Step-by-Step Guide to Setting Up a Docsify Documentation Site

Docsify is a dynamic documentation site generator that renders Markdown files at runtime without converting them to static HTML, making it ideal for quickly building small documentation sites without polluting the repository with generated files.

1. Initialize the project

Install Node.js (v8.9.4) and verify the version with node -v . Then install the docsify CLI globally using npm i docsify-cli -g , which creates a docsify-cli folder under the npm global modules path.

Create a local docs folder and run docsify init ./docs to generate the initial structure, including .nojekyll , index.html , and README.md . Edit docs/README.md to provide the homepage content.

2. Customize the navigation bar

Add a _sidebar.md file to define the sidebar menu and a _navbar.md file for the top navigation. Configure the navigation in index.html with a script block that sets window.$docsify options such as name , repo , loadNavbar , loadSidebar , maxLevel , subMaxLevel , mergeNavbar , and route alias definitions.

3. Add a cover page

Enable the cover page by adding coverpage: true to the docsify configuration and create a _coverpage.md file containing a logo, title, description, and links to the GitHub repository and the README.

4. Enable full‑text search

Configure search in the same script block with a search object specifying placeholder , noData , and depth values.

5. Add code highlighting

Include Prism.js language components for Bash, Java, and SQL by adding script tags that load the corresponding files from the CDN.

6. Add one‑click copy code

Load the //unpkg.com/docsify-copy-code script to enable a copy button on code blocks.

7. Deploy to GitHub Pages

Push the project to a GitHub repository, enable GitHub Pages in the repository settings, and access the site at https://{username}.github.io/PassJava-Learning .

8. Deploy to a cloud server

Create an Nginx configuration file (e.g., /etc/nginx/conf.d/pass_java_learning.conf ) that points the server root to the generated docs directory and set the server name to tech.jayh.club . Update DNS A records to point the subdomain to the server’s IP address.

Common issues include 404 errors caused by incorrect root paths and 403 permission errors resolved by changing the Nginx user from www-data to root and restarting the service.