Build A Documentation Site Using Markdown

May 12, 2017

When it comes to creating documentation, a plethora of solutions exist. So many that it can be difficult pick one. You could use Google Docs, WordPress, any Wiki, online documentation such as Read the Docs. I wanted something fast, searchable and easy to use. My blog uses Hugo, so I naturally decided if Hugo was suitable for building a documentation site.

Here are 5 reasons to use Hugo + docDock for your documentation.

1) Write With Markdown

Once you get used to write in Markdown, you write pretty fast. There are plenty of markdown editors, if you prefer to write using a WYSIWYG or need a side-by-side preview. Despite having a license for MarkdownPad 2, I have been quite impressed with online markdown editors such as StackEdit.

2) Version Controlled

If you plan on building your documentation site with your team, then it might be a good idea to be able to keep track of things. When was the documention last updated? Who created it? What has changed? All of those questions can be answered by Git.

3) Fast and Scalable

When it comes to performance, Hugo beats any competitors. It takes a few seconds to generate a site with 5,000 posts (video). I have been using Hugo for over a year, and it has proven to be reliable and scalable.

4) Searchable

The search feature of docDock is using Lunr which provides a great search experience. This tiny yet powerful JavaScript library works like a charm, providing instant search accross your documentation site!

5) Structure Your Documentation, Your Way

Writing good content is one. Writing good documentation is another. Without structure, your users will stuggle to find the key information they are looking for.

Hugo has a simple yet powerful menu system that permits content to be placed in menus with a good degree of control without a lot of work, in content pages.

With docdock, Each content page composes the menu, they shape the structure of your website.

Other solutions using Markdown: