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:

<code># Modify npm global install path
npm config set prefix "D:\developer\env\node-v12.14.0\node_global"
# Modify npm cache path
npm config set cache "D:\developer\env\node-v12.14.0\node_cache"
</code>

Add the system environment variable

NODE_PATH

:

<code>NODE_PATH = D:\developer\env\node-v12.14.0
</code>

Append the following paths to the

Path

variable:

<code>%NODE_PATH%
%NODE_PATH%\node_global\
</code>

Install docsify‑cli

After installing Node.js, run:

<code>npm i docsify-cli -g
</code>

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):

<code>docsify init ./docs
</code>

The basic directory structure will be:

<code>- docs/
  - .nojekyll
  - index.html
  - README.md
</code>

Live Preview

To preview the site locally, run:

<code>docsify serve docs
</code>

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:

<code><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>
</code>

Create

docs/_sidebar.md

with the desired outline, for example:

<code>* 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)
</code>

Customize Navbar

Enable a top navigation bar by adding to

index.html

:

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

Create

_navbar.md

with links, for example:

<code>* 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)
</code>

Customize Cover Page

Enable a cover page by adding to

index.html

:

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

Create

_coverpage.md

with markdown such as:

<code>![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)
</code>

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:

<code><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>

Code Highlighting

Include Prism language scripts in

index.html

for Java, SQL, Bash, YAML, XML, etc.

<code><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>
</code>

Copy Code Button

Add the copy‑code plugin script:

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

Change Theme

Replace the default theme by adding the following link in the

head

of

index.html

:

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

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/