# Nextra vs Htmlpress

> A standalone plain-HTML site builder vs Next.js with the theme-package model.

[Nextra](https://nextra.site) is a Next.js docs framework with a theme-package architecture. It originated on the Pages Router and has migrated to support the App Router as well. Documentation sites pick a theme (`nextra-theme-docs` for docs, `nextra-theme-blog` for blogs) and configure it.

## At a glance

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

## 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. One tool, one optional config file, content in `.html` files.

Nextra is a layer on top of an existing Next.js application. Setup involves installing `nextra` and a theme package, wiring them into `next.config.js`, and defining navigation in a `_meta.json` (Pages Router) or `meta.js` (App Router) file per directory. The theme package owns the entire UI; customization happens through the theme's documented hooks.

`nextra-theme-docs` is the documentation theme used by Vercel, SWR, Turbo, and many others. It's stable, maintained, and feature-complete for docs use cases.

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. Nextra reads content from `pages/` (Pages Router) or `content/` (App Router) with routes determined by file paths and `_meta.json` files alongside.

## Content surface

Nextra accepts Markdown + MDX with frontmatter and embedded React components. It supports remote MDX via `next-mdx-remote`, KaTeX/Mermaid through plugins, and image optimization through Next's `<Image>` component.

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. Mermaid diagrams come built in, from a `language-mermaid` code block.

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. Nextra uses frontmatter (`title`, `description`, `searchable`, `hide_title`) plus per-directory `_meta.json` for navigation; htmlpress has no navigation file.

## Feature matrix

| Capability                  | Htmlpress                                                   | Nextra                                               |
| --------------------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
| Versioning                  | Partial (a section or a deploy per version)                 | No (community workarounds)                           |
| Internationalization (i18n) | Yes (translations, language picker, 7 bundled UI languages) | Yes (via Next i18n + Nextra hooks)                   |
| Search                      | Yes (built-in, client-side)                                 | Yes (FlexSearch built-in, optional Algolia/Pagefind) |
| Blog                        | No                                                          | Yes (`nextra-theme-blog`)                            |
| Changelog                   | No                                                          | No (community plugins)                               |
| Sitemap                     | Yes (with `site` set)                                       | Via Next.js `sitemap.ts`                             |
| RSS                         | No                                                          | Yes (blog theme), via Next routes for docs           |
| Themes                      | Escapes in `.htmlpress/` + `--htmlpress-*` tokens           | Theme packages; customize via theme config           |
| Custom routes               | Any `.html` file; extra layouts in `.htmlpress/layouts/`    | Any Next page/route                                  |
| Standalone CLI              | Yes (`htmlpress build`)                                     | No (Next.js commands)                                |

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

Nextra inherits Next.js's output modes. The most common docs setup is full static export (`output: 'export'`), which produces a static directory deployable anywhere. SSR setups target Vercel or Node hosts.

## See also

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