# Starlight vs Htmlpress

> Plain HTML pages in one binary vs Astro Islands for docs.

[Starlight](https://starlight.astro.build) 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

| Axis               | Htmlpress                                             | Starlight                                                              |
| ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------- |
| Language / runtime | Rust (single binary, no runtime)                      | TypeScript / Node 18+                                                  |
| UI framework       | None (plain HTML + CSS, `htmlpress-*` web components) | Astro components (HTML-first), optional React/Vue/Svelte/Solid islands |
| Build tool         | htmlpress binary                                      | Astro (Vite under the hood)                                            |
| Content format     | HTML and Markdown pages                               | Markdown + MDX + MDoc                                                  |
| License            | MIT, self-hosted                                      | MIT, self-hosted                                                       |
| Output model       | Prerendered static                                    | Prerendered static (SSR-capable via adapters)                          |

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

| Capability                  | Htmlpress                                                   | Starlight                               |
| --------------------------- | ----------------------------------------------------------- | --------------------------------------- |
| Versioning                  | Partial (a section or a deploy per version)                 | No (community plugins)                  |
| Internationalization (i18n) | Yes (translations, language picker, 7 bundled UI languages) | Yes (built-in)                          |
| Search                      | Yes (built-in, client-side)                                 | Yes (Pagefind, built-in)                |
| Zero-JS by default          | No (small vanilla scripts, no framework)                    | Yes (islands architecture)              |
| Blog                        | No                                                          | No (use Astro's content collections)    |
| Changelog                   | No                                                          | No                                      |
| Sitemap                     | Yes (with `site` set)                                       | Yes                                     |
| RSS                         | No                                                          | Via `@astrojs/rss` integration          |
| Themes                      | Escapes in `.htmlpress/` + `--htmlpress-*` tokens           | Component overrides via Starlight slots |
| Plugins                     | No (project components in `.htmlpress/components/`)         | Astro integrations + Starlight plugins  |
| Custom routes               | Any `.html` file; extra layouts in `.htmlpress/layouts/`    | Astro pages alongside Starlight content |

## 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](/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](/authoring/) — htmlpress' HTML surface.
- [Customization](/customization/) — htmlpress' config keys and escapes.
- [Comparison](/comparison/) — back to the index.