Templates

Raw Markdown View this page on GitHub

Templates

To change the markup of the pages, as the links of the header and the footer, put templ files in the docs folder. The pages show templ DocpagesMain of these files, in place of the built-in page:

docs/template.templ
package docs

import "github.com/romshark/docpages"

templ DocpagesMain(p docpages.Page) {
	@docpages.Layout(p, docpages.Parts{
		HeaderLinks: docpages.HeaderLinks(p,
			docpages.Link{Title: "Docs", URL: "README.md"},
			docpages.Link{Title: "FAQ", URL: "4-more/1-faq.md", Icon: faqIcon()},
		),
		FooterLinks: docpages.FooterLinks(p,
			docpages.Link{Title: "Changelog", URL: "3-reference/2-changelog.md"},
		),
		FooterEnd: license(),
	})
}

templ faqIcon() {
	<svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor">
		<circle cx="12" cy="12" r="10"></circle>
	</svg>
}

templ license() {
	<span>MIT License © 2026 Jane Doe</span>
}

Every .templ file of the docs folder is package docs, and 1 of them has templ DocpagesMain(p docpages.Page). Without .templ files, the pages show the built-in page, with 1 link in the header, "Docs", to the first page.

A docs folder with .templ files is a Go module that requires docpages:

cd docs
go mod init docs
go get -tool github.com/romshark/docpages/cmd/docpages@latest

The tool directive keeps the requirement through go mod tidy, which finds no import of docpages in .templ files. go tool docpages in the docs folder runs the version that go.mod requires.

The built-in page

docpages.Layout is the built-in page. It takes parts of your own:

Part What it adds
Head Elements at the end of <head>, as fonts or a script.
Banner A notice across the top of the page, above the header.
HeaderLinks Links of the header, before the link to your repository.
FooterLinks Links of the footer, between the link to your repository and llms.txt.
FooterEnd The end of the footer, as a license.

Head can load a font for style.css:

docs/template.templ
templ DocpagesMain(p docpages.Page) {
	@docpages.Layout(p, docpages.Parts{Head: fonts()})
}

templ fonts() {
	<link rel="preconnect" href="https://fonts.googleapis.com"/>
	<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin/>
	<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap"/>
}
docs/style.css
:root {
  --font-sans: Inter, sans-serif;
}

docpages.HeaderLinks and docpages.FooterLinks write links. Each docpages.Link has a Title, a URL and an optional Icon, a templ of an <svg>. Draw it with currentColor and it takes the color of the text in both themes.

A URL works like a link of docs/README.md. A Markdown file leads to its page, any other file of the repository to the file in the repository, and a full URL off the site. A page that a release lacks leads to the page of main. A link to a file or a heading that doesn't exist fails the build.

A header link is highlighted on the page it leads to. A link to the first page is highlighted on every page that no other link leads to.

For a link of your own, p.URL takes the same URLs:

<a href={ p.URL("2-guide/1-events.md#dispatch") }>Dispatch</a>

Releases

The template of the docs folder renders the pages of main and of every release. p.Version is main or the release, as v1.2, so the template can change the pages of a release:

templ DocpagesMain(p docpages.Page) {
	@docpages.Layout(p, docpages.Parts{Banner: banner(p)})
}

func banner(p docpages.Page) templ.Component {
	if p.Version == "v0.9" {
		return oldBanner(p.Versions[0])
	}
	return nil
}

templ oldBanner(latest docpages.VersionLink) {
	<p class="old-banner">
		v0.9 has a known vulnerability.
		<a href={ latest.Href }>Upgrade to { latest.Version }</a>.
	</p>
}

Compare a version with ==, since < sorts v0.10 before v0.9. p.Versions lists the releases, the latest first, then main. The Href of each leads to the same page in that version, so the banner of a v0.9 page links that page in the latest release.

A page of your own

p holds all that a page shows, as p.Title, p.Body, p.Navigation and p.Versions. The built-in page is made of parts that you can use on their own:

Part What it shows
Head(p) <head> with the title, the styles and the scripts, then the elements inside it, as fonts. Every page needs it.
Body(p) <body>, which the styles and the search need, with a link that skips to the text.
Header(p) The logo, the version menu of a site with releases, the links in it, the search, the button of offline viewing and the theme switch, then ContentsBar(p). On a phone, the header and the bar hide as you scroll down.
HeaderWithoutContents(p) Header(p) without ContentsBar(p), for a page that shows the bar elsewhere. On a phone, the header stays.
ContentsBar(p) A bar with the contents of the page on screens too narrow for Contents(p). Outside Header(p), it sticks at the top of the element around it.
Navigation(p) The navigation.
Main(p) The note of the version, the text and the links to the previous and the next page.
Contents(p) The contents of the page, beside the text on wide screens.
Footer(p, end) The links in it and end.
Search(p), VersionSelect(p), Offline(p), ThemeSwitch() The controls of Header.
docs/template.templ
package docs

import "github.com/romshark/docpages"

templ DocpagesMain(p docpages.Page) {
	<!DOCTYPE html>
	<html lang="en">
		@docpages.Head(p)
		@docpages.Body(p) {
			@docpages.Header(p)
			<div class="docs">
				@docpages.Navigation(p)
				@docpages.Main(p)
			</div>
		}
	</html>
}

The Go reference lists every field of docpages.Page.

Build

A build with .templ files needs the go command, and fails without it. docpages builds a renderer in the docs module and renders the pages with it. The Go of your files and of the renderer stays in docpages/ of your user cache directory, as ~/.cache/docpages/ on Linux, so the build writes nothing to the docs folder. The first build takes a while, and later builds use the Go build cache. -serve builds again when you change a .templ or .go file, and shows a mistake in the page.

Your files can import the packages of the docs module and of the modules it requires. A .go file next to the .templ files is package docs too, as with a function that the templates call. A package in a subfolder can hold .templ files as well. The build needs the _templ.go files that templ generate writes for them, as docpages generates Go only for the .templ files of the docs folder.

The renderer uses the running docpages, not the version that go.mod requires. The running docpages must be compatible with that version, which means the same major version and no older. Below v1, the minor version must be the same too. Otherwise the build fails and names the command that runs the required version:

docs/go.mod requires github.com/romshark/docpages v0.4.0, incompatible with the running v0.3.2
run: go run github.com/romshark/docpages/cmd/docpages@v0.4.0 -serve 127.0.0.1:7340 docs

A docpages built from source, not from a release, skips the check. So does a docs module that replaces docpages with a folder, which then names no release.

templ generate writes a _templ.go file next to each .templ file, which docpages ignores.

A docs folder at the root of the repository takes no templates. Its .templ files belong to the repository.