# Docsify vs Htmlpress

> Static site builder vs runtime Markdown renderer in the browser.

[Docsify](https://docsify.js.org) is a documentation site tool that takes a different approach from every other entry in this section: it does not generate static HTML at build time. Instead, it ships a single `index.html` plus a JavaScript runtime that fetches Markdown files in the browser and renders them on the fly. There is no build step.

## At a glance

| Axis               | Htmlpress                                             | Docsify                                       |
| ------------------ | ----------------------------------------------------- | --------------------------------------------- |
| Language / runtime | Rust (single binary, no runtime)                      | Browser JavaScript (no build)                 |
| UI framework       | None (plain HTML + CSS, `htmlpress-*` web components) | Vanilla JS + Vue-flavored template directives |
| Build tool         | htmlpress binary                                      | None (runtime fetch + render)                 |
| Content format     | HTML and Markdown pages                               | Markdown (marked / Prism in the browser)      |
| License            | MIT, self-hosted                                      | MIT, self-hosted                              |
| Output model       | Prerendered static                                    | Client-rendered from raw `.md` files          |

## Architecture

htmlpress is one Rust binary, installed from npm (`gethtmlpress`), PyPI or crates.io. It wraps each HTML page in one layout with a navigation and a theme; there is no bundler, no UI framework and no plugin API. Every built-in file — the layout, the styles, the scripts and each component — can be escaped: a file at the same path under `.htmlpress/` replaces it. Pages are prerendered to static HTML at build time; `htmlpress start` serves them with live reload while you edit.

Docsify has no build pipeline. A site is an `index.html` that loads `docsify.js` from a CDN (or `node_modules`) along with a small config object on `window.$docsify`. At runtime, the script reads the URL hash (`#/some/page`), fetches the corresponding `.md` file with `fetch()`, runs it through `marked` for Markdown parsing and `Prism` for syntax highlighting, and injects the result into the page. Navigation is hash-based by default; History API mode is opt-in but requires server rewrites.

Content layout is unconstrained on the htmlpress side: it scans by glob (`include`/`exclude` in `htmlpress.yaml`, every `.html` file by default), and a page's URL follows its file path below the glob's base, so `docs/**/*.html` serves `docs/guide.html` at `/guide/`. There's no required `docs/` folder. The navigation is built from the folders and each page's `<meta name="order">`; a folder's `index.html` names its group. Docsify reads from a single source root (the directory containing `index.html`, configurable via `basePath`), and the request URL maps directly to a file path on disk — `#/guide/install` fetches `guide/install.md`. Sidebar navigation is authored manually in `_sidebar.md`; there is no auto-generated nav.

## Content surface

Docsify supports plain Markdown (CommonMark via `marked`) with a handful of built-in extensions: helpers (`> [!TIP]`-style callouts via the [docsify-tabs](https://jhildenbiddle.github.io/docsify-tabs/) and admonition plugins), HTML pass-through, and limited Vue-template-style directives if the optional Vue compiler is loaded. There is no MDX, no frontmatter parsing by default (a plugin can add it), and no per-page React components. Plugins are registered by pushing functions into `window.$docsify.plugins`, where they hook into the lifecycle (`init`, `mounted`, `beforeEach`, `afterEach`, `doneEach`, `ready`).

htmlpress pages are plain semantic HTML, styled by the theme from the elements themselves. Richer blocks are `htmlpress-*` custom elements (`htmlpress-callout`, `htmlpress-tabs`, `htmlpress-filetree`, `htmlpress-cards`, …), whose CSS and JS are linked only on pages that use the tag. A project adds its own tag with `.htmlpress/components/<name>/<name>.html`, which replaces the tag at build time.

htmlpress has no frontmatter: a page's metadata is its own `<head>` — `<title>`, `<meta name="description">`, `<meta name="order">`, `<meta name="layout">` and `<meta name="image">`; other `<head>` tags are kept.

## Feature matrix

| Capability                  | Htmlpress                                                   | Docsify                                      |
| --------------------------- | ----------------------------------------------------------- | -------------------------------------------- |
| Versioning                  | Partial (a section or a deploy per version)                 | Yes (multi-instance via `alias` config)      |
| Internationalization (i18n) | Yes (translations, language picker, 7 bundled UI languages) | Yes (`fallbackLanguages` + per-locale files) |
| Search                      | Yes (built-in, client-side)                                 | Yes (built-in full-text plugin)              |
| Blog                        | No                                                          | No                                           |
| Changelog                   | No                                                          | No (manual)                                  |
| Sitemap                     | Yes (with `site` set)                                       | No (third-party plugin)                      |
| RSS                         | No                                                          | No                                           |
| Themes                      | Escapes in `.htmlpress/` + `--htmlpress-*` tokens           | CSS themes (`vue.css`, `buble.css`, etc.)    |
| Plugins                     | No (project components in `.htmlpress/components/`)         | Runtime JS plugins on `window.$docsify`      |
| Custom routes               | Any `.html` file; extra layouts in `.htmlpress/layouts/`    | No (URL maps 1:1 to file paths)              |
| Standalone toolchain        | Single Rust binary (npm, PyPI or crates.io)                 | None at runtime; `docsify-cli` for init only |

## Output & deployment

This is where the tools diverge most sharply.

htmlpress produces a directory of prerendered HTML + assets (`.htmlpress/build/`). Every page is a real HTML file; crawlers, link previews, and JS-disabled clients all see the rendered content. htmlpress writes every page to static HTML in `.htmlpress/build/`, along with `robots.txt`, a `sitemap.xml` when `site` is set, a Markdown copy of each page, `llms.txt` and the agent skills under `.well-known/agent-skills/`. The `base` key serves the site under a sub-path. See [Deployment](/deployment/) for host guides.

Docsify ships the raw `.md` files alongside `index.html`. The "deploy" is uploading the source directory to any static host. The trade-off: zero build time and edit-and-refresh authoring, at the cost of empty HTML on first paint — search engines, social previews, and no-JS clients see only the loader shell. The project documents an [SSR/prerender workflow](https://docsify.js.org/#/ssr) using `docsify-ssr` or external prerenderers to mitigate this for SEO-sensitive sites.

## See also

- [Authoring](/authoring/) — htmlpress' HTML surface.
- [Customization](/customization/) — htmlpress' config keys and escapes.
- [Comparison](/comparison/) — back to the index.