Docsify – what is it?

Docsify is a documentation site generator, but not in the traditional sense. Normally, a site generator, commonly known as a static site generator, involves downloading and installing some software. Then you have to configure it – templates, config files, etc. – adding your instructions and uploading the documents, whether directly or via GitHub or similar, to your server. Sounds like a bit of a pfaff to me.

Docsify does away with most of this. Unlike a traditional static site generator, it does not generate static html files. Instead, it loads and parses your markdown files and displays them as a website.

Here is how it works.

The install is quite straightforward. It is recommended to install docsify-cli globally, which helps to initialise and preview the website locally. Open Terminal, or your command line interface, and type:

npm i docsify-cli -g

Then, if you want to write the documentation in the ./docs subdirectory, use the init command.

docsify init ./docs

After the init is complete, you can see the following file list in the ./docs subdirectory.

• index.html is the entry file
• README.md is the homepage
• .nojekyll, which prevents GitHub Pages from ignoring files that begin with an underscore.

You can update the documentation in ./docs/README.md and, of course, you can add more pages. Then preview your site by running the local server with docsify serve and view it at http://localhost:3000.

docsify serve docs

And this, or similar, is what you get. All I did was add an ‘About’ page and linked to it from the homepage (README.md).

You can then deploy it on GitHub Pages, share your thoughts with your ‘team’, incorporate any changes they suggest, then upload it to the world.

There are many other things you can do with Docsify, such as adding a sidebar and changing themes. The docs provide you with a full explanation of how to use Docsify.