# Docusaurus vs Htmlpress

> Technical side-by-side of a React + MDX docs framework and a plain-HTML site builder.

[Docusaurus](https://docusaurus.io) is an open-source docs framework maintained by Meta. It renders React + MDX content through a Webpack-based build pipeline, ships first-class versioning and internationalization, and has a large plugin ecosystem.

## At a glance

| Axis               | Htmlpress                                             | Docusaurus            |
| ------------------ | ----------------------------------------------------- | --------------------- |
| Language / runtime | Rust (single binary, no runtime)                      | TypeScript / Node 18+ |
| UI framework       | None (plain HTML + CSS, `htmlpress-*` web components) | React 18              |
| Build tool         | htmlpress binary                                      | Webpack               |
| Content format     | HTML and Markdown pages                               | Markdown + MDX        |
| License            | MIT, self-hosted                                      | MIT, self-hosted      |
| Output model       | Prerendered static                                    | Prerendered static    |

## 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.

Docusaurus is built on Webpack. The runtime is React Router + a Docusaurus core that handles theming, plugins, and content sources. Plugins are first-class — every built-in feature (docs, blog, pages, search) is itself a plugin, and third parties extend the system the same way.

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. Docusaurus's docs plugin expects a `docs/` directory (configurable via `path`, but folder-based rather than glob-based).

## Content surface

Docusaurus accepts Markdown and MDX with frontmatter and lets you embed React components inside `.md`/`.mdx` files. htmlpress accepts `.html` pages, a full document or a bare fragment, and `.md` pages with frontmatter, whose `:::name` directives are its components; no MDX and no React.

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. Docusaurus uses MDX components plus an `admonition` extension for callouts.

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. Docusaurus uses `id`, `slug`, `sidebar_position`, `sidebar_label`, `tags`.

## Feature matrix

| Capability                  | Htmlpress                                                   | Docusaurus                             |
| --------------------------- | ----------------------------------------------------------- | -------------------------------------- |
| Versioning                  | Partial (a section or a deploy per version)                 | Yes (built-in)                         |
| Internationalization (i18n) | Yes (translations, language picker, 7 bundled UI languages) | Yes (built-in)                         |
| Search                      | Yes (built-in, client-side)                                 | Algolia DocSearch integration          |
| Blog                        | No                                                          | Yes (built-in plugin)                  |
| Changelog                   | No                                                          | No (community plugins)                 |
| Sitemap                     | Yes (with `site` set)                                       | Yes                                    |
| RSS                         | No                                                          | Yes (for blog plugin)                  |
| Themes                      | Escapes in `.htmlpress/` + `--htmlpress-*` tokens           | Theme packages (`@docusaurus/theme-*`) |
| Plugins                     | No (project components in `.htmlpress/components/`)         | First-class plugin API                 |
| Custom routes               | Any `.html` file; extra layouts in `.htmlpress/layouts/`    | Plugin-defined routes                  |

## Output & deployment

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.

Docusaurus also prerenders to static HTML, output at `build/`. The static output works on any of the same hosts (GitHub Pages, Cloudflare, Vercel, Netlify, static hosting). Docusaurus's built-in i18n produces separate output trees per locale.

## See also

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