docsify

What this skill does

# Docsify

Docsify turns Markdown files into a documentation website **at runtime** — there is no static build step. A single `index.html` boots `docsify.js`, which fetches and renders `.md` files dynamically.

Targets Docsify **v5** by default. v5 is currently published only as a release candidate (`5.0.0-rc.4`) — all CDN URLs in this skill pin to that exact version. Use `docsify@rc` (dist-tag) to track the latest 5.x RC, and switch to `docsify@5` only after v5 stable is published. If the user needs the long-stable line, use `docsify@4` (CDN path `/lib/` instead of `/dist/`). For v4 migration guidance, load `references/advanced.md`.

## When to load which reference

Load **only** the references needed for the current task — do not preload everything.

| Task | Load |
| --- | --- |
| Bootstrap a brand-new site / write `index.html` / `docsify-cli` usage | `references/getting-started.md` (+ `assets/index.html`) |
| Add pages, build `_sidebar.md` / `_navbar.md` / `_coverpage.md`, multi-language layout, TOC | `references/pages-and-navigation.md` |
| Set or look up any `window.$docsify` option | `references/configuration.md` |
| Docsify-specific Markdown syntax (callouts, link/image attrs, heading IDs, embed `:include`, code highlight) | `references/markdown-helpers.md` |
| Theme switching, CSS variables, custom fonts, body classes, dark mode | `references/themes-and-styling.md` |
| Install / configure built-in or community plugins | `references/plugins.md` |
| Write a custom Docsify plugin (lifecycle hooks) | `references/writing-plugins.md` |
| Deploy to GitHub Pages, GitLab, Netlify, Vercel, Firebase, Docker, Nginx, AWS Amplify, etc. | `references/deployment.md` |
| PWA / offline, virtual routes, Vue components, v4 → v5 upgrade | `references/advanced.md` |

## Core mental model

A Docsify site needs only three things:

1. **`index.html`** — single boot file that loads `docsify.js`, a theme CSS, optional plugins, and defines `window.$docsify` config.
2. **Markdown files** — `README.md` is the homepage; any other `*.md` is a route (e.g. `guide.md` → `/#/guide`).
3. **Special underscore files** (optional but common):
   - `_sidebar.md` — sidebar menu (requires `loadSidebar: true`)
   - `_navbar.md` — top navbar (requires `loadNavbar: true`)
   - `_coverpage.md` — landing cover (requires `coverpage: true`)
   - `_404.md` — custom 404 (requires `notFoundPage: true`)
   - `_media/` — images and other assets
   - **`.nojekyll`** — required on GitHub Pages so underscore files are served

Subfolders define nested routes; nested `_sidebar.md` / `_navbar.md` override parent ones (used for multi-language sites).

## Quick start workflow

For "set up a new Docsify site" requests:

1. Read `references/getting-started.md` for the canonical `index.html` and CLI commands.
2. Copy `assets/index.html` into the site folder and adjust the `name`, `repo`, theme add-ons, and plugin `<script>` tags.
3. Create `README.md` (homepage) and `.nojekyll` (empty file).
4. If the user wants a sidebar/navbar/cover, also load `references/pages-and-navigation.md`.
5. Verify locally with `docsify serve <folder>` (or `python3 -m http.server`).

## Key conventions to preserve

- **Always pin an exact CDN version**. v5 is in RC: use `[email protected]` (or the `@rc` tag) until v5 stable releases — the shorthand `docsify@5` does **not** resolve today. For the long-stable line, use `docsify@4` with CDN path `/lib/` instead of `/dist/`. See `assets/index.html`.
- **Theme CSS must come before** Docsify JS; **theme add-ons must come after** the core theme; **Prism language/theme files and plugin scripts must come after** `docsify.min.js`.
- **`.nojekyll`** is mandatory whenever the site is on GitHub Pages and uses any `_*.md` file.
- **Hash routing is the default** (`/#/page`). Only switch to `routerMode: 'history'` if the host can rewrite URLs to `index.html`, and add `alias` entries for `_sidebar.md` / `_navbar.md` (see `references/configuration.md`).
- **Underscore files fall back up the directory tree** — `/guide/_sidebar.md` is used if present, otherwise `/_sidebar.md`.
- Docsify renders Markdown via **marked** and syntax-highlights via **Prism** (load extra Prism language components after `docsify.min.js`).

## Common gotchas

- Forgetting `.nojekyll` → GitHub Pages 404s on `_sidebar.md`.
- Putting plugin `<script>` tags **before** `docsify.min.js` → plugin never registers.
- Setting `coverpage: true` without creating `_coverpage.md` → blank landing.
- Using `routerMode: 'history'` on a static host without rewrite rules → deep links 404 on refresh.
- Mermaid: Docsify only supports synchronous Mermaid (≤ v9.3.0). See `references/markdown-helpers.md`.
- The legacy `!>` / `?>` callouts and the `themeColor` / `topMargin` options are deprecated in v5 — prefer GitHub-style `> [!NOTE]` callouts and CSS variables.

## Assets

- `assets/index.html` — production-ready `index.html` template with comments showing where to enable theme add-ons and plugins. Copy and edit; do not load into the conversation context unless modifying the template itself.