# Hugo vs Htmlpress

> Two single-binary static site generators: docs-first plain HTML vs general-purpose Go.

[Hugo](https://gohugo.io) is a general-purpose static site generator written in Go. It ships as a single binary, builds extremely quickly, and powers everything from blogs and portfolios to documentation sites via community themes like [Docsy](https://www.docsy.dev) and [Hugo Book](https://github.com/alex-shpak/hugo-book).

## At a glance

| Axis               | Htmlpress                                             | Hugo                           |
| ------------------ | ----------------------------------------------------- | ------------------------------ |
| Language / runtime | Rust (single binary, no runtime)                      | Go (single binary, no runtime) |
| UI framework       | None (plain HTML + CSS, `htmlpress-*` web components) | Go templates (HTML + CSS)      |
| Build tool         | htmlpress binary                                      | Hugo binary                    |
| Content format     | HTML and Markdown pages                               | Markdown with Hugo shortcodes  |
| License            | MIT, self-hosted                                      | Apache-2.0, self-hosted        |
| Output model       | Prerendered static                                    | Prerendered static             |

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

Hugo is a single Go binary — no runtime dependencies, no package install step. The site structure is convention-based: `content/`, `layouts/`, `static/`, `themes/`, `config.toml` (or `.yaml`/`.json`). Layouts use Go's `html/template` syntax. Themes are git-submoduled or copied into `themes/<name>/`. htmlpress' layout is plain HTML with no template syntax: the binary fills its `htmlpress-*` placeholder elements.

Hugo is not docs-specific. The same binary powers blogs, marketing sites, portfolios, and docs — the docs use case is supported through themes rather than first-class section types.

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. Hugo reads from `content/` with URL structure mirroring the directory tree (and per-section frontmatter overrides).

## Content surface

Hugo accepts Markdown with frontmatter; htmlpress accepts HTML pages and Markdown with frontmatter alike.

Hugo embeds components with **shortcodes** — Go-templated functions invoked from Markdown with `{{< shortcode-name arg="value" >}}`. Shortcodes are defined in `layouts/shortcodes/*.html` as Go template snippets and emit HTML directly. The closest htmlpress equivalent is a project component: `.htmlpress/components/<name>/<name>.html` fills every `<htmlpress-<name>>` at build time.

Hugo supports Goldmark-based Markdown extensions (footnotes, tables, definition lists, math via plugins). For richer interactivity, the typical pattern is to embed a `<script>` or use a JS framework as an island inside a shortcode.

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. Hugo accepts TOML, YAML, or JSON frontmatter with fields like `title`, `date`, `draft`, `weight`, `taxonomies`, plus user-defined fields.

## Feature matrix

| Capability                  | Htmlpress                                                   | Hugo                                      |
| --------------------------- | ----------------------------------------------------------- | ----------------------------------------- |
| Versioning                  | Partial (a section or a deploy per version)                 | No (manual via branches/sites)            |
| Internationalization (i18n) | Yes (translations, language picker, 7 bundled UI languages) | Yes (built-in, multilingual mode)         |
| Search                      | Yes (built-in, client-side)                                 | No (theme-provided or external)           |
| Blog                        | No                                                          | Yes (any section can be date-sorted)      |
| Changelog                   | No                                                          | No (manual)                               |
| Sitemap                     | Yes (with `site` set)                                       | Yes (built-in)                            |
| RSS                         | No                                                          | Yes (built-in, per section)               |
| Themes                      | Escapes in `.htmlpress/` + `--htmlpress-*` tokens           | Theme directories with template overrides |
| Plugins                     | No (project components in `.htmlpress/components/`)         | Hugo Modules (Go), shortcodes, hooks      |
| Custom routes               | Any `.html` file; extra layouts in `.htmlpress/layouts/`    | Layouts + content sections                |
| Standalone toolchain        | Single Rust binary (npm, PyPI or crates.io)                 | Single Go binary                          |
| Build speed                 | Native binary, no bundler                                   | Among the fastest SSGs                    |

## Output & deployment

Both tools produce static HTML + assets ready for any static host. Hugo emits to `public/` 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.