How to build a docs site

#docs #site #tutorial #documentation

You've got a Github repo with a docs folder, but it is disappointingly bland. How do you make it better?

You can turn it into a docs site.

But how do you make sure to...

make pretty, professional and easy to navigate,
focus on existing markdown content without changing it much,
keep the configuration, theming and code light, and
make it easy for you and others to maintain?

So some good solutions for building a docs site that meets these requirements are Jekyll, Docsify.js and MkDocs. I compare these in this post based on my experience. They can be deployed and hosted for free on Github Pages or Netlify easily.

Summary

Name	Type	Theming	Heaviness
Jekyll	Static site	Varied but complicated to use and customize	A lot of HTML code might be needed
Docsify.js	Single-Page Application	Limited builtin choices but extendable	Some HTML boilerplate but mostly markdown. Configuration is in JS.
MkDocs	Static site	Varied and easy to switch between	Works great as all-markdown - no HTML experience needed.

MkDocs is my favorite at the moment but I way up pros and cons of each approach below.

Github Pages

There are a few places to store docs site content and presentation rules using a Github repo and Github Pages:

Content in the root (good for a standalone repo but be messy if adding docs to an existing project)
Content in docs folder (common for projects. This also keeps docs synced with the main project)
Use a separate gh-pages branch (this means code and docs can go out of sync)

Jekyll

Homepage:
- https://jekyllrb.com/

The typical Github Pages deploy is using a Jekyll-built static site. Jekyll is built on Ruby and you can extend it with HTML or even Ruby plugins.

Here is a project I made using the Jekyll quickstart guide.

I find that Jekyll is great when I am going take time to pick a theme or to build my own. Even if you pick a theme, you might still need to implement logic and boilerplate to make it multi-page, handle the navbar, make it mobile-friendly ...

I had these issues when setting up a blog using a theme picked from the Github Pages GUI. I still need to get round to make sure the navbar doesn't disappear on mobile. See Coding Blog listed below.

Coding Blog
- Site:
  - https://michaelcurrin.github.io/coding-blog/
- Repo:
  - https://github.com/MichaelCurrin/coding-blog
  - See root directory
    - Content in markdown files
    - Configure using _config.yml
    - Dependencies in Gemfile.

I don't have an example from my own projects of Jekyll used as docs a project, but that gives a good idea of structure.

It's often hard to switch themes because you have to understand what layouts and macros/includes are being used - you might even get errors if you use a layout that no longer exists. This is noticeable for example when using the Github Page settings on your repo to change theme.

Because of these reasons I find Jekyll is too heavy for a simple doc site.

There are some documentation-based themes which I've yet to try out, for anyone interested. Though you'll be locked into the theme's way of doing things and you might have to write some HTML and to do some things not covered by the theme or to implement an includes file (macro). The two non-Jekyll solutions covered below cover menus, sidebar and search with little or no code needed, while Jekyll takes more effort to make and implement these features.

https://jekyllthemes.io/jekyll-documentation-themes

Github Pages will build a Jekyll site for you or you can use Github Actions for more control such as using custom plugin versions or API calls at build time.

Docsify.js

Homepage:
- https://docsify.js.org/

Docsify runs as a Single-Page Application that turns markdown into documentation. There are no local dependencies and no build step needed - the Docsify CLI is optional but helps for local dev.

I moved to the Vue-based Docsify.js for a lot of docs sites because you don't need to be a JS or HTML developer to use it.

The content is markdown files, menus are configured with markdown and the app prettifies it, configuration is in index.html and there are 4 main themes to choose from.

And its very extendable - add plugins like search or google analytics with mostly light code changes.

Site:
- https://michaelcurrin.github.io/docsify-js-tutorial/#/
Repo:
- https://github.com/MichaelCurrin/docsify-js-tutorial/
- See /docs/ directory.

I've been running into styling issues especially on mobile. Using my own fixes or changing to Docsify Themeablr plugin can solve these issues, but that is boilerplate which needs to be maintained across projects. Compared with the solution in the next section which handles UI better.

Also Docsify themes are limited. And its not SEO friendly, so you're going to not get found in Google search results much.

MkDocs

Last option in this post and my current favorite.

Homepage:
- https://www.mkdocs.org/

A magical documentation generator.

I am getting into MkDocs - a Python-based static generator (yey for SEO!) which is similar to Docsify but you don't need to do write any HTML, CSS or JS such as with index.html page of Docsify or the Jekyll approach. You just use a light config YAML file to pick a theme and your menu. You can extend MkDocs but I'd rather keep the docs site vanilla, simple and low on code.

It is super easy to change between themes in a config option without changing your markdown or HTML files like you would have to with Jekyll.
Sometimes installing a theme is needed. Which is easy enough.

MkDocs lets you mimic the styles of Sphinx-based docs (like ReadTheDocs),
or GitBook (which is a premium site after the one free site) or Google Material...

MkDocs themes listed on the Wiki
- https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes

You do need a build and deploy step, which can be done locally or with a Github Actions action. But once you have that flow up you can deploy continuously to GH Pages like the first two doc site options. Or use Netflify - Python is supported there for builds.

Here is my project, which is a demo, template and tutorial.

Site:
- https://michaelcurrin.github.io/mkdocs-quickstart/
Repo:
- https://github.com/MichaelCurrin/mkdocs-quickstart
- Config as /mkdocs.yml.
- Content in /docs/.

Conclusion

I hope this gives you a good idea of how doc site solutions work so you can choose one that suits your needs.

Or click Use this template on the repo for all three to get them up and running yourself on Github Pages then see which you like working with most, both on the code side and frontend.