Creating a Simple Documentation Site in Markdown

When my last employer gave me permission to spend some time documenting our code, I spent a bit of time casting around for the most convenient way to do that. The procedure I developed for writing documentation uses the same tools I use for writing software, and it’s proving itself useful for the notes I’m taking at Viking Code School.

Documenting code has its own set of feature requirements. Certain formatting features like “smart quotes” that are helpful in some contexts are a huge pain when you’re trying to copy-and-paste code. But plaintext isn’t good enough either; we need to be able to create headings and links and distinguish code keywords from regular writing. Markdown is the best compromise I’ve yet found: you write it in plaintext, indicate formatting by adding characters **like so**, and that gets turned into the formatting you want when the Markdown is rendered. Code blocks are fenced off with a line of three backticks, so any underscores or asterisks in your code won’t be misinterpreted as formatting.

The goal of this post is to create a static site that can be easily updated by editing Markdown. There are lots of static site builders out there; I use Harp because it works right out of the box, with no configuration required. You’ll need a working knowledge of Git and Markdown, a GitHub account, and NodeJS installed on your machine.

First, install Harp by running npm install -g harp. Create a repository on GitHub and clone it down to your computer.

In the repository, create a file called index.md; this will be the front page of your new site.

Run harp server in the repo folder, then open your browser and navigate to localhost:9000. The text you wrote appears! You can use this to preview your site before publishing it.

Now go back to your console, press Ctrl-C to stop the server, and run harp compile. Harp will compile the Markdown you’ve written into HTML and place it in a folder called “www”. (You should never edit the contents of “www” directly, since any changes you make will be overwritten the next time you run harp compile.)

So now you have some HTML; you just need to host it somewhere. GitHub Pages is great for this purpose. Commit the changes you’ve made and push them up to GitHub. Then, on GitHub, go into the settings for your repo, look for the GitHub Pages section, change “Source” from “None” to “master branch”, and click Save. Go get a sandwich—there’s no progress indicator, but it sometimes takes a couple minutes for new sites to get set up.

When you get back, your new site should be ready. Here’s the formula for its address: <your GitHub username>.github.io/<repo name>/www/

You are now the proud owner of a little site! It doesn’t do much yet, but you can expand outward from here.

Let’s do a few quick things to improve the site’s appearance. I want to add a layout file that will provide some basic CSS to each page of my site.

Create a file named _layout.ejs in the root folder. This is a template file that each of our Markdown files will be inserted into when Harp renders/compiles our site.

As you can see, this is mostly standard HTML. I’m just pulling in the files required for Bootstrap, creating a container for our content, and then (on line 15) inserting the Markdown. You can do whatever you want here and it will be applied to every page of your site. More information is available in Harp’s documentation.

There’s one more thing I’d like to do here, specifically because I’m documenting code. Code is easier to read with good syntax highlighting! There’s a great library called highlight.js that will do this for us with just a few more lines in our template file.

That allows for this result:

There’s a lot this site doesn’t have yet, like navigation, but this will get you started. Here’s the finished repo.

Has anyone found a better solution for writing about code?

--

--

It will get better.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store