7 days of unlimited WordPress themes, plugins & graphics - for free!* Unlimited asset downloads! Start 7-Day Free Trial
  1. Web Design
  2. Workflow

Quick and Easy Documentation Using Markdown

Scroll to top
Read Time: 16 mins

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.


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.


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.


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.


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:

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.

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

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:

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

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:

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:

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:

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:

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:

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:

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.

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:

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:

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:

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.


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">
<a href="http://www.tutsplus.com/" alt="Description">forum</a> [forum] (http://www.tutsplus.com/ "Description")

Additional Resources

Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Web Design tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.