email@encode8.com
Resources

How to Generate Documentation for Your Projects

docsify javascript plugin

Documentation is probably the most hated part of the development workflow. If you are not working on an Open Source project, chances are high you are skipping documentation. But this part of the process is as important as writing codes. Without proper documentation, you can’t reach fellow team-mates without their scornful looks. Here I am going to describe a painless way to generate documentation.

To document your projects, you can either write it by hard-coding it into html files or you can use a generator. Here, for example, we would use docsify.js, a JavaScript library that generates documentation on the fly. Instead of generating html files, docsify.js builds a snappy site from a bunch of Markdown files. Docsify also has a built-in full-text search which lets users search the entire documentation. Here is how you can drop it into your existing project by just writing a few markdown files.

Installation

Docsify comes as an npm package. You can install it with the following one-liner:

npm i docsify-cli -g

This installs docsify globally, meaning you can call docsify from anywhere. However, you can install a project dependency too. Just drop the -g and replace it with --save

Initialization

To initialize,

docsify init ./docs

This command may seem trivial but under the hood, docsify creates README.md, index.html and .nojekyll files inside docs directory. This index.html file is where the entire documentation shows up. The content of README.md shows up as the homepage.

Add Pages

Adding new pages with docsify is as simple as creating a markdown file, and that’s all. The name of the file dictates the route where the page is available. For example, if you create a file named helpers.md inside docs directory, the page can be accessed from /#/helpers.

Themes

Docsify currently supports four beautiful themes. Changing a theme is just about adding a new stylesheet to the index.html file. However, you can add new themes by modding one of the theme files.

Conclusion

For documenting your projects, docsify is definitely worth trying. Since it has almost no learning curve, documentation is fun with docsify. The extensible nature of docsify is definitely a plus — if you don’t like the theme, make one of your own.