Documentation on 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

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.

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.

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.

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.