path: root/README.md

# 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
    │   ├── docsify-copy-code.min.js
    │   ├── docsify-katex.js
    │   ├── prism-bash.min.js
    │   ├── prism-yaml.min.js
    │   ├── prism-python.min.js
    │   └── prism-r.min.js
    └── css/
        ├── vue.css
        ├── katex.min.css
        └── fonts/
            └── KaTeX_*.woff2   (20 KaTeX font files)
```

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

### Syntax Highlighting (Prism)

Docsify **bundles Prism** and highlights a handful of languages out of the box —
`markup`/HTML, `css`, `clike`, and `javascript`. For any other language, download its
Prism component and load it **after** `docsify.min.js` (see Step 3) so it attaches to
Docsify's bundled Prism.

> **Do not download `prism-core.min.js`.** A standalone Prism core loaded after Docsify
> replaces Docsify's own Prism on the page; the language components then attach to the
> wrong instance and silently fail to highlight. You only need the language files below.

This guide adds bash, yaml, python, and r:

```bash
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-python.min.js" \
  -o assets/js/prism-python.min.js

curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-r.min.js" \
  -o assets/js/prism-r.min.js
```

To highlight more languages, download additional `prism-<lang>.min.js` files (browse the
[Prism components](https://cdn.jsdelivr.net/npm/prismjs@1/components/)) and add a matching
`<script>` tag in Step 3. A few Prism languages depend on others — if one does, download
its dependency too (Docsify already provides `clike`, the most common base grammar).

### Copy-to-Clipboard Button

Add a **copy** button to every fenced code block with the
[docsify-copy-code](https://github.com/jperasmus/docsify-copy-code) plugin. Like the
assets above, it is fetched once and served locally thereafter:

```bash
# Copy-to-clipboard plugin
curl -L "https://cdn.jsdelivr.net/npm/docsify-copy-code@3/dist/docsify-copy-code.min.js" \
  -o assets/js/docsify-copy-code.min.js
```

The plugin injects its own CSS via JavaScript, so there is **no separate CSS file**
to download. Just add its `<script>` tag to `index.html` **after** `docsify.min.js`
(see Step 3). Copying uses `document.execCommand('copy')`, so it works over plain
`http://` as well as `https://`.

It works with no configuration. To customise the button labels, add a `copyCode`
block to the `window.$docsify` object in `index.html`:

```js
copyCode: {
  buttonText: 'Copy to clipboard',
  errorText: 'Error',
  successText: 'Copied'
}
```

### Math (LaTeX via KaTeX)

Render LaTeX math — inline like `$x^2 + y^2 = z^2$` and block like `$$ ... $$` — with the
[docsify-katex](https://github.com/upupming/docsify-katex) plugin. **Pin version 1.4.4**:
it bundles the KaTeX renderer (the 2.x releases are broken). The only extra assets are
KaTeX's stylesheet and the fonts it references.

```bash
# docsify-katex plugin (bundles the KaTeX renderer)
curl -L "https://cdn.jsdelivr.net/npm/docsify-katex@1.4.4/dist/docsify-katex.js" \
  -o assets/js/docsify-katex.js

# KaTeX stylesheet — pin to the version bundled by docsify-katex@1.4.4 (0.11.1)
curl -L "https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css" \
  -o assets/css/katex.min.css

# KaTeX fonts — the stylesheet loads these from ./fonts/, so they must sit beside it.
# Modern browsers use woff2, so only those (20 files) are needed.
mkdir -p assets/css/fonts
for f in $(grep -oE 'fonts/KaTeX_[^)]+\.woff2' assets/css/katex.min.css | sort -u); do
  curl -L "https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/$f" -o "assets/css/$f"
done
```

Add the stylesheet (a `<link>` in `<head>`) and the plugin `<script>` (after
`docsify.min.js`) to `index.html` — see Step 3. KaTeX then renders math automatically,
with no extra configuration.

---

## Step 3: Create `index.html`

Create `index.html`:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>My Docs</title>
  <link rel="stylesheet" href="assets/css/vue.css">
  <link rel="stylesheet" href="assets/css/katex.min.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: 'My Docs',
      loadSidebar: true,   // enables _sidebar.md
      subMaxLevel: 2,      // auto-generate H2 entries in sidebar
      search: 'auto'       // enables the search plugin
    }
  </script>
  <script src="assets/js/docsify.min.js"></script>
  <script src="assets/js/search.min.js"></script>
  <script src="assets/js/docsify-copy-code.min.js"></script>
  <script src="assets/js/docsify-katex.js"></script>

  <!-- Extra Prism languages — Docsify bundles Prism core + html/css/js. Load after docsify. -->
  <script src="assets/js/prism-bash.min.js"></script>
  <script src="assets/js/prism-yaml.min.js"></script>
  <script src="assets/js/prism-python.min.js"></script>
  <script src="assets/js/prism-r.min.js"></script>
</body>
</html>
```

> **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
# The 20 KaTeX font files are summarised rather than listed individually
find . -not -path '*/\.*' -not -path './assets/css/fonts*' | sort
echo "./assets/css/fonts/  ($(ls -1 assets/css/fonts | wc -l) KaTeX woff2 files)"
```

Expected output:

```
.
./README.md
./_sidebar.md
./assets
./assets/css
./assets/css/katex.min.css
./assets/css/vue.css
./assets/js
./assets/js/docsify-copy-code.min.js
./assets/js/docsify-katex.js
./assets/js/docsify.min.js
./assets/js/prism-bash.min.js
./assets/js/prism-python.min.js
./assets/js/prism-r.min.js
./assets/js/prism-yaml.min.js
./assets/js/search.min.js
./getting-started.md
./index.html
./assets/css/fonts/  (20 KaTeX woff2 files)
```

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

The Prism components (`prismjs@1`), the copy-code plugin (`docsify-copy-code@3`), and the
math plugin (`docsify-katex@1.4.4` with `katex@0.11.1`) are versioned independently of
Docsify; re-run their Step 2 commands the same way when you want to update them. If you
bump KaTeX, re-download the stylesheet **and** its fonts together so they stay in sync.

Check the [Docsify releases page](https://github.com/docsifyjs/docsify/releases)
for the latest version number before upgrading.