Hostingheaderbarlogoj
Join InMotion Hosting for $3.49/mo & get a year on Tuts+ FREE (worth $180). Start today.
Advertisement

Quick and Easy Documentation Using Markdown

by

So you’ve created an awesome theme, template or web application. Now for the tedious part; the documentation. Writing the content won't necessarily be that problematic, it's more likely creating the help files which will take up precious time. Markdown, a lightweight and *really* simple formatting syntax can solve all that for you.

About Markdown

Created by John Gruber, Markdown is a plain text formatting syntax which makes creating basic HTML elements a lot easier.

Instead of using HTML tags (which, relatively speaking, take a lot of time to write) Markdown’s job is to get out of the way of your thought process, allowing you to focus on content. Because the syntax is so basic, it's easy to both write and read Markdown. Later on in this tutorial, we'll walk through the steps of creating theme documentation using Markdown, so you'll see just how lightweight and fast it is!

Converting Markdown

Once you've gotten to grips with writing Markdown, you'll need some kind of parsing application to convert your Markdown into HTML markup.

The original Markdown converter was created in Perl, but since then many applications (across multiple platforms) have popped up. Let's look at some of the options, both online and run on your own system.

Dingus (Online)

Dingus is a web application created by the same people who brought you Markdown. Simply copy and paste your Markdown code from a text editor (or enter it in the text area) and with a click of a button, your HTML code (as well as a preview) will appear. Nothing fancy, but a simple way to convert Markdown into HTML.

Dingus

MarkdownPad (Windows)

MarkdownPad is a great Windows application that allows you to easily create Markdown files (and it's free!) It includes awesome features like instant HTML preview, easy formatting with keyboard shortcuts, CSS customization, HTML export and even a "distraction free" mode.

MarkdownPad

Mou (OS X)

Mou is a great, free Mac application which allows you to write Markdown in a simple and beautiful manner. It has great features such as custom styling, keyboard shortcuts, live HTML, HTML export (with optional CSS styling), PDF export, dictation support, and more. For this tutorial, we are going to be using Mou to create our theme’s documentation.

Mou

MarkdownNote (OS X & iOS)

MarkdownNote is another great application to write Markdown, and the iOS application is perfect if you want to write Markdown on the go. Just like the other applications we've covered it has some great features, including live HTML preview, keyboard shortcuts, and Dropbox syncing.

MarkdownNote

Creating Theme Documentation

So far, we've covered what Markdown is and looked up some tools you can use to write Markdown. Now let's create some theme documentation for a non-existent theme, covering what you should typically include in documentation, the Markdown syntax and best practices.

Markdown Syntax

During the following steps we'll be looking at Markdown as it applies to our needs. For a more in-depth look at the Markdown syntax, check out Markdown: The Ins and Outs over on Nettuts+.

What Should a Documentation File Include?

Because you already know the in's and out's of your theme/template/web application, it might seem a little tedious to cover the basics. The purpose of a documentation file is to serve as a guide to other users and buyers. Often, there's installation, customization, and some tweaking involved that users will need to know about - and it's your job to educate them. This is what we might want to include:

  • Information
    • Author
    • Creation Date
    • Version
    • Contact Info.
  • File Structure
    • HTML
    • CSS
    • Javascript
  • Individual File Structure
    • HTML Structure
    • CSS Structure
  • Custom Styles
  • Tweaking Files
    • Tweaking CSS
    • Tweaking Javascript
  • Browser Compatibility
  • Changelog

Remember, documentation should be simple enough for anyone with basic knowledge to understand, but also cover how to change important files. For example, you don’t necessarily have to show how to change specific CSS values, but you should show how to access these files.

Step 1: Setting up the Markdown File

Now it's time for the fun stuff! Go ahead and open your Markdown editor (I'll be using Mou for Mac). Create a header for your documentation file:

#Theme Documentation

Heading elements can be written simply by adding one to six #'s in front of the content. In the above example, we used one # sign to create an h1 element with the text 'Theme Documentation'. If you want to create an h3 element, you'd write ###Heading 3.

Now, let's create a horizontal rule (<hr />) to separate the title from the other content. Again, in Markdown this is extremely simple:

***

Step 2: Theme Information

An important section to add within your documentation is an information section.

*Theme Name:* Theme
*Author:* Suhail Dawood
*Created:* 08/08/2012
*Version:* 1.0.1
***
Thank you for your purchase! If you have any questions about this theme, feel free to e-mail me at **email@tutsplus.com** or tweet me **@tutsplus**
***

Let's take a look at the HTML equivalent of the above Markdown code:

<em>Theme Name: </em>Theme<br />
<em>Author: </em>Suhail Dawood<br />
<em>Created: </em>08/08/2012<br />
<em>Version: </em>1.0.1<br />
<hr />
Thank you for your purchase! If you have any questions about this theme, feel free to e-mail me at <strong>email@tutsplus.com</strong> or tweet me <strong>@tutsplus</strong>
<hr />

Just from looking at the two different sources, you can instantly see that Markdown is much more intuitive to understand and create. Instead of constantly having to add <'s and >'s, Markdown allows you to focus on the content. To emphasize, add an asterisk before and after the text (e.g. *Emphasized Text*). To embolden, add two asterisks before and after the text (e.g. **Emboldened Text**). To add a line break, simply add two spaces at the point you want to insert a line break.

Step 3: Adding a Table of Contents

Now let's add a list of contents into our Markdown file:

##Table of Contents
1. HTML Structure
2. CSS Files
3. Javascript Files
4. PSD Files
5. Theme Styles
6. Tweaking Javascript
7. Tweaking CSS
8. Browser Compatibility
***

If we were to create this in HTML, here is how it would appear:

<h2>Table of Contents</h2>
<ol>
   <li>HTML Structure</li>
   <li>CSS Files</li>
   <li>Javascript Files</li>
   <li>PSD Files</li>
   <li>Theme Styles</li>
   <li>Tweaking Javascript</li>
   <li>Tweaking CSS</li>
   <li>Browser Compatibility</li>
</ol>
<hr />

Instead of having to create an ordered list and separate list items, simply write 1. First Element and continue to add incremented items.

Step 4: HTML Structure

It is important to let your users how the site's files are laid out. Since we are creating documentation for a theme, we should outline how the HTML code of the theme is structured. We can outline this with the following code:

##1. HTML Structure
The HTML Structure for each page is as follows:

* Meta
* Link to CSS Files
* Header
	* Logo
	* Social Links
* Navigation
* Main Content
	* Content Slider
	* Articles
* Sidebar
	* Search
	* Post Archives
	* Mailing List
* Link to Javascript Files
* Javascript
***

Simple. To create our table of contents, we used an ordered list. In this section, we used nested unordered lists. To create an unordered list in Markdown, simply add an asterisk and a space before the text (e.g. * Item 1). To nest list items, just indent inwards and create another list item.

Step 5: CSS Files

Particularly in themes, CSS documentation is very important. It's a good idea to outline the different CSS files that are included in the theme, as well as a brief description of each file:

##2. CSS Files
There are 3 CSS files in this theme:

* main.css
* colors.css
* skeleton.css

#####main.css
This CSS file is the main stylesheet for the theme. It holds all the values for the different elements of theme and the default color scheme.
#####colors.css
This CSS file holds the styling of all the other colors schemes that are included in the theme.
#####skeleton.css
This CSS file allows the theme to be responsive, adapting to different screen sizes. 
***

Make sure to use headings to separate different sections of the documentation file. A nicely laid out documentation file will lead to fewer confused users!

Step 6: Javascript Files

If your theme includes Javascript files, it's a good idea to at least outline them in the documentation:

##3. Javascript Files
There are 2 Javascript files in this theme:

* jquery.js
* slider.js

#####jquery.js
This theme uses the jQuery Javascript library.
#####slider.js
The content slider in the theme runs on this Javascript file. There are some settings that can be tweaked, this will be covered in the 'Tweaking Javascript' section.
***

Make sure you not only list, but describe the files in your theme. This will make it a lot easier for the user to understand the contents of each file, and decide whether or not they want to mess about with it.

Step 7: PSD Files

Even though there is a separate section for PSD templates on ThemeForest, many authors decided to include PSD files with their coded templates to allow the user the freedom to make design changes. If your theme has PSD files included, it might be a good idea to outline them just as we've done with all the other files:

##4. PSD Files
Included in this theme is 5 different PSD files:

1. homepage.psd
2. about.psd
3. portfolio.psd
4. blog.psd
5. contact.psd

These PSD files will be handy if you would like to make any changes to the theme's design. You can also create a new page layout using the existing PSD files as a base to work with.
***

It's best practice to name your PSD files clearly (e.g. full-width-page.psd) as opposed to vague names (e.g. template-003.psd). This way, users can find what they need without having to open each file up.

Step 8: Theme Styles

Most likely, your theme will include a selection of color schemes for your users to choose from. If this is the case, make sure that you outline how this is done:

##5. Theme Styles
Included with this theme are 10 different theme styles:

1. Light
2. Dark
3. Grey
4. Green
5. Red
6. Orange
7. Blue
8. Purple
9. Brown
10. Dark Blue

To change these styles, go to the WordPress backend, select **Options > Styles** and select the style you would like.
***

In the example above, I've listed the different color schemes included in the theme and showed how to go about changing them.

Step 9: Tweaking Javascript

If your code includes Javascript files that have customization parameters (e.g. a slider script), it would be a good idea to show your users how to manipulate these values:

##6. Tweaking Javascript
The content slider in the theme runs off of slider.js, and there are a couple of values that can be changed to alter the look and feel of the slider.
#####Changing Values
In slider.js, you can alter these values:

<code>auto: true</code>  
*Boolean: Animate automatically, true or false*  

<code>speed: 1000</code>  
*Integer: Speed of the transition, in milliseconds*


<code>pager: true</code>  
*Boolean: Show pager, true or false*  

<code>nav: false</code>  
*Boolean: Show navigation, true or false*  
***

The above code outlines how a user can change values. To style code, wrap the relevant text within <code> tags. Applications like Mou add styling to these elements in the live preview, and you can also export the code to keep the styling. We will talk a little about exporting your documentation later on.

Step 10: Tweaking CSS

CSS files are very often customized by a user. They will certainly consider it helpful if you add a section to the documentation showing how to access the CSS files so that they can edit them.

##7. Tweaking CSS
The theme is build on a responsive framework, which allows content to be seen optimally on all screen sizes.
#####Changing the CSS
Start off by going into the WordPress backend, **Themes > Theme > View Source**. Select the *style.css* file to view and have the ability to edit the code.

Here, you can change things like the fonts, sizes, colors, etc.
***

Now that the user has access to the CSS file, they can make the changes that they want.

Step 11: Browser Compatibility

It's a good idea to notify the user of any browser compatibility issues:

##8. Browser Compatibility
This theme works well (-) or great (X) in the following browsers:

**IE 6-8** -  
**IE 9+** X  
**Chrome** X  
**Firefox** X  
**Safari** X  
**Opera** X
***

If you would like to expand on this section, you could explain which features of the theme suffer in certain browsers.

Step 12: Finishing Up the Documentation

To complete our documentation, we'll add a section to let our users know how to contact us if they have any further questions. Let's add this bit of code:

####Theme by Suhail Dawood
If you have any other questions that aren't covered in the documentation, feel free to e-mail <email@tutsplus.com> or add a new post on the [forum](http://forum.tutsplus.com/ "visit the forum").

To link e-mails using markdown, just wrap your e-mail address between chevrons (e.g. <email@tutsplus.com>).

Adding links in Mardown is quite straight forward. <a href="http://tutsplus.com" alt="The World's Leading Tutorial Network">Tuts+ is the hyperlink as you want it to appear in the HTML. The text should be placed within square braces [Tuts+]. Immediately following, you have the website address wrapped between parentheses (e.g. (http://www.tutsplus.com/)) and the alt text is placed in double quotes within the parentheses (e.g. (http://www.tutsplus.com/ "The World's Leading Tutorial Network")).

Final Markdown Code

Here is a look at our final Markdown code for this documentation:

#Theme Documentation
***
*Theme Name:* Theme  
*Author:* Suhail Dawood  
*Created:* 08/06/2012  
*Version:* 1.0.1  
***
Thank you for your purchase! If you have any questions about this theme, feel free to e-mail me at **email@tutsplus.com** or tweet me **@tutsplus**
***
##Table of Contents
1. HTML Structure
2. CSS Files
3. Javascript Files
4. PSD Files
5. Theme Styles
6. Tweaking Javascript
7. Tweaking CSS
8. Browser Compatibility
***
##1. HTML Structure
The HTML Structure for each page is as follows:

* Meta
* Link to CSS Files
* Header
	* Logo
	* Social Links
* Navigation
* Main Content
	* Content Slider
	* Articles
* Sidebar
	* Search
	* Post Archives
	* Mailing List
* Link to Javascript Files
* Javascript
***
##2. CSS Files
There are 3 CSS files in this theme:

* main.css
* colors.css
* skeleton.css

#####main.css
This CSS file is the main stylesheet for the theme. It holds all the values for the different elements of theme and the default color scheme.
#####colors.css
This CSS file holds the styling of all the other colors schemes that are included in the theme.
#####skeleton.css
This CSS file allows the theme to be responsive, adapting to different screen sizes. 
***
##3. Javascript Files
There are 2 Javascript files in this theme:

* jquery.js
* slider.js

#####jquery.js
This theme uses the jQuery Javascript library.
#####slider.js
The content slider in the theme runs on this Javascript file. There are some settings that can be tweaked, this will be covered in the 'Tweaking Javascript' section.
***
##4. PSD Files
Included in this theme is 5 different PSD files:

1. homepage.psd
2. about.psd
3. portfolio.psd
4. blog.psd
5. contact.psd

These PSD files will be handy if you would like to make any changes to the theme's design. You can also create a new page layout using the existing PSD files as a base to work with.
***
##5. Theme Styles
Included with this theme are 10 different theme styles:

1. Light
2. Dark
3. Grey
4. Green
5. Red
6. Orange
7. Blue
8. Purple
9. Brown
10. Dark Blue

To change these styles, go to the WordPress backend, select **Options > Styles** and select the style you would like.
***
##6. Tweaking Javascript
The content slider in the theme runs off of slider.js, and there are a couple of values that can be changed to alter the look and feel of the slider.
#####Changing Values
In slider.js, you can alter these values:

<code>auto: true</code>  
*Boolean: Animate automatically, true or false*  

<code>speed: 1000</code>  
*Integer: Speed of the transition, in milliseconds*


<code>pager: true</code>  
*Boolean: Show pager, true or false*  

<code>nav: false</code>  
*Boolean: Show navigation, true or false*  
***
##7. Tweaking CSS
The theme is build on a responsive framework, which allows content to be seen optimally on all screen sizes.
#####Changing the CSS
Start off by going into the WordPress backend, **Themes > Theme > View Source**. Select the *style.css* file to view and have the ability to edit the code.

Here, you can change things like the fonts, sizes, colors, etc.
***
##8. Browser Compatibility
This theme works well (-) or great (X) in the following browsers:

**IE 6-8** -  
**IE 9+** X  
**Chrome** X  
**Firefox** X  
**Safari** X  
**Opera** X
***
####Theme by Suhail Dawood
If you have any other questions that aren't covered in the documentation, feel free to e-mail <email@tutsplus.com> or add a new post on the [forum](http://forum.tutsplus.com/ "visit the forum").

Exporting the Documentation

Now that we've completed creating out documentation file, it's time to convert that Markdown into HTML or a PDF file. I'll be using Mou to export my documentation, but the steps are general and apply to most applications.

Mou

Exporting to HTML

To export your documentation to HTML, simply select File > Export > HTML. Name your documentation file and check/uncheck the 'Include CSS' depending whether or not you want the same styling shown in the application to be applied to your HTML file. Mou won't create a separate CSS file, but instead adds the styling to the HTML file. Mou also creates the necessary tags such as html,doctypehead, etc.

Exporting to PDF

If you would like to export your documentation to PDF, select File > Export > PDF. In the case of Mou, all styling shown in the HTML live preview will be included in the PDF file.

And we're done! Crystal clear, readable documentation for clients, customers and colleagues. Download the source files for this tutorial and check out the resultant .md .html and .pdf files.

Overview of Markdown Syntax

Here's a quick comparison of the HTML and Markdown syntax that we covered in this tutorial

<h1>Heading One</h1> #Heading One
<h2>Heading Two</h2> ##Heading Two
<h3>Heading Three</h3> ###Heading Three
<h4>Heading Four</h4> ####Heading Four
<h5>Heading Five</h5> #####Heading Five
<h6>Heading Six</h6> #######Heading Six
<hr /> ***
<em>Emphasized Text</em> *Emphasized Text*
<strong>Emboldened Text</strong> **Emboldened Text**
<ol><li>List Element</li></ol> 1. List Element
<ul><li>List Element</li></ul> * List Element
<code>Code</code> <code>Code</code>
<a href="mailto:email@tutsplus.com">
email@tutsplus.com</a>
<email@tutsplus.com>
<a href="http://www.tutsplus.com/" alt="Description">forum</a> [forum] (http://www.tutsplus.com/ "Description")

Additional Resources