Contour

Contour is a monochrome Hugo theme from MobiusOne that renders animated topographic contour-line graphics behind a typographic layout, producing a static blog with tags, archives, and client-side full-text search.

What is Contour?

Contour is a Hugo theme that combines contour-line (isoline) canvas motifs with typography, aimed at personal and technical blogs. It takes standard Markdown content, a hugo.toml configuration, and taxonomy plus menu settings as input, and outputs static HTML: a full-screen landing page with the menu, post lists, article pages with a left sidebar, a yearly archive, a search page, and tag term pages. It is published by MobiusOne and distributed from the mobiusone-org GitHub repository under the MIT license. It requires Hugo extended v0.146.0 or later because it is built on Hugo's new template system.

What makes Contour stand out?

• New Hugo template system — Built on baseof.html, home.html, page.html, section.html, taxonomy.html, and term.html, using the reserved _partials and _markup directories.
• Hugo Pipes asset pipeline — CSS and JavaScript are bundled through Hugo Pipes; production builds are minified, fingerprinted, and served with SRI metadata.
• Automatic heading numbering — _markup/render-heading.html numbers h2 headings in rendered content without manual editing.
• Bundled search, no dependencies — Adding json to the home outputs generates /index.json containing each post's title, tags, summary, and body text; assets/js/search.js loads only on the search page and accepts an initial query via ?q=.
• Image "plates" — Markdown images render inside L-shaped corner marks (16px, 1px, currentColor) with the image inset, and a Markdown title becomes a caption in the measurement-label style.
• Configurable contour canvas — canvas[data-contour] accepts data-color (a CSS custom property name or an "r, g, b" value) and data-cell for grid cell size in CSS pixels; smaller cells give finer line detail.
• Built-in taxonomies and archive — tag and categories taxonomies generate /tags/ and /tags/ term pages automatically, and content/archives.md produces a yearly article archive.
• Post metadata display — For pages inside the posts/ section, page.html shows date, reading time, tags, and previous/next navigation; standalone root pages show only title and body.

Who is it for?

• Personal bloggers: publish dated posts in content/posts/ and get post lists, tag pages, reading time, and previous/next navigation without writing templates.
• Technical writers: use the numbered h2 render hook and captioned image plates for long, structured articles that need consistent figure labels.
• Developers who want search without a service: rely on the JSON index and client-side search page instead of adding an external search backend.
• Sites expecting large indexes: swap the bundled search for Pagefind while keeping the same page structure.

What can you do with Contour?

• Launch a minimal blog: install the theme, set theme = "contour" in hugo.toml, and ship a monochrome site with a decorative contour-line landing page.
• Add full-text search: add json to the home outputs, then search titles, tags, summaries, and body text from content/search.md, optionally deep-linking with a query parameter.
• Publish a static page like an About or feature page: a root-level file such as feature.md renders through page.html with only title and body, no date or reading time.
• Tune the visual motif: change --bg and --fg in assets/css/base.css and keep --bg-rgb / --fg-rgb in sync, then adjust data-cell and data-color on the canvas.

How does Contour work?

1. Add the theme as a submodule into themes/contour — the folder name must match the theme = "contour" setting; using themes/hugo-contour will not work.
2. Set theme = "contour", languages, taxonomies, outputs, and the params logo, kicker, description, axis, and coords values in hugo.toml.
3. Add content files, then preview with hugo server — the repository ships an exampleSite/ you can run from the repo root with hugo server --themesDir ../...

FAQ

What Hugo version does Contour require?

Contour requires Hugo extended v0.146.0 or later. The extended build and that version are needed because the theme uses Hugo's new template system with baseof.html and the reserved _partials and _markup directories.

Does Contour include search?

Yes. Adding json to the home outputs generates /index.json from posts, and content/search.md with layout = "search" provides a dependency-free client-side search UI. For larger indexes you can replace it with Pagefind while keeping the same page structure.

Is Contour free?

Contour is released under the MIT license, so it can be used, modified, and redistributed freely. The source lives in the mobiusone-org GitHub repository, and a live demo is hosted at the project's GitHub Pages URL.

Why must the theme folder be named contour?

The repository is named hugo-contour, but Hugo looks up the folder named in the theme setting. Cloning into themes/hugo-contour while setting theme = "contour" breaks rendering, so the submodule path must be themes/contour.