Nextra vs Htmlpress

Nextra 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

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

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 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 — htmlpress' HTML surface.
• Customization — htmlpress' config keys and escapes.
• Comparison — back to the index.