Programster's Blog

Tutorials focusing on Linux, programming, and open-source

Getting Started With Docsify

Docsify is a neat tool that will convert your folder of markdown files into a slick web-based documentation service.

To make it easy to host your own Docsify server, I Dockerized it so that it is really quick and easy to deploy your own documentation server.

Deploy

Clone the project and run the following commands:

docker-compose build
docker-compose up

You will need to have installed Docker and docker-compose.

Themes

In my dockerized version, I have provided an index.html.sample file which contains various sources for CSS for Docsify themes. Simply rename the index.html.sample file to index.html, and uncomment the theme you want, ensuring only one theme is uncommented at a time.

Sidebar

By default, docsify will just create a sidebar that shows content with items related to your headers in your *README.md` file. However, you probably want to create some more pages and have the sidebar show both these pages, and the subheadings within them when you are on that page. Luckily it is easy enough to set this up.

First create a _sidebar.md file with links to your other pages. They must have the correct relative paths. E.g. if I have the following files in my docs folder:

  • README.md
  • Page1.md
  • subfolder/Page2.md

Then my _sidebar.md file will need to look like this:

* [Home](/)
* [Page 1](Page1.md)
* [Page 2](subfolder/Page2.md)

If using GitHub pages, you would need to create a .nojekyll file to have GitHub pages not ignore files beginning with an underscore, but that won't matter here if you are deploying with Docker.

Now configure docsify with loadSidebar: true and subMaxLevel set to at least 2 in your index.html file like below:

<script>
window.$docsify = {
  name: 'My Project',
  repo: '',
  loadNavbar: true,
  loadSidebar: true,
  subMaxLevel: 3
}
</script>

You should now have a working sidebar, that will track you appropriately throughout your pages, and dynamically expanding to show the headings for the page that you are currently viewing.

Syntax

There are a few syntaxes that I have not come across in traditional Markdown that Docsify support that I am putting below:

Notice

To create a notice, do something like:

Lorem ipsum dolor sit amet. 

?> This is a notice message.

To create a warning, do:

Lorem ipsum dolor sit amet. 

!> This is a warning message.

Relative Path To Asset

If you wish to link off to a file in order to download it, then you will need to add :ignore to your link like below:

[my-file-to-download.zip](/my-file.zip ':ignore')

References

Last updated: 23rd April 2021
First published: 21st April 2021