# Docsify: Self-Hosted Setup on Apache 2 A complete guide to running Docsify on Apache 2 with no external CDN dependencies. We follow the [manual creation](https://docsify.js.org/#/quickstart?id=manual-initialization) but download the JavaScript and CSS files locally so we don't have to worry if the domain cdn.jsdelivr.net get seized (who knows what's going to happen in the future). --- ## Prerequisites - Apache 2.4+ - `curl` (for downloading assets) --- ## Directory Structure The final layout this guide produces, relative to your document root: ``` ./ ├── index.html ← Docsify entry point ├── README.md ← Homepage content ├── _sidebar.md ← Sidebar navigation ├── getting-started.md ← Example page └── assets/ ├── js/ │ ├── docsify.min.js │ └── search.min.js └── css/ └── vue.css ``` All commands in this guide assume you have already `cd`'d into your document root. --- ## Step 1: Create the Directory Structure ```bash mkdir -p assets/js mkdir -p assets/css ``` --- ## Step 2: Download Docsify Assets All files are downloaded from jsDelivr once and served locally thereafter. See all [docsify CDN files](https://cdn.jsdelivr.net/npm/docsify@4/lib/) on jsDelivr. ```bash # Docsify core curl -L "https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js" \ -o assets/js/docsify.min.js # Search plugin curl -L "https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js" \ -o assets/js/search.min.js # Theme (Vue — clean, light) curl -L "https://cdn.jsdelivr.net/npm/docsify@4/themes/vue.css" \ -o assets/css/vue.css ``` ### Alternative Themes Replace `vue.css` in the command above with any of the following if preferred; see all [themes](https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/themes/). * buble.css * dark.css * dolphin.css * pure.css * vue.css ### Optional: Syntax Highlighting If your documentation includes fenced code blocks, download Prism and the language components you need: ```bash # Prism core (required) curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js" \ -o assets/js/prism-core.min.js # Language components — add as many as needed curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js" \ -o assets/js/prism-bash.min.js curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js" \ -o assets/js/prism-yaml.min.js curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-javascript.min.js" \ -o assets/js/prism-javascript.min.js ``` Then add each ` ``` > **Note:** Docsify uses hash-based routing by default, producing URLs like > `/docs/#/page-name`. This requires no Apache configuration whatsoever. --- ## Step 4: Create Boilerplate Content ### Homepage — `README.md` Docsify uses `README.md` in each directory as its index page, just like GitHub. Create `README.md`: ```markdown # Welcome This is the home page of your documentation site. Edit `README.md` to replace this content. ## Quick Links - [Getting Started](getting-started.md) ``` ### Sidebar — `_sidebar.md` The sidebar lists your pages and their navigation structure. Create `_sidebar.md`: ```markdown - [Home](/) - [Getting Started](getting-started.md) ``` Add a new `- [Title](filename.md)` entry here each time you create a new page. ### Example Page — `getting-started.md` Create `getting-started.md`: ```markdown # Getting Started This is an example page. Replace this content with your own documentation. ## Section One Write your content here using standard Markdown. ## Section Two Docsify will automatically generate sidebar anchors for H2 headings when `subMaxLevel: 2` is set in `index.html`. ``` --- ## Step 5: Set File Permissions Since you are creating these files yourself, you already own them. Just ensure they are readable by Apache: ```bash find . -type f -exec chmod 644 {} \; find . -type d -exec chmod 755 {} \; ``` --- ## Apache Configuration No Apache configuration is required. Docsify's default hash-based routing means every request is for a real file (`index.html`, a `.md` file, or an asset) — Apache serves them as ordinary static files without any rewrite rules or special directives. --- ## Verify the Setup After completing the steps above, confirm the file layout looks correct: ```bash find . -not -path '*/\.*' | sort ``` Expected output: ``` . ./README.md ./_sidebar.md ./assets ./assets/css ./assets/css/vue.css ./assets/js ./assets/js/docsify.min.js ./assets/js/search.min.js ./getting-started.md ./index.html ``` Then open `http://your-server/docs/` in a browser. You should see the rendered homepage with a sidebar and search bar — no external requests are made. --- ## Adding New Pages 1. Create a `.md` file in the docs directory (or a subdirectory). 2. Add a corresponding entry to `_sidebar.md`. Example for a new page `reference.md`: ```markdown - [Home](/) - [Getting Started](getting-started.md) - [Reference](reference.md) ``` For subdirectories, nest entries with indentation: ```markdown - [Home](/) - [Getting Started](getting-started.md) - **Advanced** - [Configuration](advanced/configuration.md) - [Deployment](advanced/deployment.md) ``` --- ## Upgrading Docsify Since files are self-hosted, upgrades are manual. Re-run the `curl` commands from Step 2 with a specific version to update: ```bash # Pin to a specific version (replace 4.13.1 with the target version) curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/docsify.min.js" \ -o assets/js/docsify.min.js curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/plugins/search.min.js" \ -o assets/js/search.min.js curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/themes/vue.css" \ -o assets/css/vue.css ``` Check the [Docsify releases page](https://github.com/docsifyjs/docsify/releases) for the latest version number before upgrading.