LinuxCommandLibrary

docsify

Generate documentation websites from Markdown files

TLDR

Initialize a new documentation in the current directory

$ docsify init
copy

Initialize a new documentation in the specified directory
$ docsify init [path/to/directory]
copy

Serve local documentation on localhost:3000 with live reload
$ docsify serve [path/to/directory]
copy

Serve local documentation on localhost at the specified port
$ docsify serve --port [80] [path/to/directory]
copy

Generate a sidebar markdown file in the specified directory
$ docsify generate [path/to/directory]
copy

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.

SEE ALSO

npx(1), npm(1), yarn(1), mkdocs(1), hugo(1), jekyll(1)

Copied to clipboard