docsify

# 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 `docsify@5.0.0-rc.4` (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.