Liftoff

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Liftoff can be consumed in two ways. Pick the one that matches how the rest of your dependencies live.

As a Hugo module

 toml
 
 
# hugo.toml
[module]
 [[module.imports]]
 path = "codeberg.org/head1328/hugo-liftoff"

bash

hugo mod tidy
hugo server

As a git submodule

 bash
 
 
git submodule add https://codeberg.org/head1328/hugo-liftoff.git themes/liftoff
echo 'theme = "liftoff"' >> hugo.toml

SaaS landing page

Mon, 01 Jan 0001 00:00:00 +0000

The most common product page: convince, prove, price, close. Copy the front matter and the body below into content/_index.md, then replace the copy with your own.

Front matter

The hero is configured, not written. Everything below it is markdown.

 yaml
 
 
---
title: "Acme"
description: "Ship your first workflow in five minutes."
hero:
 title: "Automate the boring half of"
 titleAccent: "your deployments."
 subtitle: "One config file. No agents to install."
 highlights:
 - icon: "mdi:lightning-bolt-outline"
 label: "Zero downtime"
 - icon: "mdi:lock-outline"
 label: "SOC 2"
 primary:
 label: "Start free"
 url: "/signup"
 secondary:
 label: "Read the docs"
 url: "/docs"
 code:
 language: yaml
 content: |
 deploy:
 target: production
 strategy: rolling
---

Body

 markdown
 
 
{{< section >}}
## Everything you need to ship

{{< feature-grid >}}
 {{< feature-card title="Rollbacks" icon="mdi:backup-restore" >}}
 One command back to the last known good release.
 {{< /feature-card >}}
 {{< feature-card title="Audit log" icon="mdi:history" >}}
 Every change attributed, exportable as JSON.
 {{< /feature-card >}}
 {{< feature-card title="Secrets" icon="mdi:key-outline" >}}
 Encrypted at rest, injected at runtime.
 {{< /feature-card >}}
{{< /feature-grid >}}
{{< /section >}}

{{< section width="narrow" >}}
## Works with your stack

{{< icon-grid data="integrations" >}}
{{< /section >}}

{{< section >}}
## Pricing

{{< pricing data="editions" >}}
{{< /section >}}

{{< section width="narrow" >}}
{{< testimonial author="Jane Doe" role="VP Engineering, Northwind" >}}
We replaced three internal tools with this and stopped thinking about
deploys entirely.

metrics:
- 80% less deploy time
- 40+ teams onboarded
{{< /testimonial >}}
{{< /section >}}

{{< cta title="Ready to ship faster?" primary="Start free|/signup" secondary="Talk to sales|/contact" >}}
No credit card. Cancel whenever.
{{< /cta >}}

What to change

Piece	Replace with
`hero.code.content`	Your actual config or CLI invocation
`feature-card`	Three to six cards, one benefit each
`data/integrations.yaml`	The tools your customers already run
`data/editions.yaml`	Two or three plans, one marked `featured`

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Liftoff reads conventional Hugo configuration. A few extras enable the landing-style chrome.

Required markup settings

The shortcodes emit HTML, so Goldmark must be allowed to pass it through. Without this, feature cards and callouts render as escaped text.

 toml
 
 
[markup.goldmark.renderer]
 unsafe = true

Syntax highlighting comes from a stylesheet the theme ships, assets/css/syntax.css, so Chroma has to emit class names for it to match. The inline variant is also the first thing a Content-Security-Policy without 'unsafe-inline' throws away, which leaves every code block colourless.

Open source project page

Mon, 01 Jan 0001 00:00:00 +0000

An open source project page has one job: get someone from “what is this” to a working install before they lose interest. Cut everything that does not serve that.

Front matter

Put the install command in the hero. It is the single most-copied string on the page.

 yaml
 
 
---
title: "Widget"
description: "A single-binary task runner for small teams."
hero:
 title: "Task running without"
 titleAccent: "the YAML sprawl."
 subtitle: "One binary, no runtime, MIT licensed."
 highlights:
 - icon: "mdi:package-variant-closed"
 label: "Single binary"
 - icon: "mdi:scale-balance"
 label: "MIT"
 primary:
 label: "Get started"
 url: "/docs/installation"
 secondary:
 label: "Source"
 url: "https://codeberg.org/you/widget"
 code:
 tabs:
 - name: "macOS"
 icon: "simple-icons:apple"
 language: bash
 content: |
 brew install widget
 - name: "Linux"
 icon: "simple-icons:linux"
 language: bash
 content: |
 curl -sSf https://widget.dev/install.sh | sh
---

Body

 markdown
 
 
{{< section >}}
## What it does

{{< feature-grid >}}
 {{< feature-card title="No daemon" icon="mdi:power-plug-off-outline" >}}
 Runs and exits. Nothing left behind on your machine.
 {{< /feature-card >}}
 {{< feature-card title="Readable config" icon="mdi:file-document-outline" >}}
 Twenty lines of TOML, not two hundred of YAML.
 {{< /feature-card >}}
 {{< feature-card title="Docs" icon="mdi:book-open-page-variant" url="/docs" >}}
 Every flag documented, with examples.
 {{< /feature-card >}}
{{< /feature-grid >}}
{{< /section >}}

{{< section width="narrow" >}}
## Try it

{{< steps >}}
 {{< step number="1" title="Install" >}}
 Pick your platform above.
 {{< /step >}}
 {{< step number="2" title="Initialise" >}}
 Run `widget init` in your project root.
 {{< /step >}}
 {{< step number="3" title="Run" >}}
 Run `widget run build` and watch it exit cleanly.
 {{< /step >}}
{{< /steps >}}
{{< /section >}}

{{< cta title="Found a rough edge?" primary="Good first issues|https://codeberg.org/you/widget/issues" secondary="Contributing guide|/docs/contributing" >}}
Bug reports are contributions too.
{{< /cta >}}

Customization

Mon, 01 Jan 0001 00:00:00 +0000

Liftoff is designed to be customized without forking. Hugo’s theme lookup falls through to the site project first, so anything you place under your project’s assets/, layouts/, i18n/ or static/ wins over the theme. This page lists the seams that exist and how to use them.

Custom CSS

Place a stylesheet at assets/css/custom.css in your project. The theme’s head includes loads it after the main bundle, so any rule you write here overrides the theme.

Icons

Mon, 01 Jan 0001 00:00:00 +0000

Liftoff has a single icon partial that resolves three things: the Iconify catalog, the Material Design Icons set as a shortcut, and local SVGs you ship with your site. Anywhere a shortcode or partial takes an icon parameter, the value goes through this resolver.

Iconify icons

Iconify exposes 200,000+ icons from 150+ sets under a uniform naming scheme: set:name. Liftoff fetches the SVG once at build time and caches it.

Docs-only site

Mon, 01 Jan 0001 00:00:00 +0000

Some projects are the documentation. The home page exists only to get people into the docs, and everything else in the theme comes off.

Front matter

A short hero, no code block. The landing page is a signpost, not a pitch.

 yaml
 
 
---
title: "Widget Handbook"
description: "Everything Widget can do, in one place."
hero:
 title: "The complete"
 titleAccent: "Widget handbook."
 subtitle: "Install, configure, extend. Updated with every release."
 primary:
 label: "Start reading"
 url: "/docs/installation"
 secondary:
 label: "Source"
 url: "https://codeberg.org/you/widget"
---

Body

 markdown
 
 
{{< section width="narrow" >}}
{{< feature-grid >}}
 {{< feature-card title="Install" icon="mdi:download-outline" url="/docs/installation" >}}
 Package managers, binaries, and building from source.
 {{< /feature-card >}}
 {{< feature-card title="Configure" icon="mdi:cog-outline" url="/docs/configuration" >}}
 Every option, with defaults and examples.
 {{< /feature-card >}}
 {{< feature-card title="Extend" icon="mdi:puzzle-outline" url="/docs/plugins" >}}
 Write a plugin in about thirty lines.
 {{< /feature-card >}}
{{< /feature-grid >}}
{{< /section >}}

Removing the other sections

Deleting a content folder is only half the job. The menu entries survive and turn into dead links, so remove those too.

Landing pages

Mon, 01 Jan 0001 00:00:00 +0000

A landing page combines a hero, content sections built from shortcodes, and a closing CTA. The hero is driven by front matter; everything else is markdown.

Hero from front matter

 yaml
 
 
hero:
 title: "From zero to"
 titleAccent: "a running site."
 subtitle: "Pick your platform, drop in the theme, write content."
 highlights:
 - icon: "mdi:code-tags"
 label: "Any language"
 - icon: "mdi:translate"
 label: "Multilingual"
 primary:
 label: "Install"
 url: "#install"
 secondary:
 label: "See blueprints"
 url: "/blueprints"
 code:
 language: bash
 content: |
 hugo server

Field	Purpose
`title`	Headline, rendered as the page `h1`
`titleAccent`	Second half of the headline, in the accent colour
`subtitle`	Lead paragraph, parsed as markdown
`highlights`	List of `{ icon, label }` pills below the subtitle
`primary` / `secondary`	Buttons, each `{ label, url }`
`code`	Single code block: `{ language, content }`
`code.tabs`	Multiple code blocks, see below

url values are resolved with relLangURL, so write them without a language prefix: /docs, not /en/docs.

Public changelog

Mon, 01 Jan 0001 00:00:00 +0000

A changelog is the articles layout with different vocabulary: one page per release, newest first, tagged by change type. Point it at its own section so your actual writing stays separate.

Section front matter

Create content/releases/_index.md. The articles layout is reused by matching the section name in your own layouts/ folder, or by keeping the content under content/articles/ if you have no blog.

 yaml
 
 
---
title: "Releases"
description: "Every change to Widget, newest first."
hero:
 title: "What changed, and"
 titleAccent: "when it changed."
 subtitle: "Every release since 1.0, with upgrade notes."
 highlights:
 - icon: "mdi:tag-outline"
 label: "Semantic versioning"
 - icon: "mdi:rss"
 label: "RSS feed"
---

One page per release

Name the file after the version. The date drives the ordering, the tags drive the filtering.

Shortcodes

Mon, 01 Jan 0001 00:00:00 +0000

Liftoff ships a small set of shortcodes you can compose freely. Each entry lists its parameters, a code example, and a live preview.

Two features need no shortcode at all, because they are markdown render hooks: callouts and code blocks.

Callouts

Blockquotes starting with an alert marker render as a callout. The label is translated through i18n, so it follows the page language.

 markdown
 
 
> [!NOTE]
> Neutral background information.

> [!TIP]
> A shortcut or a better approach.

> [!WARNING]
> Something that bites later.

> [!DANGER]
> Something that breaks the build now.

[!CAUTION] is accepted as an alias for [!DANGER]. A blockquote without a marker renders as a plain quotation.

Every markdown element, on one page

Fri, 10 Jul 2026 00:00:00 +0000

This article exists to be ugly on purpose. It runs through every markdown element the theme styles, so you can check typography, spacing, and dark-mode contrast in one place. If something looks wrong here, it will look wrong in your content too.

Every section shows the source first, then the result.

Shipping a docs site in an afternoon

Sun, 28 Jun 2026 00:00:00 +0000

Most documentation sites die of structure, not of prose. You spend the first afternoon on the generator, the second on navigation, and by the third you have written four pages and lost interest. This walkthrough skips to the part where you are writing.

Start from the module, not from a fork

Add Liftoff as a Hugo module rather than copying it into themes/. You keep the ability to update, and your repository stays small enough to read.

Icons without a build step

Fri, 12 Jun 2026 00:00:00 +0000

Icon fonts ship every glyph to every visitor. Sprite sheets need a build step and a naming convention nobody remembers. Liftoff takes a third route: it fetches each icon from the Iconify API while Hugo builds, and inlines the SVG.

 go-html-template
 
{{ partial "icon.html" "simple-icons:codeberg" }}

Any set on Iconify works, addressed as set:name. A bare name falls back to Material Design Icons, so check and mdi:check are the same icon.

Multilingual from day one

Sun, 24 May 2026 00:00:00 +0000

Retrofitting a second language is the kind of task that looks like an afternoon and turns into a weekend. Every content file needs a counterpart, every menu entry needs a translation, every data file needs a variant, and every hardcoded date format turns out to be English.

Configuring it up front costs almost nothing, even if you only ever ship one language.

 toml
 
 
defaultContentLanguage = "en"
defaultContentLanguageInSubdir = true

[languages]
 [languages.en]
 label = "English"
 weight = 1

Content files then carry their language in the filename: about.md and about.de.md sit side by side and Hugo pairs them automatically.

A performance budget you can actually keep

Fri, 15 May 2026 00:00:00 +0000

A performance budget only works if it is short enough to remember. Three numbers are enough for a content site.

Budget	Target	What breaks it
Requests per page	Under 10	Web fonts, analytics
CSS	Under 30 kB	Utility frameworks
JavaScript	Under 10 kB	Anything with a build

Liftoff spends its JavaScript on three things: the theme toggle, the copy buttons on code blocks, and the blueprint filter. All three degrade to something usable when scripting is off, which is the only reason they are allowed to exist at all.

Dark mode that respects the system

Fri, 08 May 2026 00:00:00 +0000

A theme toggle that defaults to dark for everyone is a preference disguised as a feature. Liftoff reads prefers-color-scheme first, and only writes to localStorage once someone actually picks a scheme.

 js
 
 
const stored = localStorage.getItem("liftoff.theme");
const system = matchMedia("(prefers-color-scheme: light)").matches;

That ordering matters. A visitor whose system is light gets a light page on first load, without a flash of dark. A visitor who then picks dark keeps dark, even if their system changes later, because an explicit choice outranks an inferred one.

On design tokens

Sat, 02 May 2026 00:00:00 +0000

Liftoff exposes its palette, spacing scale, and typography as CSS custom properties on :root. Consumers can theme the site without forking the theme.

Override pattern

Drop a small CSS file into your site’s assets/css/ and import it after the theme’s bundle.

 css
 
 
:root {
 --color-accent: #ff7a59;
 --color-bg: #0d0a0a;
}

Light mode is opt-in by setting data-theme="light" on <html>. The built-in toggle remembers the user’s choice in localStorage with prefers-color-scheme as the fallback.

Hello, Liftoff

Wed, 15 Apr 2026 00:00:00 +0000

I kept rebuilding the same scaffold for every small product page: a hero with a code block, OS-specific install tabs, a feature grid, a docs section, and a closing CTA. Liftoff bundles those pieces into one Hugo theme with sensible dark-first defaults.

What’s in the first cut

Hero partial driven by front matter
OS tabs as a CSS-light shortcode
Code blocks with copy buttons
Feature, integrations, pricing, testimonial, and CTA shortcodes
Docs layout with card index, on-this-page TOC, and prev/next navigation
Blog and showcase sections

Where it’s going

Internationalisation strings ship for German and English. More languages are a i18n/<lang>.yaml file away.