My Documentation

The need for great documentation can never be underestimated. Clear concise step by step instruction is the difference between a happy customer and a frustrated one.

Providing good documentation can save you countless hours in support, allowing you to get on with producing your amazing products.

This is where Dox comes in, Dox is a simple to use documentation template, giving you a huge head start in producing your documentation. all you have to do is create sections and fill in your instructions. If you want to change the look and feel of Dox a set of handy CSS variables allow you to alter colours, fonts and other commonly used attributes.

Can I use Dox

Dox is written in good'ol HTML and CSS with a splash of jQuery, if you have a basic understanding of HTML and CSS you are good to go, there shouldn't be any need to touch the jQuery.

Working with Dox

After your file has downloaded, open the zip file, you should see a folder called documentation inside this folder you should see one file index.html and one folder assets drag or open the documentation folder into your favourite text editor to begin using Dox.

In the index.html file on or around 35 you should see the start of the navigation it will look like the code below:

    
<div class="navigation-sidebar">
    
    <nav>
            
        <ul class="navigation">

                    
            <li class="navigation-item">
                        
                <a href="#top">Home</a>

            </li>
  

            <li class="navigation-item">
                        
                <a href="#section-1">A navigation link</a>
                    
            </li>


            <li class="navigation-item">
                        
                <a href="#section-2">A navigation link</a>
                    
            </li>
      

            <li class="navigation-item">
                        
                <a href="#section-3">A navigation link</a>

            </li>


            <li class="navigation-item">
                        
                <a href="#section-4">A navigation link</a>

            </li>
    

            <li class="navigation-item">
                        
                <a href="#section-5">A navigation link</a>

            </li>

  
        </ul>
            
    </nav>
  
</div>
    

Delete A Navigation link and write a new description of the section you wish to link to, for example Theme setup

Note the anchor tag has a hashed link #section-1 this is used to jump to the id of the section you are linking to.

To create a new navigation item simply copy an existing navigation item and paste it into the navigation ul remembering to change the hashed link to match the section you wish to jump to.

In your index.html file on or around line 69 you should see the start of the documentation sections.

    
<!--  ==============================

START OF SECTION

==============================  -->


    <section class="docs-section" id="section-5">


        <header class="docs-section__header">
        
            <h2>Sections</h2>
        
        </header>


            <!--  ==============================

            PLACE YOUR CODE BENEATH THIS COMMENT

            ==============================  -->



            <!--  ==============================

            PLACE YOUR CODE ABOVE THIS COMMENT

            ==============================  -->


        <footer class="docs-section__footer">

            <a href="#section-5">Top of section</a>

        </footer>



    </section>


<!--  ==============================

END OF SECTION

==============================  -->
    

You should change the id of the section to match the id you specified in the navigation item that jumps to this section, in the above example id="section-5" would match to navigation link <a href="#section-5">Sections</a>

Once you have a working link to your section you can begin to add your content. In the middle of the section there are 2 comments PLACE YOUR CODE BENEATH THIS COMMENT and PLACE YOUR CODE ABOVE THIS COMMENT you should start to write your content in between these 2 comments.

Once you have completed a section and you wish to start a new section simply copy the code below or duplicate an existing section and paste it after the last END OF SECTION comment. Remember to update the link in the section footer and the section itself with your new navigation id.

    
<!--  ==============================

START OF SECTION

==============================  -->


    <section class="docs-section" id="section-">


        <header class="docs-section__header">
        
            <h2>Sections</h2>
        
        </header>


            <!--  ==============================

            PLACE YOUR CODE BENEATH THIS COMMENT

            ==============================  -->



            <!--  ==============================

            PLACE YOUR CODE ABOVE THIS COMMENT

            ==============================  -->


        <footer class="docs-section__footer">

            <a href="#section-">Top of section</a>

        </footer>



    </section>


<!--  ==============================

END OF SECTION

==============================  -->
    

Dox has a selection of alerts you can use to draw attention to parts of your documentation that need more focus, there are three degrees of severity, danger, warning and success.

Danger alert

This could get you into a whole lot of wrong..... are you sure?

    
<p class="alert danger">

	This could get you into a whole lot of wrong..... are you sure?

</p>
    

Warning alert

This has the potential to go south..... are you sure?

    
<p class="alert warning">

	This has the potential to go south..... are you sure?

</p>
    

Success alert

This is totally safe, go right ahead.

    
<p class="alert success">

	This is totally safe, go right ahead.

</p>
    

Dox features a class to highlight text, you may wish to use the text highlight to focus on pertinent info, paths, folders etc. To add a text highlight simply wrap a word or line of text in a span with the class highlight

<span class="highlight">highlight</span>

Dox can give your images a little style treatment, simply wrap your images in a div with the class image

Wrapping your images in this way is purely optional, it just gives some continuity to your imagery.

Photo by Luke Chesser on Unsplash.

    
<div class="image">

    <img src="assets/img/sample-image.jpg" alt="Computer on a wooden desk">

</div>
    

Dox comes with a way to highlight any process which you want to explain in steps. Simply create a paragraph tag with the class step

Step 1 - Getting started

    
<p class="alert step">

   Step 1 - Getting started

</p>
    

Sometimes you may have a long list of options that need a brief description but a complete section is overkill, this is where a nicely formatted table comes in. Add a class of table to a table element.

    
<table class="table">
            
    <tr>
                
        <th class="bold dark">Option</th>
                
        <th class="bold dark">Function</th> 
                
        <th class="bold dark">ID</th>
            
    </tr>
            
    <tr>
                
        <td>option 1</td>
                
        <td>Lorem ipsum dolor sit amet, consectetur adipisicing elit</td> 
                
        <td>50</td>
            
    </tr>
            
    <tr>
                
        <td>option 2</td>
                
        <td>Lorem ipsum dolor sit amet, consectetur adipisicing elit</td> 
                
        <td>49</td>
            
    </tr>
            
    <tr>

        <td>option 3</td>
                
        <td>Lorem ipsum dolor sit amet, consectetur adipisicing elit</td> 
                
        <td>48</td>

    </tr>
            
    <tr>
                
        <td>option 4</td>

        <td>Lorem ipsum dolor sit amet, consectetur adipisicing elit</td> 
                
        <td>47</td>
            
    </tr>
            
    <tr>
                
        <td>option 5</td>
                
        <td>Lorem ipsum dolor sit amet, consectetur adipisicing elit</td> 
                
        <td>46</td>

    </tr>
            
    <tr>
                
        <td>option 6</td>

        <td>Lorem ipsum dolor sit amet, consectetur adipisicing elit</td> 

        <td>45</td>

    </tr>
            
    <tr>
                
        <td>option 7</td>
                
        <td>Lorem ipsum dolor sit amet, consectetur adipisicing elit</td> 
                
        <td>44</td>
            
    </tr>
            
    <tr>
                
        <td>option 8</td>
                
        <td>Lorem ipsum dolor sit amet, consectetur adipisicing elit</td> 
                
        <td>43</td>

    </tr>
                 
</table>

    

Code highlighting is taken care of by the Prism plugin, to include a code block add a pre tag with a code tag inside, the code tag will take the class of language postfixed by the name of the language you are using, for example language-html

    
<pre>
    
    <code class="language-html">
        

        Your HTML code as HTML entities will go here....
        
       
    </code>

</pre>
    

For more details about supported languages and about prism in general please visit the Prism website

Dox has a few utility classes for you to use, enabling you to quickly style a handful of commonly used elements.