docsify
Generate documentation websites from Markdown files
TLDR
Initialize a new documentation in the current directory
Initialize a new documentation in the specified directory
Serve local documentation on localhost:3000 with live reload
Serve local documentation on localhost at the specified port
Generate a sidebar markdown file in the specified directory
SYNOPSIS
docsify serve [path] [options]
Alternatively, if docsify-cli is not globally installed:
npx docsify-cli serve [path] [options]
PARAMETERS
[path]
Optional. The directory to serve. Defaults to the current working directory ('.'). This directory should contain your Markdown files and an 'index.html' file.
-p, --port <port>
Specify the port to listen on. Defaults to 3000.
-o, --open
Open the browser automatically after starting the server.
-H, --hostname <hostname>
Specify the hostname to listen on. Defaults to 'localhost'.
-b, --base-path <path>
Set the base path for relative URLs. Useful when serving from a subdirectory.
-l, --lr
Enable live reload. Note: This is often enabled by default or deprecated in newer versions as live reloading is built-in.
-c, --config <file>
Specify a custom configuration file for docsify. Defaults to '.docsify.js'.
-d, --index <file>
Specify the main HTML file to serve. Defaults to 'index.html'.
DESCRIPTION
docsify is a lightweight, client-side documentation generator that directly serves Markdown files as a dynamic single-page application (SPA).
Unlike traditional static site generators (SSGs) that pre-build HTML files, docsify generates your documentation website on the fly, rendering Markdown content directly in the browser. This means there's no complex build process; you simply point docsify to a directory containing your Markdown files, and it creates a navigable documentation site instantly.
It's commonly used for project documentation, API docs, or any content that benefits from being quickly published and updated. Key features include a real-time search plugin, theme customization, syntax highlighting via Prism.js, and support for a variety of plugins to extend functionality. The core command for local development and serving is docsify serve, typically run via npx docsify-cli serve or after global installation of the docsify-cli package.
CAVEATS
docsify requires Node.js and npm (or yarn) to run, as it is a Node.js application, not a native Linux executable. It generates documentation client-side, meaning it requires JavaScript to be enabled in the user's browser. It is a development server; for production deployment, it often requires serving the generated `index.html` and markdown files from a static file server or CDN. It does not produce static HTML output in a build directory like traditional SSGs; it serves content dynamically.
INSTALLATION
To use the docsify serve command, you first need to install the docsify-cli package globally using npm or yarn:
npm i docsify-cli -g
or
yarn global add docsify-cli
Alternatively, you can use npx to run it without a global installation: npx docsify-cli serve.
BASIC USAGE EXAMPLE
1. Create a directory for your documentation:
mkdir my-docs && cd my-docs
2. Initialize docsify (creates index.html and .nojekyll):
docsify init .
3. Create your first Markdown file (e.g., README.md):
echo '# Hello Docsify!' > README.md
4. Serve your documentation:
docsify serve
This will start a local server, usually on http://localhost:3000, and open your browser to view your documentation.
HISTORY
docsify was created by Qin Guan (QSCTech) and first released in 2016. Its development was driven by a desire for a simple, client-side documentation generator that didn't require a complex build step, differentiating itself from existing static site generators. It quickly gained popularity for its ease of use and ability to render Markdown on-the-fly, making it ideal for quick documentation setups and single-page documentation sites.