Create a theme
This tutorial makes a theme called Sand: the engine’s layout with its
own footer, its own colours and an accent colour the site’s
administrator can change. It takes a site running from source
(Run from source) with
env: local, so template edits show up without a restart.
A quick start
Section titled “A quick start”app theme new writes such a theme’s starting files - a manifest with
the engine’s regions and an accent colour, a stylesheet, a Russian
catalog of its strings and a README:
app theme new sand # in themes/sandapp theme new sand -dir ../kosatka-theme-sand # a repository of its ownIt is ready to preview on the Appearance page and passes app theme check. The steps below build a theme by hand and explain each part.
1. Make the directory
Section titled “1. Make the directory”In the project’s directory:
mkdir -p themes/sand/templates/partials themes/sand/static/css themes/sand/translationsThe directory’s name (sand) is the theme’s key: it is in its asset
URLs (/static/themes/sand/…), in the admin’s addresses and in the
database’s block layout. Use lowercase latin letters, digits, - and
_, and don’t rename it later.
2. Write the manifest
Section titled “2. Write the manifest”themes/sand/theme.yaml:
name: Sanddescription: A warm light theme with a credit line in the footer.version: 0.1.0author: Example Studiolicense: MITtags: [light, two-columns]default_region: sidebarregions: - id: header label: Header - id: sidebar label: Sidebar - id: content_top label: Content top - id: content_bottom label: Content bottom - id: content_inline label: Inside content (content page) - id: footer label: Footer - id: footer_bottom label: Footer bottom lineblocks: - plugin: copyright region: footer_bottomsettings: - id: accent label: Accent colour type: color default: "#b45309" css_var: --sand-accent - id: credit label: Credit line in the footer type: bool default: trueregionsare the areas the theme’s templates (and the engine’s templates it keeps) render blocks into. These are the engine’s own regions: keeping their IDs means the blocks placed for the current theme land in the same places when the site switches to Sand.blocksplaces the copyright line in the footer the first time the theme gets a block layout.settingsadds two options to the theme’s settings page: a colour that becomes the CSS variable--sand-accent, and an on/off switch that the footer template reads.
Every key is described in the manifest reference. Name, labels and description are written in English; other languages come from the theme’s translations.
3. Replace a template
Section titled “3. Replace a template”The engine’s footer is web/templates/footer.html. A file with the same
relative path in the theme replaces it. Copy it and add a line:
themes/sand/templates/footer.html:
{{define "footer"}}<footer class="site-footer"> <div class="container"> {{if regionHasBlocks "footer" .}} <div class="site-footer-region"> {{template "region_blocks" (dict "Region" (region "footer") "Ctx" .)}} </div> {{end}} {{template "region_blocks" (dict "Region" (region "footer_bottom") "Ctx" .)}} {{if themeSetting "credit"}} <p class="sand-credit">{{t "Made of sand and patience"}}</p> {{end}} </div></footer>{{template "html_scripts" .}}{{template "html_end" .}}{{end}}region_blocksrenders the blocks placed in a region;regionHasBlocksleaves the wrapper out when there are none.themeSetting "credit"is the switch from the manifest (trueorfalse),ttranslates a string to the page’s language.- The footer must end with
html_scriptsandhtml_end: they load the engine’s scripts and close the document. See Templates.
4. Add a stylesheet
Section titled “4. Add a stylesheet”themes/sand/static/css/sand.css:
:root { --bs-body-bg: #fdf8f0; --bs-body-color: #2b2118; --bs-border-color: #eadfcf;}
.site-header { border-bottom: 3px solid var(--sand-accent, #b45309);}
.site-name,.sand-credit { color: var(--sand-accent, #b45309);}The engine’s markup uses Bootstrap 5 classes, so a theme mostly changes
Bootstrap’s variables and styles the engine’s classes (site-header,
site-name…). --sand-accent is set by the engine from the theme’s
setting.
Pages link to the minified file, sand.min.css. Build it, and again
after each change to the CSS:
./scripts/minify_css.sh5. Link the stylesheet
Section titled “5. Link the stylesheet”The engine links the theme’s styles through the hooks in
partials/theme_head.html. A theme’s copy of that file replaces the
engine’s, and defines all three hooks.
themes/sand/templates/partials/theme_head.html:
{{define "theme_framework"}} <link rel="stylesheet" href="{{ staticCSS "bootstrap" }}">{{end}}{{define "theme_head"}} <link rel="stylesheet" href="{{ staticCSS "base" }}"> <link rel="stylesheet" href="{{ themeCSS "sand" }}">{{end}}{{define "theme_editor_css"}}{{ staticCSS "bootstrap" }},{{ staticCSS "base" }},{{ themeCSS "sand" }}{{end}}theme_framework- the Bootstrap build: the engine’s Bootstrap 5.3 here.theme_head- the engine’s neutralbase.css, then the theme’s CSS.themeCSS "sand"is/static/themes/sand/css/sand.min.css?v=….theme_editor_css- the same styles for the text editors, so text being edited looks as it does on the page (a comma-separated list of URLs).
A shorter way, when the engine’s hooks suit you (Bootstrap, light or dark
as the visitor’s device is, and base.css): leave
partials/theme_head.html out and add stylesheets: [sand] to the
manifest. The engine then links css/sand.min.css after its own styles
(the text editors don’t get it then: the engine’s theme_editor_css is
empty). See Stylesheets.
6. Make it active
Section titled “6. Make it active”Open Appearance (/admin/config/appearance). Sand is in
the list. If it isn’t, its manifest has an error: a theme whose
theme.yaml doesn’t parse or fails a check is left out of the list, and
the page names its directory above the list with what is wrong. Compare
it with the manifest reference.
- Preview shows your site in Sand to you alone; the visitors keep the active theme.
- Settings shows the accent colour and the credit switch. Change the colour and press Save and preview.
- Set as default switches the site to Sand, at once.
The Blocks page (/admin/config/blocks) now has a Sand tab with the
blocks copied from the previous theme and the copyright line.
7. See what rendered what
Section titled “7. See what rendered what”Stop the server and start it again with template debugging:
TEMPLATES_DEBUG=1 go run ./cmd/appThe page source then has comments naming the template files used, the theme first:
<!-- PAGE: home/index.html - theme: sand → (engine) -->…<!-- BEGIN footer - themes/sand/templates/footer.html -->To change another part of the page, find the file in these comments and copy it into the theme under the same path. See Template debugging.
What changes need a restart
Section titled “What changes need a restart”With env: local templates show up on reload, and CSS too once
minified. The browser keeps static files for a year under the same
?v=, though: after changing a stylesheet, reload bypassing the cache (a
hard reload, or with the cache off in the browser’s developer tools).
The server reads some things once per run and needs a restart after you change them:
- the theme’s settings,
base,stylesheets,faviconandlogointheme.yaml(regions, labels and description are re-read by the admin pages); - the theme’s
translations/*.json.
- Replace more templates: Templates.
- Translate the strings: Translations.
- Build on an existing theme instead of starting from the engine: Subthemes.
- Publish it: Distributing a theme.
- Give it a demo site, installed with one command: A theme’s demo site.