Starlight vs Htmlpress

Starlight is the official Astro docs theme, maintained by the Astro team. It uses Astro's islands architecture (zero JavaScript by default, opt-in interactive components) and supports MDX content.

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.

htmlpress pages render to HTML at build time and hydrate nothing: interactive htmlpress-* components are custom elements with a small vanilla script each, linked only on pages that use them.

Starlight uses Astro's islands model: pages are rendered to HTML at build time with zero JavaScript by default. Interactive components are explicit "islands" that hydrate on demand. The default Starlight theme is mostly Astro components (no client JS); reaching for React/Vue/Svelte is opt-in. Astro's component model is Astro's own .astro syntax (HTML + JS frontmatter, statically analyzed).

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. Starlight requires content in src/content/docs/ (Astro's content-collections directory), with routes derived from file paths under that root.

Content surface

Starlight accepts Markdown + MDX with frontmatter, and additionally MDoc (Markdoc) for structured, validated content with custom tags. Components in .mdx files are Astro components by default; framework components (React, etc.) need explicit client:* directives to hydrate.

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. Starlight uses frontmatter: title, description, sidebar, tableOfContents, editUrl, lastUpdated.

Feature matrix

Output & deployment

Both produce a directory of static HTML + assets. Starlight emits to 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 for host guides.

Starlight inherits Astro's adapter system, which supports SSR on Cloudflare, Netlify, Vercel, Node, and Deno. htmlpress has no server mode: the build is static only.

See also

• Authoring — htmlpress' HTML surface.
• Customization — htmlpress' config keys and escapes.
• Comparison — back to the index.