How to Quickly Build a Docsify Documentation Site in Minutes

Previously when building a mall project documentation site, I tried several tools such as Docsify, VuePress, Hexo, and Yuque. Comparing them, Docsify is the simplest and fastest to get online, allowing a site to be launched in minutes.

Introduction

Docsify is an open‑source documentation generator with 21K+ stars on GitHub. It can quickly create a documentation website; unlike VuePress and Hexo it does not generate static .html files, performing all conversion at runtime.

Installation

Using Docsify only requires installing Node.js and the Docsify CLI tool, which is very simple.

Install Node.js

Download the Node.js installer from https://nodejs.org/dist/v12.14.0/node-v12.14.0-x64.msi .

Run the installer and follow the prompts. To change npm’s global module path and cache, run:

# Modify npm global install path
npm config set prefix "D:\developer\env
ode-v12.14.0
ode_global"
# Modify npm cache path
npm config set cache "D:\developer\env
ode-v12.14.0
ode_cache"

Add the system environment variable NODE_PATH:

NODE_PATH = D:\developer\env
ode-v12.14.0

Append the following paths to the Path variable:

%NODE_PATH%
%NODE_PATH%
ode_global\

Install docsify‑cli

After installing Node.js, run:

npm i docsify-cli -g

Usage

After the environment is set up, let’s look at how to use Docsify.

Initialize Project

Run the following command to create a new Docsify project (if the docsify command is not found, check your Node.js environment variables):

docsify init ./docs

The basic directory structure will be:

- docs/
  - .nojekyll
  - index.html
  - README.md

Live Preview

To preview the site locally, run:

docsify serve docs

The server starts quickly; the final site can be accessed at http://localhost:3000.

Customize Sidebar

The left sidebar is defined in index.html. Add the following script configuration:

<script>
  window.$docsify = {
    loadSidebar: true,
    maxLevel: 2,
    subMaxLevel: 4,
    alias: {
      '/.*/_sidebar.md': '/_sidebar.md' // prevent accidental fallback
    }
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>

Create docs/_sidebar.md with the desired outline, for example:

* Preface
  * [mall architecture overview](foreword/mall_foreword_01.md)
  * [mall learning points](foreword/mall_foreword_02.md)
* Architecture
  * [SpringBoot + MyBatis skeleton](architect/mall_arch_01.md)
  * [Swagger‑UI API docs](architect/mall_arch_02.md)

Customize Navbar

Enable a top navigation bar by adding to index.html:

<script>
  window.$docsify = {
    loadNavbar: true,
    alias: {
      '/.*/_navbar.md': '/_navbar.md' // prevent accidental fallback
    }
  }
</script>

Create _navbar.md with links, for example:

* Demo
  * [Admin](http://www.macrozheng.com/admin/index.html)
  * [Mobile](http://www.macrozheng.com/app/mainpage.html)
* Project
  * [Backend](https://github.com/macrozheng/mall)
  * [Frontend](https://github.com/macrozheng/mall-admin-web)
  * [Tutorial](https://github.com/macrozheng/mall-learning)
  * [Skeleton](https://github.com/macrozheng/mall-tiny)
* SpringCloud
  * [SpringCloud version](https://github.com/macrozheng/mall-swarm)
  * [SpringCloud tutorial](https://github.com/macrozheng/springcloud-learning)

Customize Cover Page

Enable a cover page by adding to index.html:

<script>
  window.$docsify = {
    coverpage: true
  }
</script>

Create _coverpage.md with markdown such as:

![logo](images/mall.svg)
# mall-learning
> mall learning tutorial, covering architecture, business, and technical points.

mall project (50k+ stars) is an e‑commerce system built with mainstream technologies such as SpringBoot, MyBatis, Elasticsearch, RabbitMQ, Redis, MongoDB, MySQL, and Docker.

[GitHub](https://github.com/macrozheng/mall-learning)
[Get Started](README.md)

Plugins

Docsify supports many plugins; here are some common ones.

Full‑text Search

Add the following configuration to index.html and include the plugin script:

<script>
  window.$docsify = {
    search: {
      placeholder: 'Search',
      noData: 'No results found!',
      depth: 3
    }
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>

Code Highlighting

Include Prism language scripts in index.html for Java, SQL, Bash, YAML, XML, etc.

<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-sql.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-xml.min.js"></script>

Copy Code Button

Add the copy‑code plugin script:

<script src="//cdn.jsdelivr.net/npm/docsify-copy-code@2/dist/docsify-copy-code.min.js"></script>

Change Theme

Replace the default theme by adding the following link in the head of index.html:

<head>
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
</head>

More Plugins

Docsify has many extensions; see the awesome‑docsify repository for additional plugins.

https://github.com/docsifyjs/awesome-docsify

Deployment

Deploy Docsify with Nginx by copying the docs folder into Nginx’s html directory.

Start Nginx and access the documentation via the server URL.

Conclusion

Docsify makes building documentation sites simple and fast. Compared with VuePress and Hexo, Docsify requires no compilation or packaging, updates are instantaneous, and Markdown files remain untouched. Most configuration can be done with plain Markdown, making it worth trying.

References

Official documentation: https://docsify.js.org/#/zh-cn/