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:

Create A Notice

To create a notice, do something like:

Lorem ipsum dolor sit amet. 

?> This is a notice message.

Create A Warning

To create a warning, do:

Lorem ipsum dolor sit amet. 

!> This is a warning message.

Link To To Asset To Download

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 Image](/my-image.png ':ignore')

You can even specify a target to make it open in another tab:

[My Image](/my-image.png ':ignore :target=_blank' )

Linking To Section In Page

If you wish to link to a somewhere within a page, then you can simply use the id of the title like so:

[some text for link](#id-of-title)

For example, if you have the following content:

# Primary Title
some text here.

## Secondary Title
some text here.

### Tertiary Title
some text here.

Then the titles would get translated to the following IDs

• primary-title
• secondary-title
• tertiary-title

... and one can then link to those titles using the following codes:

• [primary](#primary-title)
• [secodary](#secondary-title)
• [tertiary](#tertiary-title)

Docsify takes care of manipulating the links to work, and translating to #/{page-name}?id=primary-title etc.

If that wasn't clear, refer here.

Customizing ID

Below is an example, where we manually set the ID of this h3 element to hello-world.

### Hello, world! :id=hello-world

References

• Docsify Docs
• DocisfyJS Issues - Embedded files doesn't resolve relative links #865