# VitePress vs Htmlpress

> Vite + Vue Markdown docs vs a single binary building plain HTML pages.

[VitePress](https://vitepress.dev) is the official Vue docs framework, built on Vite. It's Markdown-first, ships a minimal default theme, and is what powers most Vue ecosystem documentation (Vue itself, Vite, Pinia, …).

## At a glance

| Axis               | Htmlpress                                             | VitePress                    |
| ------------------ | ----------------------------------------------------- | ---------------------------- |
| Language / runtime | Rust (single binary, no runtime)                      | TypeScript / Node 18+        |
| UI framework       | None (plain HTML + CSS, `htmlpress-*` web components) | Vue 3                        |
| Build tool         | htmlpress binary                                      | Vite (custom build pipeline) |
| Content format     | HTML and Markdown pages                               | Markdown with Vue templating |
| License            | MIT, self-hosted                                      | MIT, self-hosted             |
| Output model       | Prerendered static                                    | Prerendered static (SSG)     |

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

VitePress wraps Vite with its own SSG pipeline and renders Vue. Its runtime is `vue-router` plus a built-in default theme.

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. VitePress expects all content under a single source root (`docs/` by default, configurable via `srcDir`), with routes derived from file paths.

## Content surface

VitePress accepts Markdown with built-in Vue templating — you can use Vue components and `<script setup>` blocks inside `.md` files. It does **not** support MDX in the React sense.

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. VitePress uses frontmatter: `title`, `layout`, `sidebar`, `outline`, `prev`/`next`.

Callouts/admonitions: VitePress uses `::: tip` / `::: warning` containers; htmlpress uses `<htmlpress-callout type="warning">`.

## Feature matrix

| Capability                  | Htmlpress                                                   | VitePress                             |
| --------------------------- | ----------------------------------------------------------- | ------------------------------------- |
| Versioning                  | Partial (a section or a deploy per version)                 | No (community workarounds)            |
| Internationalization (i18n) | Yes (translations, language picker, 7 bundled UI languages) | Yes (built-in)                        |
| Search                      | Yes (built-in, client-side)                                 | Yes (local + Algolia)                 |
| Blog                        | No                                                          | No (community plugins)                |
| Changelog                   | No                                                          | No                                    |
| Sitemap                     | Yes (with `site` set)                                       | Yes                                   |
| RSS                         | No                                                          | No                                    |
| Themes                      | Escapes in `.htmlpress/` + `--htmlpress-*` tokens           | Custom themes via `.vitepress/theme/` |
| Plugins                     | No (project components in `.htmlpress/components/`)         | Vite plugins + markdown-it plugins    |
| Custom routes               | Any `.html` file; extra layouts in `.htmlpress/layouts/`    | Dynamic routes via `paths()`          |

## Output & deployment

Both produce a directory of static HTML + assets ready for any static host. VitePress emits to `.vitepress/dist/` by default; htmlpress emits to `.htmlpress/build/`.

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.

## See also

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