fugo

abs_url

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

Signature

x | abs_url

Absolute URL against baseURL (base path kept).

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

defined

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

Signature

x is defined

The value is defined.

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

fugo

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

The command line

Usage#

fugo [OPTIONS]
 fugo <COMMAND>

Commands#

fugo build: Builds the site into the publish directory (the default command)
fugo server: Builds the site into memory, serves it with live reload, and rebuilds it when files change (Go’s development server; environment development by default)
fugo templates: Template tooling
fugo config: Prints the resolved configuration
fugo cms: Content editor ([cms]) tooling
fugo version: Prints the version

Options#

-b, --base-url <URL>: The site’s base URL
-t, --theme <THEMES>: Themes to use (comma-separated)
--cache-dir <DIR>: The cache directory
--ignore-cache[=BOOL]: Ignores the cache directory
-D, --build-drafts[=BOOL]: Includes content marked as draft
-E, --build-expired[=BOOL]: Includes expired content
-F, --build-future[=BOOL]: Includes content with a publish date in the future
--clean-destination-dir[=BOOL]: Removes files from the publish directory that the static directories do not have
--no-times[=BOOL]: Does not copy the static files’ modification times (config noTimes)
--no-chmod[=BOOL]: Does not copy the static files’ permissions (config noChmod)
--minify[=BOOL]: Minifies the supported output formats
--threads <N>: The render thread count (default: RAYON_NUM_THREADS, else the CPUs). The output does not depend on it

Global options#

Every command takes these.

get_asset

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

Signature

get_asset(path=)

The asset at path under assets/, or none.

Arguments#

Argument	Type	Required
`path`	string	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

get_env

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

Signature

get_env(name=)

An environment variable ("" when unset): one the project’s .env file defines (the process environment wins), or one security.funcs.getenv allows; any other name is an error.

Arguments#

Argument	Type	Required
`name`	string	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

get_page

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

Signature

get_page(path=, lang=?, page=?)

The full value of the page at path (relative paths resolve against page), or none.

Arguments#

Argument	Type	Required
`path`	string	yes
`lang`	string	no
`page`	page	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

i18n

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

Signature

i18n(key=, count=?, data=?, page=?)

The translation of key in page’s language; count picks the plural form, data fills {{ .Field }}.

Arguments#

Argument	Type	Required
`key`	string	yes
`count`	number	no
`data`	any	no
`page`	page	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

length

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

Signature

x | length

Length of a string (characters), array or map.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

lower

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

Signature

x | lower

Lower case.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

now

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

Signature

now()

The build time (honours --clock) as a date value.

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Page

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

page in layouts, shortcodes and render hooks, and every element of a page list (site.pages, page.pages, a pager’s pages, …). A list holds summary values: every field below except the relations (parent … term), which only the page being rendered has; get_page, deref and page.parent give a full value. The content fields (content … len) are not available while content is rendered (shortcodes, render hooks): use page_content(page=…) and its siblings there.

resize

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

Signature

x | resize(width=?, height=?, format=?, quality=?, filter=?, anchor=?, spec=?)

Resizes to width and/or height (or a spec string in Go’s syntax, e.g. "600x400 webp q75").

Arguments#

Argument	Type	Required
`width`	int	no
`height`	int	no
`format`	string	no
`quality`	int	no
`filter`	string	no
`anchor`	string	no
`spec`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

safe

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

Signature

x | safe

Marks the value safe.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

super

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

Signature

super()

The parent block’s content (inside {% block %} only).

Details#

Kind: Function, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

throw

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

Signature

throw(message=)

Aborts the render at once with message.

Arguments#

Argument	Type	Required
`message`	string	yes

Details#

Kind: Function, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

date

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

Signature

x | date(format=?, style=?, locale=?)

Formats a date with strftime format or style (short, medium, long, full). A style is localized in locale (default: the render’s lang; Thai uses the Gregorian calendar); a format’s month and weekday names are English (Go’s .Format) unless locale is given (time.Format, dateFormat: locale=lang). Accepts a date value, a date string or Unix seconds; none prints nothing.

Arguments#

Argument	Type	Required
`format`	string	no
`style`	string	no
`locale`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

default

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

Signature

x | default(value=, boolean=?)

value when the input is undefined (only then; boolean=true also replaces falsy values). Not Go’s default.

Arguments#

Argument	Type	Required
`value`	any	yes
`boolean`	bool	no

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

deref

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

Signature

x | deref

The full value (with relations) of a listed summary page.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

escape

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

Signature

x | escape

Tera’s escape (leaves safe input alone). Go’s html is html_escape.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

fill

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

Signature

x | fill(width=?, height=?, format=?, quality=?, filter=?, anchor=?, spec=?)

Crops and resizes to fill width×height at anchor.

Arguments#

Argument	Type	Required
`width`	int	no
`height`	int	no
`format`	string	no
`quality`	int	no
`filter`	string	no
`anchor`	string	no
`spec`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

find_asset

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

Signature

find_asset(pattern=)

The first asset matching the glob pattern, or none.

Arguments#

Argument	Type	Required
`pattern`	string	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

log_error

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

Signature

log_error(message=)

Records an error with the template position; the build fails when it ends. Prints nothing.

Arguments#

Argument	Type	Required
`message`	string	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

partial

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

Signature

partial(name=, …)

Renders _partials/<name> with the kwargs as top-level names; returns its return_value or the rendered string.

Arguments#

Argument	Type	Required
`name`	string	yes

Further keyword arguments are passed on.

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

read_file

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

Signature

read_file(path=)

A file of the project (security rules apply).

Arguments#

Argument	Type	Required
`path`	string	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

rel_url

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

Signature

x | rel_url

Root-relative URL with the base path.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

Site

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

site: the site of the language being rendered.

Fields#

all_pages: Every page in every language.
base_url: The base URL, e.g. https://example.org/.
config: The configuration the embedded templates read: services and privacy, in snake case, e.g. site.config.services.rss.limit.
copyright: copyright.
data: The data files of data/, e.g. site.data.authors.
home: The home page.
is_multilingual: Whether more than one language is configured.
lang: The language code.
language: The site’s language.
language_code: languageCode, e.g. en-US.
languages: Every configured language, by weight.
last_mod: The latest lastmod of the site’s pages.
main_sections: The mainSections configuration, else the section with the most regular pages.
menus: {menu: [menu entry]} (see menu entry), e.g. site.menus.main.
pages: Every page of the language: regular pages and list pages.
params: The site parameters (params), keys lower case.
regular_pages: The regular pages of the language.
sections: The top-level sections.
server_port: The port of the base URL (the server’s port under fugo server), 0 without one.
sitemap_abs_url: The absolute URL of the language’s sitemap.
taxonomies: {plural: {key: term entry}}: every term of every taxonomy with its pages, e.g. site.taxonomies.tags.rust.pages (see taxonomy).
title: The site title (title).

undefined

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

Signature

x is undefined

The value is undefined.

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

upper

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

Signature

x | upper

Upper case.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

abs_lang_url

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

Signature

x | abs_lang_url(page=?)

abs_url with the language prefix of page’s language.

Arguments#

Argument	Type	Required
`page`	page	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

capitalize

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

Signature

x | capitalize

First character upper, the rest lower.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

default_if_empty

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

Signature

x | default_if_empty(value=)

Go’s default: value when the input is undefined, none, 0, “”, or an empty array or map. false counts as set.

Arguments#

Argument	Type	Required
`value`	any	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

escape_html

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

Signature

x | escape_html

Tera’s HTML escape of a string.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

file_exists

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

Signature

file_exists(path=)

Whether a project file exists.

Arguments#

Argument	Type	Required
`path`	string	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

find_assets

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

Signature

find_assets(pattern=)

All assets matching pattern.

Arguments#

Argument	Type	Required
`pattern`	string	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

fit

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

Signature

x | fit(width=?, height=?, format=?, quality=?, filter=?, anchor=?, spec=?)

Downscales to fit width×height.

Arguments#

Argument	Type	Required
`width`	int	no
`height`	int	no
`format`	string	no
`quality`	int	no
`filter`	string	no
`anchor`	string	no
`spec`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

get_terms

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

Signature

get_terms(taxonomy=, page=?)

The term links of page for taxonomy; [] when it is not a taxonomy.

Arguments#

Argument	Type	Required
`taxonomy`	string	yes
`page`	page	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

Language

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

site.language, page.language and the elements of site.languages.

Fields#

code: languageCode, else the key.
direction: languageDirection: ltr or rtl.
lang: The language key, e.g. en.
name: languageName, e.g. English.
params: The language’s params.
weight: The language’s weight.

log_warn

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

Signature

log_warn(message=, id=?)

Records a warning; id lets ignoreLogs suppress it. Prints nothing.

Arguments#

Argument	Type	Required
`message`	string	yes
`id`	string	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

none

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

Signature

x is none

The value is none (zero dates serialise as none).

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

partial_cached

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

Signature

partial_cached(name=, key=, …)

partial memoised on (name, key).

Arguments#

Argument	Type	Required
`name`	string	yes
`key`	any	yes

Further keyword arguments are passed on.

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

to_date

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

Signature

x | to_date

Parses a string or number into a date value ({rfc3339, unix}).

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

crop

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

Signature

x | crop(width=?, height=?, format=?, quality=?, filter=?, anchor=?, spec=?)

Crops to width×height at anchor.

Arguments#

Argument	Type	Required
`width`	int	no
`height`	int	no
`format`	string	no
`quality`	int	no
`filter`	string	no
`anchor`	string	no
`spec`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

dump

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

Signature

x | dump

Pretty-printed JSON of any value.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

escape_xml

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

Signature

x | escape_xml

Tera’s XML escape (", '; leaves safe input alone). Go’s transform.XMLEscape is xml_escape.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

get

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

Signature

x | get(key=, default=?)

The map entry key, else default, else an error.

Arguments#

Argument	Type	Required
`key`	string	yes
`default`	any	no

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

get_remote

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

Signature

get_remote(url=, options=?, optional=?)

A remote resource (options: headers, method, body, key). Errors propagate unless optional=true (then none and a warning).

Arguments#

Argument	Type	Required
`url`	string	yes
`options`	map	no
`optional`	bool	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

max

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

Signature

max(values=)

The largest of values (numbers).

Arguments#

Argument	Type	Required
`values`	array	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Page link

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

A small page value: the elements of page.terms.<taxonomy> and the pages menus point to.

Fields#

id: The page’s id.
kind: The page’s kind.
lang: The page’s language.
link_title: The page’s link title.
path: The page’s logical path.
permalink: The page’s absolute URL.
rel_permalink: The page’s URL path.
title: The page’s title.

rel_lang_url

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

Signature

x | rel_lang_url(page=?)

rel_url with the language prefix of page’s language.

Arguments#

Argument	Type	Required
`page`	page	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

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

Signature

related(pages=, page=?, indices=?, fragments=?, keywords=?, limit=?)

Pages related to page among pages, best first, per the related config: indices limits the search to some indices, fragments adds heading ids to the fragments indices, keywords adds keywords by index name ({"tags": ["rust"]}), page=none searches the fragments and keywords alone. When a fragments index with applyFilter matched, each result’s fragments holds only the matched headings.

return_value

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

Signature

return_value(value=)

Sets the value the enclosing partial() returns. Prints nothing.

Arguments#

Argument	Type	Required
`value`	any	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

string

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

Signature

x is string

A string.

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

title

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

Signature

x | title

Tera’s naive title case. Go’s title is title_case.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

concat_assets

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

Signature

concat_assets(target=, items=)

Concatenates items into a resource at target.

Arguments#

Argument	Type	Required
`target`	string	yes
`items`	array	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

get_path

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

Signature

x | get_path(path=)

Walks path (keys and integer indices); none when a step is missing.

Arguments#

Argument	Type	Required
`path`	array	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Menu entry

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

An element of site.menus.<menu> and of an entry’s children.

Fields#

children: The child entries.
has_children: Whether the entry has children.
identifier: The entry’s identifier.
key_name: The identifier, else the name: the key parent refers to.
name: The text of the entry.
page: The page the entry points to, or none.
params: The entry’s params.
parent: The key_name of the parent entry, or "".
post: post: HTML after the name (safe).
pre: pre: HTML before the name (safe).
title: The title attribute, else the page’s link title.
url: The URL: the page’s, or the entry’s url.
weight: The entry’s weight.

min

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

Signature

min(values=)

The smallest of values (numbers).

Arguments#

Argument	Type	Required
`values`	array	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

number

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

Signature

x is number

A number.

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

param

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

Signature

param(key=, page=?)

The page param key (a dotted path), else the site param.

Arguments#

Argument	Type	Required
`key`	string	yes
`page`	page	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

process

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

Signature

x | process(width=?, height=?, format=?, quality=?, filter=?, anchor=?, spec=?)

Any of the above per spec (or the typed kwargs).

Arguments#

Argument	Type	Required
`width`	int	no
`height`	int	no
`format`	string	no
`quality`	int	no
`filter`	string	no
`anchor`	string	no
`spec`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

ref

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

Signature

ref(path=, lang=?, output_format=?, page=?)

The permalink of the page at path; unresolved per refLinksErrorLevel.

Arguments#

Argument	Type	Required
`path`	string	yes
`lang`	string	no
`output_format`	string	no
`page`	page	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

template_exists

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

Signature

template_exists(name=)

Whether a template called name exists.

Arguments#

Argument	Type	Required
`name`	string	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

title_case

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

Signature

x | title_case(style=?)

Title case in style (ap, chicago, go, firstupper, none; default: titleCaseStyle).

Arguments#

Argument	Type	Required
`style`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

xml_escape

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

Signature

x | xml_escape

Drops the characters XML forbids, then escapes & < > " ', tab, newline and CR (" ' 	 
 , Go’s xml.EscapeText) even when the input is safe; the result is safe.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.

abs

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

Signature

x | abs

Absolute value.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

asset_from_string

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

Signature

asset_from_string(target=, content=)

A resource at target with content.

Arguments#

Argument	Type	Required
`target`	string	yes
`content`	string	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

defer

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

Signature

defer(template=, key=, data=?)

A placeholder; template is rendered once per key with data after all pages.

Arguments#

Argument	Type	Required
`template`	string	yes
`key`	string	yes
`data`	any	no

Details#

Kind: Function, implemented by fugo.
Available in: layouts and partials only, not shortcodes or render hooks.
Output: safe HTML, not escaped.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

first

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

Signature

x | first

The first element, or none.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

html_escape

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

Signature

x | html_escape

Escapes & < > " ' even when the input is safe; the result is safe.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.

image_filter

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

Signature

x | image_filter(filters=)

Applies filters, a list of {"op": …} maps, one per Go images.* filter: brightness, color_balance, colorize, contrast, gamma, gaussian_blur, grayscale, hue, invert, saturation, sepia, sigmoid, unsharp_mask, pixelate, opacity, padding, overlay and mask (image: a resource), auto_orient, text (text, color, size, x, y, alignx, aligny, linespacing, font: a font resource), dither (colors, method, serpentine, strength), process (spec). E.g. img | image_filter(filters=[{"op": "text", "text": page.title, "size": 40}, {"op": "dither"}]).

integer

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

Signature

x is integer

An integer.

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Pager

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

What paginator() and paginate(pages=…) return. The embedded _partials/pagination.html renders the navigation.

Fields#

first: The first pager’s {page_number, url}.
has_next: Whether there is a next pager.
has_prev: Whether there is a previous pager.
last: The last pager’s {page_number, url}.
next: The next pager’s {page_number, url}, or none.
page_number: The number of this pager, from 1.
pager_size: The number of pages per pager.
pagers: Every pager’s {page_number, url}.
pages: The pages of this pager.
prev: The previous pager’s {page_number, url}, or none.
total_number_of_elements: The number of pages over all pagers.
total_pages: The number of pagers.
url: The URL path of this pager.

paginator

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

Signature

paginator()

The pager of the current (page, format) over its default list. Recorded: the first call wins.

Details#

Kind: Function, implemented by fugo.
Available in: layouts and partials only, not shortcodes or render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

rel_ref

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

Signature

rel_ref(path=, lang=?, output_format=?, page=?)

The relative permalink of the page at path.

Arguments#

Argument	Type	Required
`path`	string	yes
`lang`	string	no
`output_format`	string	no
`page`	page	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

wordcount

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

Signature

x | wordcount

Tera’s word count (whitespace split).

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

arg

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

Signature

x | arg(index=?, name=?, default=?)

A shortcode argument by position index or by name, else default: shortcode | arg(index=0, default="").

Arguments#

Argument	Type	Required
`index`	int	no
`name`	string	no
`default`	any	no

Details#

Kind: Filter, implemented by fugo.
Available in: shortcodes and render hooks only.
Output: escaped like any value, unless marked safe.

exif

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

Signature

x | exif

EXIF data of an image, or none.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

float

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

Signature

x is float

A float.

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

get_resource

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

Signature

x | get_resource(name=)

The resource named name in a list (case-insensitive), or none.

Arguments#

Argument	Type	Required
`name`	string	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

html_unescape

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

Signature

x | html_unescape

Decodes HTML entities.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

last

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

Signature

x | last

The last element, or none.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

paginate

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

Signature

paginate(pages=, size=?)

The pager over pages. A re-call with another list or size is an error naming both positions.

Arguments#

Argument	Type	Required
`pages`	array	yes
`size`	int	no

Details#

Kind: Function, implemented by fugo.
Available in: layouts and partials only, not shortcodes or render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

parse_url

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

Signature

x | parse_url

{scheme, host, path, fragment, query, is_absolute, string}.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Resource

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

A page resource (page.resources), a global resource (get_asset), a remote resource (get_remote), or the result of a pipe (to_css, fingerprint, resize, …).

Fields#

__rid: An internal identifier the site functions read the resource back by; do not print it.
data: {integrity}: the integrity of a fingerprinted resource, else none.
height: The height of an image in pixels, else none.
integrity: The Subresource Integrity hash after fingerprint, e.g. sha256-….
media_type: Its media type.
name: The resource’s name: its path relative to the page bundle or assets/, or the name front matter gives it.
page_id: For a content file of a bundle (a page resource that is a page), that page’s id.
params: The params front matter resources gives it.
permalink: Its absolute URL; publishes the resource.
rel_permalink: Its URL path; publishes the resource.
resource_type: The main type of its media type, e.g. image.
title: The title front matter resources gives it, else the name.
width: The width of an image in pixels, else none.

round

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

Signature

x | round(method=?, precision=?)

method is common (default), ceil or floor; precision digits after the point.

Arguments#

Argument	Type	Required
`method`	string	no
`precision`	int	no

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

trim

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

Signature

x | trim(pat=?)

Trims whitespace, or the string pat repeatedly.

Arguments#

Argument	Type	Required
`pat`	string	no

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

bool

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

Signature

x is bool

A bool.

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

find_resource

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

Signature

x | find_resource(pattern=)

The first resource matching the glob pattern, or none.

Arguments#

Argument	Type	Required
`pattern`	string	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

image_colors

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

Signature

x | image_colors

Not implemented yet: calling it is an error (Go’s .Colors gives the dominant colours as hex strings).

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

int

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

Signature

x | int(base=?)

Converts to an integer; strings are parsed in base (default 10).

Arguments#

Argument	Type	Required
`base`	int	no

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

join_url

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

Signature

join_url(parts=)

Joins URL parts with single slashes.

Arguments#

Argument	Type	Required
`parts`	array	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

jsonify

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

Signature

x | jsonify(indent=?)

JSON with sorted keys, <>& escaped as \u003c…; indent pretty-prints.

Arguments#

Argument	Type	Required
`indent`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.

nth

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

Signature

x | nth(n=)

The element at index n, or none.

Arguments#

Argument	Type	Required
`n`	int	yes

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Shortcode

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

shortcode in a shortcode template. Read arguments with shortcode | arg(name=…) or arg(index=…).

Fields#

args: The positional arguments.
is_named_params: Whether the call uses named arguments.
name: The shortcode’s name.
ordinal: The shortcode’s position among the page’s calls, from 0.
params: The named arguments.
parent: The enclosing shortcode, or none.
position: The call’s position, file:line:column, for error messages.

store_set

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

Signature

store_set(key=, value=, page=?)

Sets key in the page store (content-phase writes are buffered per transaction); in a content adapter without page=, in the adapter’s store, which its runs for every language share. Prints nothing.

Arguments#

Argument	Type	Required
`key`	string	yes
`value`	any	yes
`page`	page	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

trim_start

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

Signature

x | trim_start(pat=?)

Trims leading whitespace, or pat.

Arguments#

Argument	Type	Required
`pat`	string	no

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Build

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

build: the version and the build environment, in every template. It replaces the Go templates’ site-info object.

Fields#

environment: The environment: production (build), development (server), or -e.
generator: <meta name="generator" content="fugo <version>"> (safe).
is_development: Whether the environment is development.
is_production: Whether the environment is production.
is_server: Whether the build runs in fugo server.
name: The program’s name, fugo (the RSS feeds’ <generator>).
version: fugo’s version, e.g. 1.0.0; check it with version_at_least.

find_resources

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

Signature

x | find_resources(pattern=)

All resources matching pattern.

Arguments#

Argument	Type	Required
`pattern`	string	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

float

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

Signature

x | float

Converts to a float.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

keys

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

Signature

x | keys

The keys of a map.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

map

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

Signature

x is map

A map.

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

path_ext

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

Signature

x | path_ext

Extension with the dot.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

qr_code

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

Signature

qr_code(text=, level=?, scale=?, target_dir=?)

A PNG image resource of the QR code of text, with Go’s bytes and name (<target_dir>/qr_<hash>.png): level low, medium (default), quartile or high; scale pixels per module (at least 2, default 4). E.g. qr_code(text=page.permalink, target_dir="images/qr").

Arguments#

Argument	Type	Required
`text`	string	yes
`level`	string	no
`scale`	int	no
`target_dir`	string	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

store_get

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

Signature

store_get(key=, page=?)

Reads key from the page store (in a content adapter without page=: the adapter’s store), or none.

Arguments#

Argument	Type	Required
`key`	string	yes
`page`	page	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

trim_end

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

Signature

x | trim_end(pat=?)

Trims trailing whitespace, or pat.

Arguments#

Argument	Type	Required
`pat`	string	no

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

unmarshal

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

Signature

x | unmarshal(format=?)

Parses a string or resource as JSON, TOML, YAML, CSV or XML (format overrides detection); keys sorted.

Arguments#

Argument	Type	Required
`format`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

add_page

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

Signature

add_page(page=)

Adds the page page describes to the adapter’s directory: path (relative, required but for kind: home), kind (default page), title, content ({mediaType, value}, default Markdown), dates ({date, lastmod, publishDate, expiryDate}), params, build, cascade, outputs and the other front matter fields (not lang, content.markup). A path added again replaces the earlier page. Prints nothing.

Arguments#

Argument	Type	Required
`page`	map	yes

Details#

Kind: Function, implemented by fugo.
Available in: content adapters (_content.html) and the partials they call only.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

array

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

Signature

x is array

An array.

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

by_type

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

Signature

x | by_type(type=)

Resources whose type is type (image, page, …).

Arguments#

Argument	Type	Required
`type`	string	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Content organization

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

Pages and sections#

Every Markdown (.md) or HTML (.html) file below content/ is a page. Its path is its URL:

text

content/
├── _index.md → / the home page
├── about.md → /about/
└── posts/
 ├── _index.md → /posts/ the section "posts"
 ├── first-post.md → /posts/first-post/
 └── second-post.md → /posts/second-post/

A directory directly below content/ is a section, with or without an _index.md. A deeper directory is a section only when it has an _index.md; the _index.md holds the section’s own content and front matter. Pages are of a kind: home, section, page (a regular page), and taxonomy and term for taxonomies.

Converting templates

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

A Go template and its fugo version side by side:

Go template: layouts/list.html

{{ define "main" }}
 <h1>{{ .Title }}</h1>
 {{ range where .Pages "Params.featured" true }}
 <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
 {{ with .Params.subtitle }}<p>{{ . }}</p>{{ end }}
 {{ end }}
 {{ partial "pagination.html" . }}
{{ end }}

fugo: layouts/list.html

{% extends "baseof.html" %}
{% block main %}
 <h1>{{ page.title }}</h1>
 {% for p in [x for x in page.pages if x.params.featured] %}
 <h2><a href="{{ p.rel_permalink }}">{{ p.link_title }}</a></h2>
 {% if p.params.subtitle %}<p>{{ p.params.subtitle }}</p>{% endif %}
 {% endfor %}
 {% include "_partials/pagination.html" %}
{% endblock main %}

The main changes: the context is named (page, site) instead of .; fields are snake case (.RelPermalink → rel_permalink); define/block become extends and block; range, with and where become for, if and comprehensions.

Development

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

Build#

You need Rust 1.99 or later and a C compiler:

git clone https://github.com/getfugo/fugo.git
cd fugo
cargo build --release --locked -p ssg-cli
target/release/fugo version

The workspace#

fugo is a Cargo workspace. Each crate under crates/ is a package named ssg-<crate>; the binary fugo is the package ssg-cli.

Crate	What it does
`cli`	the command line, `templates check`, the server’s front end
`build`	the build: phases, waves, deferred work
`config`	configuration loading, merging, themes
`vfs`	the union file system of mounts and themes
`pageparser`, `page`, `site`	content files, pages, the site model
`markup`	Markdown rendering (comrak with goldmark’s behaviour)
`highlight`	the Chroma port
`layouts`, `render`, `view`	template lookup, Tera rendering, the values templates see
`funcs`, `sitefuncs`	template functions (`spec.rs` declares every one)
`resources`, `images`, `jsbuild`, `minify`	asset pipelines
`npm`	installing `package.json` (Deno’s npm installer)
`publish`, `serve`	writing files, the development server
`cms`	the browser editor: its settings, content index and API Worker
`locale`, `nav`, `base`	languages, menus and pagination, shared types
`testkit`	fixtures, the contract tests, a local npm registry

docs/rust-port/HANDOFF.md is the map of the code, the parity gates and the known deviations; each crate’s README describes its API, its tests and its accepted differences.

fugo build

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

Builds the site into the publish directory (the default command)

Usage#

fugo build [OPTIONS]

Options#

-b, --base-url <URL>: The site’s base URL
-t, --theme <THEMES>: Themes to use (comma-separated)
--cache-dir <DIR>: The cache directory
--ignore-cache[=BOOL]: Ignores the cache directory
-D, --build-drafts[=BOOL]: Includes content marked as draft
-E, --build-expired[=BOOL]: Includes expired content
-F, --build-future[=BOOL]: Includes content with a publish date in the future
--clean-destination-dir[=BOOL]: Removes files from the publish directory that the static directories do not have
--no-times[=BOOL]: Does not copy the static files’ modification times (config noTimes)
--no-chmod[=BOOL]: Does not copy the static files’ permissions (config noChmod)
--minify[=BOOL]: Minifies the supported output formats
--threads <N>: The render thread count (default: RAYON_NUM_THREADS, else the CPUs). The output does not depend on it

Global options#

Every command takes these.

GitHub Pages

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

In the repository’s Settings › Pages, set the source to GitHub Actions, then add this workflow:

.github/workflows/pages.yml

name: Pages

on:
 push:
 branches: [main]
 workflow_dispatch:

permissions:
 contents: read
 pages: write
 id-token: write

concurrency:
 group: pages
 cancel-in-progress: false

jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Install fugo
 run: |
 V=1.0.0
 curl -sL "https://github.com/getfugo/fugo/releases/download/v$V/fugo_${V}_linux-amd64.tar.gz" | tar -xz fugo
 sudo install fugo /usr/local/bin/
 - id: pages
 uses: actions/configure-pages@v5
 - name: Build
 run: fugo build --minify --base-url "${{ steps.pages.outputs.base_url }}/"
 - uses: actions/upload-pages-artifact@v3
 with:
 path: public

 deploy:
 needs: build
 runs-on: ubuntu-latest
 environment:
 name: github-pages
 url: ${{ steps.deployment.outputs.page_url }}
 steps:
 - id: deployment
 uses: actions/deploy-pages@v4

configure-pages gives the site’s URL (https://user.github.io/repository, or your custom domain), so the same workflow works for user, organization and project sites.

Introduction

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

The configuration file#

The configuration is one file: config.toml, config.yaml, config.yml or config.json in the project directory (--source). If there are several, fugo stops with an error that names them: merge them into one. --config names another file instead (one file, not a list).

config.toml

baseURL = "https://example.org/"
title = "My site"
languageCode = "en-US"

[params]
 description = "Notes on Rust and the web"

Keys are case-insensitive: baseURL and baseurl are the same. Other file names are not read: rename a configuration file named after another generator to config.toml.

Introduction to templates

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

A template is HTML (or XML, JSON, text) with Tera tags:

{{ expression }}: Prints a value.
{% statement %}: Control flow, variables, blocks, includes.
{# comment #}: Removed from the output.

A dash trims whitespace on its side: {%- if x -%}.

Values#

html

<h1>{{ page.title }}</h1>
<time datetime="{{ page.date | date(format="%Y-%m-%d") }}">{{ page.date | date(style="long") }}</time>
<p>{{ page.params.subtitle or "" }}</p>

Every template sees a few top-level names: page, site, build (the version and environment), lang; shortcodes add shortcode and inner, render hooks their fields. See Template contexts for each kind of template.

License

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

fugo is licensed under the Apache License, Version 2.0. You may use, modify and distribute it, including commercially, under the licence’s terms; the LICENSE and NOTICE files ship with every release.

Third-party material in fugo — the Go implementation’s templates and test data, Chroma’s lexers and styles, Unicode CLDR data, KaTeX and others — keeps its own licence. PROVENANCE.md and THIRD_PARTY/ in the repository list each source and licence, and each release archive includes the licences of the Rust crates linked into the binary (THIRD_PARTY_NOTICES.txt).

path_base

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

Signature

x | path_base

Last element.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Quick start

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

This guide takes about ten minutes. You need the fugo binary on your PATH; see Installation if you do not have it yet.

fugo version

Create the project#

A fugo project is a directory with a configuration file, content and templates:

mkdir -p my-site/content/posts my-site/layouts
cd my-site

Create the configuration file config.toml:

config.toml

baseURL = "https://example.org/"
title = "My site"
languageCode = "en-us"

Add content#

Content is Markdown with front matter. The home page’s content is content/_index.md:

remarshal

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

Signature

x | remarshal(format=)

Re-encodes data as format (toml, yaml, json).

Arguments#

Argument	Type	Required
`format`	string	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Sass

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

to_css compiles Sass and SCSS with grass, a Rust implementation of Dart Sass. Nothing to install.

html

{% set opts = {"targetPath": "css/style.css", "outputStyle": "compressed"} %}
{% set css = get_asset(path="sass/main.scss") | to_css(options=opts) %}
<link rel="stylesheet" href="{{ css.rel_permalink }}">

Options#

targetPath: The published path. Default: the asset’s path with .css.
outputStyle: expanded (default) or compressed.
includePaths: Directories, relative to the project, searched for imports after assets/.
vars: Variables for the build:vars module: {"primary": "#d4337c"}.

Imports resolve in assets/ first (themes’ and modules’ included), then includePaths: @use "components/button" finds assets/sass/components/_button.scss next to the importer.

str

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

Signature

x | str

Converts to a string.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Taxonomy

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

page.taxonomy (on taxonomy pages), page.term (on term pages) and the entries of site.taxonomies.<plural>.<term>.

Fields#

count: The number of pages with the term (in a hierarchical taxonomy also those of the terms below it).
key: The term’s key, e.g. blue-sky; in a hierarchical taxonomy its path below the taxonomy, e.g. snacks/chips.
name: The term as first written, e.g. Blue Sky.
page: The term’s page.
pages: The pages with the term (in a hierarchical taxonomy also those of the terms below it).
plural: The plural name, e.g. tags.
singular: The singular name, e.g. tag.
term: On a term page: the term, as .Data.Term gives it.
terms: On a taxonomy page: the terms with their pages, [term entry].

trim_chars

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

Signature

x | trim_chars(chars=)

Trims any of the characters in chars from both ends.

Arguments#

Argument	Type	Required
`chars`	string	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

values

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

Signature

x | values

The values of a map.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

add_resource

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

Signature

add_resource(resource=)

Adds the page resource resource describes: path (relative to the adapter’s directory, required), content ({mediaType, value}: a string, or a resource, which keeps its own URL), name, title, params. A path added again replaces the earlier resource. Prints nothing.

Arguments#

Argument	Type	Required
`resource`	map	yes

Details#

Kind: Function, implemented by fugo.
Available in: content adapters (_content.html) and the partials they call only.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

fingerprint

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

Signature

x | fingerprint(algo=?)

The resource renamed with its hash (algo: sha256 default, sha384, sha512, md5); sets data.integrity.

Arguments#

Argument	Type	Required
`algo`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

fugo cms fields

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

Prints the editor’s fields as [cms.fields] settings: every front matter key of the content with the label and widget the build gives it (from the key and its values), the settings of the configuration over them, to copy and change

Usage#

fugo cms fields [OPTIONS]

Options#

-b, --base-url <URL>: The site’s base URL
-t, --theme <THEMES>: Themes to use (comma-separated)
--cache-dir <DIR>: The cache directory
--ignore-cache[=BOOL]: Ignores the cache directory
-D, --build-drafts[=BOOL]: Includes content marked as draft
-E, --build-expired[=BOOL]: Includes expired content
-F, --build-future[=BOOL]: Includes content with a publish date in the future

Global options#

Every command takes these.

fugo templates check

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

Checks the layouts: Tera parse and name errors, context names, lookup coverage and the conversion lints (REWRITE_PLAN.md §4.8)

Usage#

fugo templates check [OPTIONS]

Options#

-b, --base-url <URL>: The site’s base URL
-t, --theme <THEMES>: Themes to use (comma-separated)
--cache-dir <DIR>: The cache directory
--ignore-cache[=BOOL]: Ignores the cache directory
-D, --build-drafts[=BOOL]: Includes content marked as draft
-E, --build-expired[=BOOL]: Includes expired content
-F, --build-future[=BOOL]: Includes content with a publish date in the future
--coverage <COVERAGE>: How much of the lookup coverage to print Default: summary. One of summary, full, none.
--deny-warnings: Exits with 1 when there are warnings, too

Global options#

Every command takes these.

iterable

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

Signature

x is iterable

An array, map or string.

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Output format

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

output_format (the format being rendered) and the values of page.output_formats.

Fields#

is_html: Whether the format is HTML.
is_plain_text: Whether the format is plain text (not HTML-escaped).
media_type: The format’s media type.
name: The format name, e.g. html, rss.
permalink: The page’s absolute URL in this format.
rel: The rel of its <link>: canonical or alternate.
rel_permalink: The page’s URL path in this format.

pairs

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

Signature

x | pairs

[key, value] pairs of a map.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

path_base_name

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

Signature

x | path_base_name

Last element without extension.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

trim_start_chars

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

Signature

x | trim_start_chars(chars=)

Trims any of chars from the start.

Arguments#

Argument	Type	Required
`chars`	string	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

urlencode

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

Signature

x | urlencode

Percent-encodes for a URL path (keeps /).

Details#

Kind: Filter, implemented by tera-contrib.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

enable_all_languages

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

Signature

enable_all_languages()

Runs the adapter for every language, not only its own (the runs share the adapter’s store). Prints nothing.

Details#

Kind: Function, implemented by fugo.
Available in: content adapters (_content.html) and the partials they call only.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

Media type

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

The media_type of output formats and resources.

Fields#

delimiter: The suffix delimiter, ..
main_type: The main type, e.g. text.
sub_type: The subtype, e.g. html.
suffixes: The file suffixes, e.g. ["html", "htm"].
type: The full type, e.g. text/html.

minify

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

Signature

x | minify

The minified resource.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

odd

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

Signature

x is odd

An odd number.

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

path_dir

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

Signature

x | path_dir

All but the last element.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

sort_keys

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

Signature

x | sort_keys

The map with its keys sorted; Go ranges maps in key order, Tera literals keep insertion order.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

trim_end_chars

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

Signature

x | trim_end_chars(chars=)

Trims any of chars from the end.

Arguments#

Argument	Type	Required
`chars`	string	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

urlencode_strict

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

Signature

x | urlencode_strict

Percent-encodes every non-alphanumeric character.

Details#

Kind: Filter, implemented by tera-contrib.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

even

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

Signature

x is even

An even number.

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

from_pairs

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

Signature

x | from_pairs

A map from [key, value] pairs (the inverse of pairs), for keys a map literal cannot compute: [[k, v]] | from_pairs. Keys are stringified, a later pair wins, keys sorted.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

page_content

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

Signature

page_content(page=)

The rendered content of page; memoised and cycle-checked.

Arguments#

Argument	Type	Required
`page`	page	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

path_clean

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

Signature

x | path_clean

Lexically cleaned path.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

resource_content

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

Signature

x | resource_content

The text of a resource; for a bundled content page, its rendered HTML (marked safe).

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

Site configuration

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

site.config: the services and privacy configuration the embedded templates read, in snake case.

Fields#

disable: Whether the service is disabled.
disable_inline_css: Whether the embedded shortcode leaves out its inline CSS.
disqus: {shortname} under services; the privacy switches under privacy.
enable_dnt: Whether Do Not Track is sent (x, vimeo).
google_analytics: {id} under services; the privacy switches under privacy.
id: The Google Analytics measurement ID.
instagram: {disable_inline_css} under services; the privacy switches under privacy.
limit: The number of items (-1: all).
privacy: {disqus, google_analytics, instagram, twitter, vimeo, x, youtube}, each with every switch below.
privacy_enhanced: Whether the privacy-enhanced mode is used (youtube).
respect_do_not_track: Whether the browser’s Do Not Track is respected (google_analytics).
rss: {limit}: services.rss.limit, the number of items of RSS feeds (-1: all).
services: {rss, google_analytics, disqus, instagram, x, twitter}.
shortname: The Disqus shortname.
simple: Whether the simple (static) variant is used.
twitter: {disable_inline_css} under services; the privacy switches under privacy.
vimeo: The privacy switches of the vimeo shortcode.
x: {disable_inline_css} under services; the privacy switches under privacy.
youtube: The privacy switches of the youtube shortcode.

strip_prefix

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

Signature

x | strip_prefix(prefix=)

Removes prefix once.

Arguments#

Argument	Type	Required
`prefix`	string	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

urldecode

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

Signature

x | urldecode

Decodes percent-encoding.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

append

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

Signature

x | append(value=)

The array with value appended.

Arguments#

Argument	Type	Required
`value`	any	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

b64_encode

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

Signature

x | b64_encode(url_safe=?, padded=?)

Base64 (url_safe, padded).

Arguments#

Argument	Type	Required
`url_safe`	bool	no
`padded`	bool	no

Details#

Kind: Filter, implemented by tera-contrib.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

divisible_by

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

Signature

x is divisible_by(divisor=)

Divisible by divisor.

Arguments#

Argument	Type	Required
`divisor`	int	yes

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

page_summary

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

Signature

page_summary(page=)

The summary of page.

Arguments#

Argument	Type	Required
`page`	page	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

path_join

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

Signature

path_join(parts=)

Joins parts and cleans the result.

Arguments#

Argument	Type	Required
`parts`	array	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

publish

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

Signature

x | publish

Publishes the resource and returns it.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

strip_suffix

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

Signature

x | strip_suffix(suffix=)

Removes suffix once.

Arguments#

Argument	Type	Required
`suffix`	string	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

b64_decode

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

Signature

x | b64_decode(url_safe=?)

Decodes base64.

Arguments#

Argument	Type	Required
`url_safe`	bool	no

Details#

Kind: Filter, implemented by tera-contrib.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

concat

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

Signature

x | concat(with=)

The array followed by the elements of with.

Arguments#

Argument	Type	Required
`with`	array	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

page_plain

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

Signature

page_plain(page=)

The content of page as plain text.

Arguments#

Argument	Type	Required
`page`	page	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

replace

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

Signature

x | replace(from=, to=)

Replaces every from with to.

Arguments#

Argument	Type	Required
`from`	string	yes
`to`	string	yes

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

starting_with

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

Signature

x is starting_with(pat=)

Starts with pat.

Arguments#

Argument	Type	Required
`pat`	string	yes

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

to_css

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

Signature

x | to_css(options=?)

Sass/SCSS to CSS.

Arguments#

Argument	Type	Required
`options`	map	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

ending_with

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

Signature

x is ending_with(pat=)

Ends with pat.

Arguments#

Argument	Type	Required
`pat`	string	yes

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

js_build

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

Signature

x | js_build(options=?)

Bundles with rolldown.

Arguments#

Argument	Type	Required
`options`	map	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

md5

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

Signature

x | md5

Hex MD5.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

merge

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

Signature

x | merge(with=)

Deep merge of two maps; with wins; keys sorted.

Arguments#

Argument	Type	Required
`with`	map	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

page_word_count

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

Signature

page_word_count(page=)

The word count of page.

Arguments#

Argument	Type	Required
`page`	page	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

split

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

Signature

x | split(pat=)

Splits on pat.

Arguments#

Argument	Type	Required
`pat`	string	yes

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

containing

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

Signature

x is containing(pat=)

Contains pat (substring, element or key).

Arguments#

Argument	Type	Required
`pat`	any	yes

Details#

Kind: Test, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

execute_as_template

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

Signature

x | execute_as_template(target=, data=?)

Renders the asset as a Tera template with data, published at target.

Arguments#

Argument	Type	Required
`target`	string	yes
`data`	any	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

join

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

Signature

x | join(sep=?)

Joins with sep.

Arguments#

Argument	Type	Required
`sep`	string	no

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

page_fragments

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

Signature

page_fragments(page=)

{headings, identifiers} of page.

Arguments#

Argument	Type	Required
`page`	page	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

regex_replace

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

Signature

x | regex_replace(pattern=, rep=)

Replaces matches of pattern with rep ($1 groups).

Arguments#

Argument	Type	Required
`pattern`	string	yes
`rep`	string	yes

Details#

Kind: Filter, implemented by tera-contrib.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

sha1

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

Signature

x | sha1

Hex SHA-1.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

delimit

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

Signature

x | delimit(sep=, last=?)

Joins with sep, and last before the final element.

Arguments#

Argument	Type	Required
`sep`	string	yes
`last`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

matching

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

Signature

x is matching(pat=)

Matches the regex pat.

Arguments#

Argument	Type	Required
`pat`	string	yes

Details#

Kind: Test, implemented by tera-contrib.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

page_toc

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

Signature

page_toc(page=)

The table of contents of page.

Arguments#

Argument	Type	Required
`page`	page	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

post_process

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

Signature

x | post_process

Defers the resource’s fields until all pages are rendered.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

regex_find

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

Signature

x | regex_find(pattern=, limit=?)

Matches of pattern, at most limit.

Arguments#

Argument	Type	Required
`pattern`	string	yes
`limit`	int	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

sha256

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

Signature

x | sha256

Hex SHA-256.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

fnv32a

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

Signature

x | fnv32a

FNV-1a 32-bit hash as an integer.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

purge_css

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

Signature

x | purge_css(safelist=?, greedy=?, blocklist=?, content=?, variables=?, important=?)

A placeholder that each page’s published output replaces with the rules of the CSS (a resource or string) that page uses: the tags, classes and ids of its elements, the words of its <script> elements. safelist names (or /regex/) count as used; greedy keeps any selector whose text contains the string or matches the /regex/; blocklist names drop their selectors; content resources or strings (scripts that add classes) count their words as used on every page; variables=true drops custom properties nothing kept references; important=false drops !important. Printed compactly for the project’s browserslist targets. E.g. <style>{{ css | purge_css(content=[js]) }}</style>.

render_shortcodes

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

Signature

render_shortcodes(page=)

The source of page with its shortcodes expanded (placeholders renumbered).

Arguments#

Argument	Type	Required
`page`	page	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

reverse

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

Signature

x | reverse

Reversed array or string.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

substr

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

Signature

x | substr(start=, length=?)

length characters from start (negative counts from the end).

Arguments#

Argument	Type	Required
`start`	int	yes
`length`	int	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

version_at_least

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

Signature

x is version_at_least(version=)

A semver at least version; a -DEV build ranks below its release. Replaces Go-template comparisons of the site-info object’s Version.

Arguments#

Argument	Type	Required
`version`	string	yes

Details#

Kind: Test, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Differences

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

Not supported#

Go templates: Layouts, shortcodes, render hooks, content adapters (_content.gotmpl) and execute_as_template assets are Tera. A Go template is an error that names its first Go tag.
Content formats: Markdown and HTML only. AsciiDoc, reStructuredText, Pandoc and Org mode files are errors.
Module downloads: Modules are not downloaded (no go.mod). Use themes/, _vendor/ (a vendored copy of the modules) or a path; see Modules and mounts.
Commands: fugo has build, server, templates check, config and version. The Go implementation’s new, mod, deploy, gen, list, env, convert and import commands do not exist.
Node.js tools: No PostCSS, Babel or Tailwind CSS pipeline, and no build stats file (buildStats): fugo runs no programs but git, for enableGitInfo. minify adds vendor prefixes, js_build compiles TypeScript and JSX for the browser targets, purge_css purges per page, and Tailwind’s own CLI runs next to fugo (see Tailwind CSS).
Git ancestors: page.git_info is the file’s last commit only: Go’s Ancestors and Parent (the commits before it) are not read.
image_colors: Not implemented yet (.Colors in Go templates).
Goldmark extras and cjk: Accepted, not applied: no ==mark==, ++insert++, ~sub~, ^sup^, and no CJK line-break handling.
Server settings: [server] headers and redirects are not read (its proxies are fugo’s: Development server); every change rebuilds the whole site (there is no fast render); no TLS, --openBrowser or --pprof.
Some flags: The Go implementation’s logging and housekeeping flags (--gc, --logLevel, --noBuildLock, --printI18nWarnings, --printPathWarnings, --printUnusedTemplates, --templateMetrics, --templateMetricsHints) and the server’s --disableFastRender and --disableBrowserError are usage errors: remove them from your command lines.

Different by design#

Templates are Tera with the current layout names; older names are refused with the new one.
Printing an undefined value is an error, not an empty string.
Content is rendered before layouts: inside a shortcode, another page’s content comes from page_content(page=p).
Pagination is explicit: a second paginate with another list is an error.
YAML is YAML 1.2: yes and no are strings.
Imaging settings, media types and output formats are per project, not per language.
Settings that the Go implementation ignores silently (a [caches] entry that is not a table, an output format without a media type) are errors.
build.version is fugo’s version.
Images published as they are (page resources, assets, static files) lose their metadata: EXIF with the GPS position, XMP, IPTC and comments. [imaging] stripMetadata = false keeps it; see Image metadata.
An image resource’s copyright and author params are not only template data: they are written into the image, and into the images processed from it, in place of [imaging]’s. A value that is not text, has a line break (in YAML, wrap a long one with >-, not >), has a brace other than {year} or is longer than 1000 bytes stops the build. [imaging] stripMetadata = false turns this off; see Copyright notice.
Settings and the environment are not read from environment variables: --environment chooses the environment. Secrets that templates read go in the .env files.
The configuration is one file: a configuration directory (config/_default/, config/production/) is an error that names the table each file’s settings go in (an environment’s settings are a table, [environments.<name>]), several of config.toml, config.yaml, config.yml and config.json are an error, --config names one file and there is no --configDir.

Expected output differences#

When you compare a fugo build with the Go implementation’s, these are normal:

Directory structure

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

A fugo project looks like this:

text

my-site/
├── config.toml the configuration, one file (or config.yaml, config.yml, config.json)
├── content/ Markdown and HTML content
├── layouts/ Tera templates
├── assets/ files processed by asset pipelines (Sass, JavaScript, images)
├── static/ files copied to the site as they are
├── data/ data files: JSON, TOML, YAML, CSV, XML
├── i18n/ translation tables
├── themes/ themes, each a project of its own
└── public/ the built site (created by fugo)

Only config.toml and the content are required to start. A directory that does not exist is simply empty.

Documentation

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

This site is built with fugo from the docs/ directory of the repository, with its own theme (Tera templates, Sass and a small script).

Preview#

cargo build --release -p ssg-cli
target/release/fugo server -s docs

Open http://localhost:1313/. Pages reload as you save.

Where things are#

text

docs/
├── config.toml
├── content/ the pages, one Markdown file each
├── data/ generated reference data (do not edit by hand)
├── layouts/ the theme's templates, shortcodes and render hooks
└── assets/ Sass and JavaScript

The function, object and command references are generated by content adapters from docs/data/, which the tests write from the code:

File

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

page.file: the content file a page comes from.

Fields#

base_file_name: The file name without extension, e.g. index.
content_base_name: The page’s name: the bundle directory for an index file, else the file name without extension.
dir: The directory of path, with a trailing slash.
is_content_adapter: Whether the page comes from a content adapter (_content.html).
path: The path relative to the content directory, e.g. posts/my-post/index.md.
unique_id: A hash of the path, stable across builds.

Front matter

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

Front matter is metadata at the top of a content file. Write it in YAML between ---, TOML between +++, or JSON as an object:

content/posts/hello.md

+++
title = "Hello, fugo"
date = 2026-10-02T09:00:00Z
draft = false
tags = ["intro", "rust"]
[params]
 author = "Ada"
+++

Templates read the fields: page.title, page.date, page.params.author. A key fugo does not know is a parameter: author: Ada at the top level is page.params.author too. Parameter keys are lower case in templates.

fugo server

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

Builds the site into memory, serves it with live reload, and rebuilds it when files change (Go’s development server; environment development by default)

Usage#

fugo server [OPTIONS]

Options#

-b, --base-url <URL>: The site’s base URL
-t, --theme <THEMES>: Themes to use (comma-separated)
--cache-dir <DIR>: The cache directory
--ignore-cache[=BOOL]: Ignores the cache directory
-D, --build-drafts[=BOOL]: Includes content marked as draft
-E, --build-expired[=BOOL]: Includes expired content
-F, --build-future[=BOOL]: Includes content with a publish date in the future
--clean-destination-dir[=BOOL]: Removes files from the publish directory that the static directories do not have
--no-times[=BOOL]: Does not copy the static files’ modification times (config noTimes)
--no-chmod[=BOOL]: Does not copy the static files’ permissions (config noChmod)
--minify[=BOOL]: Minifies the supported output formats
--threads <N>: The render thread count (default: RAYON_NUM_THREADS, else the CPUs). The output does not depend on it
-p, --port <PORT>: The port to listen on [default: 1313, or a free port when it is taken; 0: a free port]
--bind <INTERFACE>: The interface to listen on Default: 127.0.0.1.
--append-port[=BOOL]: Puts the server’s port into the base URL (--append-port=false: the configured or --base-url port)
--disable-live-reload: Serves the pages without the LiveReload script and endpoints
--live-reload-port <PORT>: The port the browsers’ LiveReload connects to (e.g. 443 behind an HTTPS proxy)
-N, --navigate-to-changed: Sends the browsers to the page whose content file changed
--render-to-disk: Builds into the publish directory (--destination) and serves it from there, instead of memory
--no-http-cache: Sends headers that keep browsers from caching (Cache-Control: no-store, …)
--proxy <PATH=URL>: Forwards the requests of PATH and below it to the server at URL, keeping their path (/api/=http://127.0.0.1:3000, or an https:// server; repeatable). Replaces the [[server.proxies]] entry of the same path
-w, --watch[=BOOL]: Watches the project and rebuilds on changes (--watch=false: build once)
--poll <INTERVAL>: Polls for changes at this interval instead of using file notifications (700ms, 2s; a number is milliseconds). Polling reads the watched files each time

Global options#

Every command takes these.

GitLab Pages

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

.gitlab-ci.yml

pages:
 image: debian:stable-slim
 variables:
 V: "1.0.0"
 before_script:
 - apt-get update && apt-get install -y --no-install-recommends ca-certificates curl
 - curl -sL "https://github.com/getfugo/fugo/releases/download/v$V/fugo_${V}_linux-amd64.tar.gz" | tar -xz fugo
 script:
 - ./fugo build --minify --base-url "$CI_PAGES_URL/"
 artifacts:
 paths:
 - public
 cache:
 paths:
 - resources/_gen
 rules:
 - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

GitLab publishes the public artifact of the pages job.

is_menu_current

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

Signature

is_menu_current(menu=, entry=, page=?)

Whether entry of menu points at page.

Arguments#

Argument	Type	Required
`menu`	string	yes
`entry`	map	yes
`page`	page	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

JavaScript bundling

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

js_build bundles a script and everything it imports into one file, with rolldown running inside fugo. TypeScript and JSX work without configuration.

html

{% set js = get_asset(path="js/main.ts") | js_build(options={"minify": build.is_production}) %}
<script src="{{ js.rel_permalink }}" defer></script>

Imports resolve in assets/ first (so import "./menu" and import "js/menu" find assets/js/menu.ts), then in the project’s node_modules. A tsconfig.json (or jsconfig.json) in the project directory sets path aliases and JSX settings.

Site settings

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

Identity#

baseURL: The absolute URL of the published site, with a trailing slash: https://example.org/ or https://example.org/blog/. fugo server replaces it with the server’s address.
title, copyright: The site’s title and copyright notice (site.title, site.copyright).
languageCode: The site’s language tag, e.g. en-US (site.language_code).
defaultContentLanguage: The key of the default language (en); see Multilingual sites.
timeZone: The zone of dates written without one: Asia/Bangkok. Default UTC.
params: Your own settings, for templates (site.params). Keys are lower-cased.

Directories#

Setting	Default
`contentDir`	`content`
`layoutDir`	`layouts`
`assetDir`	`assets`
`dataDir`	`data`
`i18nDir`	`i18n`
`archetypeDir`	`archetypes`
`staticDir`	`static` (also `staticDir0` … `staticDir10`)
`publishDir`	`public`
`resourceDir`	`resources`
`themesDir`	`themes`
`cacheDir`	the user cache directory (`~/.cache/fugo_cache`), see Caching

ignoreFiles lists regular expressions of content files to skip.

Template lookup order

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

fugo picks each page’s template by comparing every template’s name with what the page needs: the best match wins.

Template names#

text

layouts/
├── baseof.html the base template the others extend
├── home.html the home page
├── section.html section pages
├── taxonomy.html taxonomy pages (/tags/)
├── term.html term pages (/tags/rust/)
├── list.html any list page without a more specific template
├── single.html regular pages
├── all.html any page without a more specific template
├── 404.html the 404 page
├── _partials/ partials
├── _shortcodes/ shortcodes
├── _markup/ render hooks
└── docs/ templates for pages under /docs/
 ├── single.html
 └── _shortcodes/ shortcodes only pages under /docs/ can use

A name can carry a language and an output format before its extension: single.th.html, home.rss.xml, list.json.json.

truncate

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

Signature

x | truncate(length=, end=?)

Tera’s plain-text truncate to length characters plus end.

Arguments#

Argument	Type	Required
`length`	int	yes
`end`	string	no

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

unique

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

Signature

x | unique

Removes duplicates, keeping the first.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

xxhash

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

Signature

x | xxhash

Hex xxHash64.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Git info

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

page.git_info: the last commit of the page’s file, with enableGitInfo. It is none without it, for a page without a file (a home page or a term without _index.md) and for a file Git does not know (not committed): {% if page.git_info %}…{% endif %}.

Fields#

abbreviated_hash: The abbreviated commit hash.
author_date: The author date, in the offset Git recorded: page.lastmod with the default [frontmatter].
author_email: The author’s email address, as .mailmap maps it.
author_name: The author’s name, as .mailmap maps it.
body: The commit message after the subject.
commit_date: The commit date, in the offset Git recorded.
hash: The commit hash.
subject: The commit subject.

has_menu_current

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

Signature

has_menu_current(menu=, entry=, page=?)

Whether a child of entry of menu points at page.

Arguments#

Argument	Type	Required
`menu`	string	yes
`entry`	map	yes
`page`	page	no

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

sort

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

Signature

x | sort(attribute=?)

Tera’s sort (by value, or by attribute path); not locale-aware. Use sort_by for Go’s sort.

Arguments#

Argument	Type	Required
`attribute`	string	no

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

truncate_html

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

Signature

x | truncate_html(length=, ellipsis=?)

Go’s HTML-aware truncate: closes open tags, ellipsis default …. Keeps the input’s safety.

Arguments#

Argument	Type	Required
`length`	int	yes
`ellipsis`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

by_title

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

Signature

x | by_title

Pages by title (collation of the language).

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

Date

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

A date value: page.date, page.lastmod, now(), x | to_date. Format it with the date filter: page.date | date(format="%B %-d, %Y"), or date(style="long") for the language’s own format. Compare dates by unix.

Fields#

rfc3339: The date in RFC 3339 format, e.g. 2025-10-13T15:00:00Z.
unix: Seconds since 1970-01-01 UTC.

group_by

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

Signature

x | group_by(attribute=)

Tera’s grouping by attribute path into a map.

Arguments#

Argument	Type	Required
`attribute`	string	yes

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

pad_start

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

Signature

x | pad_start(width=)

Pads on the left with spaces to width characters.

Arguments#

Argument	Type	Required
`width`	int	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

by_link_title

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

Signature

x | by_link_title

Pages by link title.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

pad_end

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

Signature

x | pad_end(width=)

Pads on the right with spaces to width characters.

Arguments#

Argument	Type	Required
`width`	int	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Sitemap settings

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

page.sitemap: the page’s sitemap front matter merged over the site’s sitemap configuration.

Fields#

change_freq: changefreq, e.g. monthly.
disable: Whether the page is left out of the sitemap.
priority: priority: an integer when it is whole, else a number; -1 when unset.

sort_by

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

Signature

x | sort_by(attribute=, reverse=?)

Sorts by attribute (a path such as params.weight; "" or value: the elements): collation of the render’s lang, dates as instants, stable.

Arguments#

Argument	Type	Required
`attribute`	string	yes
`reverse`	bool	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

by_date

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

Signature

x | by_date

Pages by date, oldest first.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

complement

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

Signature

x | complement(without=)

Elements not in without (pages compared by id).

Arguments#

Argument	Type	Required
`without`	array	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Fragments

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

page.fragments and page_fragments(page=…): the headings of the content as a tree, and every identifier.

Fields#

headings: The headings as a tree: [{id, level, title, headings}].
id: The heading’s id.
identifiers: Every id of the content, in document order.
level: The heading level, 1 to 6.
title: The heading’s text (HTML).

indent

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

Signature

x | indent(width=?, indentation=?, first=?, blank=?)

Tera’s indent.

Arguments#

Argument	Type	Required
`width`	int	no
`indentation`	string	no
`first`	bool	no
`blank`	bool	no

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

by_publish_date

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

Signature

x | by_publish_date

Pages by publish date.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

newlines_to_br

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

Signature

x | newlines_to_br

Replaces line breaks with <br>.

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

union

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

Signature

x | union(with=)

Elements of either array, first occurrence kept (pages by id).

Arguments#

Argument	Type	Required
`with`	array	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

by_lastmod

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

Signature

x | by_lastmod

Pages by last modification.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

intersect

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

Signature

x | intersect(with=)

Elements present in both (pages by id).

Arguments#

Argument	Type	Required
`with`	array	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

pluralize

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

Signature

x | pluralize(singular=?, plural=?)

Tera’s suffix pluralizer for a count (singular, plural). Go’s inflect.Pluralize is pluralize_word.

Arguments#

Argument	Type	Required
`singular`	string	no
`plural`	string	no

Details#

Kind: Filter, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

by_weight

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

Signature

x | by_weight

Pages by Go’s default page order (weight, date, link title, path).

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

pluralize_word

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

Signature

x | pluralize_word

English plural of a word.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

symdiff

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

Signature

x | symdiff(with=)

Elements present in exactly one (pages by id).

Arguments#

Argument	Type	Required
`with`	array	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

group_by_date

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

Signature

x | group_by_date(format=, attribute=?, order=?)

[{key, pages}] grouped by the date formatted with format (strftime), newest first (order="asc": oldest first); no date is Go’s zero date (0001).

Arguments#

Argument	Type	Required
`format`	string	yes
`attribute`	string	no
`order`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

range

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

Signature

range(start=?, end=, step_by=?)

Integers from start (default 0) to end (exclusive) by step_by; Go’s seq N is range(start=1, end=N+1).

Arguments#

Argument	Type	Required
`start`	int	no
`end`	int	yes
`step_by`	int	no

Details#

Kind: Function, implemented by a Tera built-in.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

singularize_word

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

Signature

x | singularize_word

English singular of a word.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

group_by_param

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

Signature

x | group_by_param(param=)

[{key, pages}] grouped by the page param param.

Arguments#

Argument	Type	Required
`param`	string	yes

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

humanize

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

Signature

x | humanize

Go’s humanize (my-first-post → My first post; numbers → ordinals).

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

querify

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

Signature

querify(params=)

A URL query string from params, keys sorted.

Arguments#

Argument	Type	Required
`params`	map	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Base templates and blocks

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

baseof.html holds the outer page — <head>, header, footer — and defines blocks that layouts fill:

layouts/baseof.html

<!doctype html>
<html lang="{{ site.language_code or lang }}">
<head>
 <meta charset="utf-8">
 <title>{% block title %}{{ page.title }} | {{ site.title }}{% endblock title %}</title>
 {% include "_partials/head.html" %}
</head>
<body>
 {% include "_partials/header.html" %}
 <main>{% block main %}{% endblock main %}</main>
 {% include "_partials/footer.html" %}
</body>
</html>

A layout extends it with its first tag and fills the blocks:

Basic usage

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

Build#

fugo

Builds the site in the current directory into public/. The build prints one line with what it did, and the time it took:

text

pages 42 | files 51 (aliases 2) | resources 12 | processed images 6 | static files 9
Total in 128 ms

Common options:

-s <dir>: The project directory, when it is not the current one.
-d <dir>: Where to write the site (default public).
--minify: Minify HTML, CSS, JavaScript, JSON, SVG and XML.
-b <url>: Override baseURL, for example for a preview deployment.
-e <environment>: The environment (default production).
--clean-destination-dir: Remove files from the publish directory that the site no longer has.

Drafts, future and expired content#

A page with draft: true, a publishDate (or date) in the future, or an expiryDate in the past is not built. Include them with:

by_count

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

Signature

x | by_count

Taxonomy terms by page count, then lower-cased name in Go’s string order.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

Fingerprinting and minification

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

Minify#

minify shrinks a resource by its media type — HTML, CSS, JavaScript, JSON, SVG and XML — with fugo’s built-in minifiers (lightningcss, oxc, minify-html):

html

{% set css = get_asset(path="css/site.css") | minify %}

The result is published as site.min.css. Other media types are an error.

Minified CSS is prepared for the browsers of the project’s browserslist configuration (a .browserslistrc or browserslist file, or the browserslist key of package.json): vendor prefixes those browsers need are added, newer syntax they lack is lowered, and prefixes none of them needs are removed, as autoprefixer does. Without a browserslist configuration, prefixes stay as written.

Front matter

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

Dates#

[frontmatter] lists, for each date, where to look, in order:

config.toml

[frontmatter]
 date = ["date", "publishDate", "pubdate", "published", "lastmod", "modified"]
 lastmod = [":git", "lastmod", "modified", "date", "publishDate", "pubdate", "published"]
 publishDate = ["publishDate", "pubdate", "published", "date"]
 expiryDate = ["expiryDate", "unpublishdate"]

config.yaml

frontmatter:
 date:
 - date
 - publishDate
 - pubdate
 - published
 - lastmod
 - modified
 expiryDate:
 - expiryDate
 - unpublishdate
 lastmod:
 - :git
 - lastmod
 - modified
 - date
 - publishDate
 - pubdate
 - published
 publishDate:
 - publishDate
 - pubdate
 - published
 - date

config.json

{
 "frontmatter": {
 "date": [
 "date",
 "publishDate",
 "pubdate",
 "published",
 "lastmod",
 "modified"
 ],
 "expiryDate": [
 "expiryDate",
 "unpublishdate"
 ],
 "lastmod": [
 ":git",
 "lastmod",
 "modified",
 "date",
 "publishDate",
 "pubdate",
 "published"
 ],
 "publishDate": [
 "publishDate",
 "pubdate",
 "published",
 "date"
 ]
 }
}

These are the defaults. A list you set replaces the default list; the first source that has a date wins.

fugo templates

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

Template tooling

Usage#

fugo templates [OPTIONS] <COMMAND>

Commands#

fugo templates check: Checks the layouts: Tera parse and name errors, context names, lookup coverage and the conversion lints (REWRITE_PLAN.md §4.8)

Global options#

Every command takes these.

-s, --source <DIR>: The project directory (default: the working directory)
--config <FILE>: The configuration file, relative to the source. Default: the project’s config.toml, config.yaml, config.yml or config.json
-e, --environment <ENV>: The build environment (default production, development for server): picks the configuration’s [environments.<environment>] table and the .env.<environment> file
--themes-dir <DIR>: The themes directory
--clock <TIME>: The build’s “now” (RFC 3339, e.g. 2026-09-27T12:00:00Z), for dates and now()
-d, --destination <DIR>: The publish directory, relative to the source
-M, --render-to-memory: Renders into memory only (a dry run: nothing is written; what server does by default)
-q, --quiet: Prints only warnings and errors

Netlify

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

Add netlify.toml to the project, then create a site from the repository in Netlify:

netlify.toml

[build]
 publish = "public"
 command = """
 V=1.0.0 && \
 curl -sL https://github.com/getfugo/fugo/releases/download/v$V/fugo_${V}_linux-amd64.tar.gz | tar -xz fugo && \
 ./fugo build --minify --base-url "$URL/"
 """

[context.deploy-preview]
 command = """
 V=1.0.0 && \
 curl -sL https://github.com/getfugo/fugo/releases/download/v$V/fugo_${V}_linux-amd64.tar.gz | tar -xz fugo && \
 ./fugo build --build-drafts --build-future --base-url "$DEPLOY_PRIME_URL/"
 """

$URL is the site’s address and $DEPLOY_PRIME_URL the preview’s. Netlify serves 404.html for missing pages.

ordinalize

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

Signature

x | ordinalize

1 → 1st.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Page resources

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

The files of a page bundle other than its content are the page’s resources, page.resources:

text

content/posts/my-trip/
├── index.md
├── cover.jpg
├── gallery/
│ ├── 01.jpg
│ └── 02.jpg
└── route.gpx

Find resources#

text

{# By name: the path in the bundle #}
{% set cover = page.resources | get_resource(name="cover.jpg") %}

{# By pattern: the first match, or every match #}
{% set first = page.resources | find_resource(pattern="gallery/*.jpg") %}
{% set photos = page.resources | find_resources(pattern="gallery/*") %}

{# By type: image, text, application, … #}
{% set images = page.resources | by_type(type="image") %}

Patterns are globs (*, **, ?, [abc], {a,b}), matched without regard to case.

Render contexts

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

What a template can read depends on what is being rendered. A layout sees page, site, build and lang; a shortcode also sees shortcode and inner; a render hook sees its node’s fields directly (destination, text, …). A name a template uses outside its context is reported by fugo templates check.

Templates and their names#

Template	Top-level names
Layout job	`page`, `site`, `build`, `lang`, `output_format`, `__nh`
Shortcode	`page`, `site`, `build`, `lang`, `shortcode`, `inner`, `inner_deindent`, `__nh`
Render hook	`page`, `page_inner`, `site`, `build`, `lang`, `__nh`; plus the hook’s fields, flattened (below)
`partial(name=…, …)`	`page`, `site`, `build`, `lang`, `output_format`, `__nh`; plus the call’s kwargs as top-level names
Component	; only its declared arguments; `@page`, `@site`, `@build`, `@lang` and `@__nh` may be declared as implicit arguments (looked up in the caller’s scope)
`defer` template	`data`, `site`, `build`, `__nh`
`execute_as_template`	`data`, `site`, `build`, `__nh`
Alias	`permalink`, `page`, `site`, `build`
Sitemap, robots, 404	`page`, `site`, `build`, `lang`, `__nh`
Sitemapindex	`page`, `site`, `build`, `lang`, `__nh`, `sites`
Content adapter (`content/**/_content.html`)	`site`, `build`, `lang`, `__nh`; `site` has no page lists (`home`, `pages`, `regular_pages`, `all_pages`, `sections`, `main_sections`, `taxonomies`, `menus`): the model is not built yet

What the names hold#

Name	Meaning
`page`	the full page value of the Full generation
`site`	`SiteView` of the current language
`build`	`BuildView`: version, environment, generator
`lang`	the language code of the page
`output_format`	`OutputFormatView` being rendered
`__nh`	the render scope (`RenderScope`); read by site-bound functions
`shortcode`	`ShortcodeView`: name, args, params, is_named_params, ordinal, parent, position
`inner`	the inner content (safe)
`inner_deindent`	the inner content without common indentation
`page_inner`	the page whose source holds the hooked node (differs inside `render_shortcodes`)
`data`	the `data=` value of the call
`permalink`	the target URL
`sites`	`[{language, sitemap_abs_url, last_mod}]`

__nh is fugo’s render scope. You never print it; site-bound functions such as get_page, paginate or partial read it. A component does not see the caller’s names, so a component that calls a site-bound function declares @__nh, or is passed page=.

alphabetical

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

Signature

x | alphabetical

Taxonomy terms by name (collation).

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

urlize

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

Signature

x | urlize

The URL-safe path form of a string, as Go’s urlize makes it.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

anchorize

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

Signature

x | anchorize(style=?)

An anchor id as Go generates it; style github (default), github-ascii or blackfriday.

Arguments#

Argument	Type	Required
`style`	string	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

plainify

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

Signature

x | plainify

Strips HTML tags.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

emojify

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

Signature

x | emojify

Replaces :shortcode: emoji.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.

Cloudflare Workers

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

A Worker with static assets serves the files of public/; requests for static files are free and unlimited. Cloudflare suggests Workers rather than Pages for new sites, and the browser editor needs them: its API runs in the same Worker.

Describe the Worker next to config.toml:

wrangler.jsonc

{
 "name": "site",
 "compatibility_date": "2026-10-01",
 "assets": {
 "directory": "public",
 "not_found_handling": "404-page"
 }
}

and deploy after each build:

fugo build --minify
npx wrangler deploy

Add a custom domain in the Worker’s settings (or "routes" in wrangler.jsonc) and set baseURL to it.

markdownify

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

Signature

x | markdownify

Renders Markdown with the current page’s hooks; a single paragraph is unwrapped.

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

render_string

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

Signature

x | render_string(display=?, page=?)

Renders Markdown with page’s hooks; display="block" keeps the paragraph.

Arguments#

Argument	Type	Required
`display`	string	no
`page`	page	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

highlight

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

Signature

x | highlight(lang=, options=?)

Syntax highlighting of the input as lang (Chroma classes, or inline styles per noClasses; needs the site’s highlight configuration).

Arguments#

Argument	Type	Required
`lang`	string	yes
`options`	any	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: safe HTML, not escaped.
Site-bound: reads the site or the page being rendered; in a component, pass page= or declare @__nh.

to_math

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

Signature

x | to_math(options=?, optional=?)

LaTeX to MathML and/or HTML with KaTeX 0.16.22 and mhchem, as Go renders it (SHOULD; feature math). options: KaTeX’s output (mathml default, html, htmlAndMathml), displayMode, leqno, fleqn, errorColor, macros, minRuleThickness, throwOnError (default true), strict (error default, ignore, warn: warnings). An error (a formula KaTeX rejects, invalid options) fails the render; with optional=true it is a warning (id to_math) and the result none.

diagrams_goat

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

Signature

diagrams_goat(text=)

{inner (safe SVG), width, height, wrapped} for the ASCII diagram text (SHOULD; feature goat).

Arguments#

Argument	Type	Required
`text`	string	yes

Details#

Kind: Function, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Cloudflare Pages

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

Create a Pages project connected to the repository, with these build settings:

Framework preset: None
Build command: V=1.0.0 && curl -sL https://github.com/getfugo/fugo/releases/download/v$V/fugo_${V}_linux-amd64.tar.gz | tar -xz fugo && ./fugo build --minify --base-url "$CF_PAGES_URL/"
Build output directory: public

$CF_PAGES_URL is the deployment’s URL; for the production site with a custom domain, set baseURL in config.toml and drop --base-url.

For new sites, and for the browser editor, use Cloudflare Workers instead: Cloudflare suggests Workers for new projects, and the editor’s API runs in the site’s Worker.

Embedded templates

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

fugo ships a set of templates so that a site works without writing them: the RSS feed, the sitemap, robots.txt, alias redirects, the default render hooks, the built-in shortcodes Go-template sites expect and a few partials. They are loaded under the prefix _embedded/. A template of your project or theme with the same name wins: to change the sitemap, add layouts/sitemap.xml.

_markup/render-codeblock-goat.html
_markup/render-image.html
_markup/render-link.html
_markup/render-table.html
_partials/_funcs/get-page-images.html
_partials/google_analytics.html
_partials/opengraph.html
_partials/pagination.html
_partials/schema.html
_partials/twitter_cards.html
_shortcodes/details.html
_shortcodes/figure.html
_shortcodes/highlight.html
_shortcodes/instagram.html
_shortcodes/param.html
_shortcodes/qr.html
_shortcodes/ref.html
_shortcodes/relref.html
_shortcodes/vimeo.html
_shortcodes/x.html
_shortcodes/youtube.html
alias.html
robots.txt
rss.xml
sitemap.xml
sitemapindex.xml

Call an embedded partial by its name: {{ partial(name="pagination.html") }}, {% include "_partials/opengraph.html" %}. The shortcodes are used in content like your own: {{< youtube id="0RKpf3rK57I" >}}. See Shortcodes for their arguments.

format_number

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

Signature

x | format_number(precision=?)

The number with precision decimals in the format of the render’s lang.

Arguments#

Argument	Type	Required
`precision`	int	no

Details#

Kind: Filter, implemented by fugo.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

fugo config

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

Prints the resolved configuration

Usage#

fugo config [OPTIONS]

Options#

-b, --base-url <URL>: The site’s base URL
-t, --theme <THEMES>: Themes to use (comma-separated)
--cache-dir <DIR>: The cache directory
--ignore-cache[=BOOL]: Ignores the cache directory
-D, --build-drafts[=BOOL]: Includes content marked as draft
-E, --build-expired[=BOOL]: Includes expired content
-F, --build-future[=BOOL]: Includes content with a publish date in the future
--format <FORMAT>: Default: json. One of json, toml.

Global options#

Every command takes these.

Image processing

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

Images from a page bundle, from assets/ (get_asset(path="images/logo.png")) or from the web (get_remote) can be processed in templates. The results are cached between builds and published under the image’s directory with a name like cover_hu_3f2a9c….jpg.

Resize, fit, fill and crop#

html

{% set img = page.resources | get_resource(name="cover.jpg") %}
{% set small = img | resize(width=600) %}
<img src="{{ small.rel_permalink }}" width="{{ small.width }}" height="{{ small.height }}" alt="">

resize: Scales to width and/or height; give one to keep the aspect ratio.
fit: Scales down to fit inside width×height, keeping the aspect ratio.
fill: Scales and crops to exactly width×height, keeping the part at anchor.
crop: Crops to width×height at anchor, without scaling.
process: Runs a spec with any action: img | process(spec="fill 300x300 webp q80").

Every method takes width, height, format, quality, filter, anchor as keyword arguments, or one spec string, as in Go templates:

Imaging

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

config.toml

[imaging]
 quality = 75
 resampleFilter = "box"
 anchor = "smart"
 bgColor = "#ffffff"
 hint = "photo"
 stripMetadata = true
 copyright = ""
 author = ""
 titleFromFileName = false
 [imaging.exif]
 includeFields = ""
 excludeFields = ""
 disableDate = false
 disableLatLong = false

config.yaml

imaging:
 anchor: smart
 author: ""
 bgColor: '#ffffff'
 copyright: ""
 exif:
 disableDate: false
 disableLatLong: false
 excludeFields: ""
 includeFields: ""
 hint: photo
 quality: 75
 resampleFilter: box
 stripMetadata: true
 titleFromFileName: false

config.json

{
 "imaging": {
 "anchor": "smart",
 "author": "",
 "bgColor": "#ffffff",
 "copyright": "",
 "exif": {
 "disableDate": false,
 "disableLatLong": false,
 "excludeFields": "",
 "includeFields": ""
 },
 "hint": "photo",
 "quality": 75,
 "resampleFilter": "box",
 "stripMetadata": true,
 "titleFromFileName": false
 }
}

quality: JPEG and WebP quality, 1–100 (75).
resampleFilter: The filter for resizing: box (default), lanczos, catmullRom, mitchellNetravali, linear, nearestNeighbor and others; see Image processing.
anchor: Where fill and crop keep the image: smart (default), center, topLeft, …
bgColor: The background for images converted to a format without transparency (JPEG).
hint: The WebP encoding hint: photo (default), picture, drawing, icon, text.
stripMetadata: Publish JPEG, PNG and WebP images without their metadata (true by default; fugo’s own setting). See Image metadata.
copyright, author, titleFromFileName: A copyright notice ({year} in it is the build’s year), an author and the file name as the title, written into every JPEG, PNG and WebP image fugo publishes, unless a page resource gives its own copyright and author (fugo’s own settings; they need stripMetadata). See Copyright notice.
exif.includeFields, exif.excludeFields: Regular expressions of the EXIF tags to keep in img | exif. By default fugo leaves out large and technical tags.
exif.disableDate, exif.disableLatLong: Do not read the date or the location.

Processed images are cached in resources/_gen/images; keep that directory between builds (or commit it) to avoid processing images again. See Caching.

Partials and components

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

Partials live in layouts/_partials/. There are three ways to use one.

Include#

include renders a partial with the caller’s names — page, site, and any variable set before it:

html

{% include "_partials/header.html" %}

partial()#

partial renders a partial with the names you pass, and can return a value instead of text:

html

{{ partial(name="card.html", p=p, size="small") }}

layouts/_partials/cover.html

{#- The page's cover image: its resource named cover.*, or none. -#}
{{- return_value(value=p.resources | find_resource(pattern="cover.*")) -}}

html

{% set cover = partial(name="cover.html", p=page) %}
{% if cover %}
 {% set thumb = cover | fill(width=600, height=400, format="webp") %}
 <img src="{{ thumb.rel_permalink }}" width="{{ thumb.width }}" height="{{ thumb.height }}" alt="">
{% endif %}

Every call still sees page, site, build and lang. partial_cached(name=…, key=…) renders once per key and reuses the result: use it for the footer or a menu that is the same on every page (key=lang).

Unused CSS

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

purge_css removes the rules a page does not use. Unlike PurgeCSS, it works per page: each published page gets the rules for its own elements, inlined.

layouts/_partials/head.html

{% set css = get_asset(path="scss/main.scss") | to_css %}
{% set js = get_asset(path="js/main.js") | js_build %}
<style>{{ css | purge_css(content=[js]) }}</style>

purge_css prints a placeholder; when a page is written, fugo replaces it with the rules whose selectors match the page’s tags, classes and ids, and the words of its <script> elements. The CSS is printed compactly for the project’s browserslist targets.

filesize_format

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

Signature

x | filesize_format(binary=?)

Human file size (binary units by default).

Arguments#

Argument	Type	Required
`binary`	bool	no

Details#

Kind: Filter, implemented by tera-contrib.
Available in: every kind of template: layouts, partials, shortcodes and render hooks.
Output: escaped like any value, unless marked safe.

Font subsetting

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

[fonts] cuts the published fonts down to the characters the site uses, once every page is written. An icon font such as Font Awesome, whose files hold some 2,000 icons, keeps the few dozen the site shows, and goes from about 150 KB to 3 KB:

config.toml

[[fonts.subset]]
 paths = ["assets/webfonts/*"]
 from = "content"

Each [[fonts.subset]] entry covers some fonts and says which characters they keep:

Bundling and generated files

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

Concatenate#

html

{% set parts = [get_asset(path="js/a.js"), get_asset(path="js/b.js")] %}
{% set bundle = concat_assets(target="js/bundle.js", items=parts) | minify | fingerprint %}

Items must have the same media type. For JavaScript with imports, use js_build instead.

From a string#

html

{% set json = {"name": site.title, "start_url": "/"} | jsonify %}
{% set manifest = asset_from_string(target="manifest.webmanifest", content=json) %}
<link rel="manifest" href="{{ manifest.rel_permalink }}">

Assets as templates#

execute_as_template renders an asset as a Tera template, with data:

Caching

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

fugo keeps the results of slow work on disk so that the next build is fast:

Cache	Holds	Default directory
`images`	processed images	`:resourceDir/_gen`
`assets`	transformed assets (Sass, bundles, …)	`:resourceDir/_gen`
`getresource`	files fetched with `get_remote`	`:cacheDir/:project`
`misc`	other results	`:cacheDir/:project`

:resourceDir is the project’s resources/; :cacheDir the cache directory (cacheDir, or --cache-dir, else $XDG_CACHE_HOME/fugo_cache or ~/.cache/fugo_cache); :project the project directory’s name.

config.toml

[caches]
 [caches.getresource]
 dir = ":cacheDir/:project"
 maxAge = "1h"
 [caches.images]
 dir = ":resourceDir/_gen"
 maxAge = -1

maxAge is how long an entry stays valid: -1 (the default) forever, 0 never, or a duration ("10m", "24h") or a number of seconds. fugo build --ignore-cache ignores every cache for one build.

fugo cms

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

Content editor ([cms]) tooling

Usage#

fugo cms [OPTIONS] <COMMAND>

Commands#

fugo cms fields: Prints the editor’s fields as [cms.fields] settings: every front matter key of the content with the label and widget the build gives it (from the key and its values), the settings of the configuration over them, to copy and change

Global options#

Every command takes these.

Sections

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

A section is a group of pages under one directory: every directory directly below content/, and a deeper directory that has an _index.md.

text

content/
├── docs/ section /docs/
│ ├── _index.md
│ ├── install.md
│ └── guides/ section /docs/guides/ (it has an _index.md)
│ ├── _index.md
│ └── deploy.md
└── blog/ section /blog/ (top level: no _index.md needed)
 └── hello.md

A section’s page uses section.html (or list.html) and lists its pages. _index.md gives it a title, content and front matter; without one the title is the directory name, title-cased.

Shortcode templates

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

A file in layouts/_shortcodes/ is a shortcode of the same name: _shortcodes/note.html is {{< note >}}. Shortcodes in layouts/<section>/_shortcodes/ are available only to the pages of that section.

Arguments#

layouts/_shortcodes/button.html

{%- set href = shortcode | arg(name="href") -%}
{%- set label = shortcode | arg(name="label", default="Read more") -%}
{%- if not href -%}
 {{- log_error(message="button: missing href at " ~ shortcode.position) -}}
{%- endif -%}
<a class="button" href="{{ href | rel_url }}">{{ label }}</a>

{{< button href="/docs/" label="Get started" >}}

shortcode | arg(name=…) reads a named argument, arg(index=0) a positional one; default is the value when it is missing. shortcode.params holds the named arguments, shortcode.args the positional ones, shortcode.is_named_params which kind the call used.

fugo version

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

Prints the version

Usage#

fugo version [OPTIONS]

Global options#

Every command takes these.

-s, --source <DIR>: The project directory (default: the working directory)
--config <FILE>: The configuration file, relative to the source. Default: the project’s config.toml, config.yaml, config.yml or config.json
-e, --environment <ENV>: The build environment (default production, development for server): picks the configuration’s [environments.<environment>] table and the .env.<environment> file
--themes-dir <DIR>: The themes directory
--clock <TIME>: The build’s “now” (RFC 3339, e.g. 2026-09-27T12:00:00Z), for dates and now()
-d, --destination <DIR>: The publish directory, relative to the source
-M, --render-to-memory: Renders into memory only (a dry run: nothing is written; what server does by default)
-q, --quiet: Prints only warnings and errors

Modules and mounts

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

fugo builds from a union of directories: the project’s content, layouts, assets, data, i18n, archetypes and static, then each theme’s. Mounts decide which directory provides which part.

Mounts#

config.toml

[[module.mounts]]
 source = "content"
 target = "content"
[[module.mounts]]
 source = "node_modules/bootstrap/scss"
 target = "assets/scss/bootstrap"
[[module.mounts]]
 source = "../brand"
 target = "assets/brand"
[[module.mounts]]
 source = "docs-th"
 target = "content"
 lang = "th"

config.yaml

module:
 mounts:
 - source: content
 target: content
 - source: node_modules/bootstrap/scss
 target: assets/scss/bootstrap
 - source: ../brand
 target: assets/brand
 - lang: th
 source: docs-th
 target: content

config.json

{
 "module": {
 "mounts": [
 {
 "source": "content",
 "target": "content"
 },
 {
 "source": "node_modules/bootstrap/scss",
 "target": "assets/scss/bootstrap"
 },
 {
 "source": "../brand",
 "target": "assets/brand"
 },
 {
 "lang": "th",
 "source": "docs-th",
 "target": "content"
 }
 ]
 }
}

source: A directory or file, relative to the project (or absolute).
target: Where it appears: content, layouts, assets, data, i18n, archetypes or static, and a path below it.
lang: The language of mounted content.
includeFiles, excludeFiles: Globs of the files to take or leave.
disableWatch: Do not watch the source in fugo server.

Once you configure one mount for a component, the default for that component is gone: mount content and static again if you still need them (as above).

npm packages

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

Put the npm packages a site needs in package.json, next to the configuration file:

package.json

{
 "private": true,
 "dependencies": { "alpinejs": "^3.14.9", "bootstrap": "^5.3.3" }
}

fugo build and fugo server install them into node_modules before they read the project. You do not need Node.js or npm:

js_build bundles what you import from them;
mounts can use their files (node_modules/bootstrap/scss).

fugo runs none of their programs.

text

Installed the npm packages of package.json in 2102 ms

The next build installs nothing until package.json or the lock file changes. fugo server installs again when you save package.json, and looks at package-lock.json again when it changes (see below).

Render hooks

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

A render hook is a template that renders one kind of Markdown element. Put it in layouts/_markup/, or layouts/<section>/_markup/ for the pages of one section.

Hook	Renders	Fields
`render-link.html`	`[text](url "title")`	`destination`, `title`, `text`, `plain_text`
`render-image.html`	`![alt](src "title")`	`destination`, `title`, `text`, `plain_text`, `is_block`
`render-heading.html`	`## Heading`	`level`, `anchor`, `text`, `plain_text`
`render-codeblock.html`	fenced code blocks	`type` (the language), `inner`, `options`
`render-codeblock-<lang>.html`	code blocks of one language	as above
`render-blockquote.html`	blockquotes and alerts	`type` (`regular`, `alert`), `alert_type`, `alert_title`, `alert_sign`, `text`
`render-table.html`	tables	`thead`, `tbody`
`render-passthrough.html`	passthrough elements (math)	`type` (`inline`, `block`), `inner`

Every hook also gets page, page_inner (the page whose Markdown holds the element; it differs when a template renders another page’s content) and attributes (Markdown attributes such as {.class #id}). All but the heading hook get ordinal, the element’s number on the page; links, images, code blocks and passthrough elements get position for messages. See the generated table in Template contexts.

Taxonomies

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

A taxonomy groups pages by terms: the taxonomy tags with the terms rust and web. fugo creates a page for each taxonomy (/tags/) and each term (/tags/rust/).

Configure taxonomies#

The default taxonomies are tags and categories. Define your own, singular name first:

config.toml

[taxonomies]
 tag = "tags"
 category = "categories"
 series = "series"

Defining [taxonomies] replaces the defaults; an empty table, or disableKinds = ["taxonomy", "term"], turns taxonomies off.

Menus

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

A menu is a named list of entries: main, footer, docs. Entries point to pages or URLs and may have children.

In the configuration#

config.toml

[menus]
 [[menus.main]]
 name = "Docs"
 pageRef = "/docs/"
 weight = 10
 [[menus.main]]
 name = "Install"
 pageRef = "/docs/install/"
 parent = "Docs"
 weight = 10
 [[menus.main]]
 name = "GitHub"
 url = "https://github.com/getfugo/fugo"
 weight = 30

config.yaml

menus:
 main:
 - name: Docs
 pageRef: /docs/
 weight: 10
 - name: Install
 pageRef: /docs/install/
 parent: Docs
 weight: 10
 - name: GitHub
 url: https://github.com/getfugo/fugo
 weight: 30

config.json

{
 "menus": {
 "main": [
 {
 "name": "Docs",
 "pageRef": "/docs/",
 "weight": 10
 },
 {
 "name": "Install",
 "pageRef": "/docs/install/",
 "parent": "Docs",
 "weight": 10
 },
 {
 "name": "GitHub",
 "url": "https://github.com/getfugo/fugo",
 "weight": 30
 }
 ]
 }
}

name: The text of the entry.
pageRef: A page’s path; the entry links to it and knows it.
url: A URL, when the entry is not a page.
weight: The order: lower first.
parent: The identifier (or name) of the parent entry.
identifier: A unique key, needed when two entries share a name.
pre, post: HTML before and after the name, e.g. an icon.
title: The title attribute of the link.
params: Parameters of the entry.

In front matter#

content/about.md

+++
title = "About"
[menus.main]
 weight = 20
+++

menus: main adds the page with its link title; a map sets name, weight, parent, identifier; a list of names adds it to several menus.

Output formats

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

A page is rendered once per output format. By default the home page, sections, taxonomies and terms are rendered as html and rss, regular pages as html.

config.toml

[outputs]
 home = ["html", "rss", "json"]
 section = ["html"]
 page = ["html"]

A page can set its own with outputs in front matter.

Tailwind CSS

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

fugo does not run Tailwind CSS. Run Tailwind’s CLI next to fugo (the standalone binary, or npx @tailwindcss/cli), and publish the stylesheet it writes like any other asset:

assets/css/main.css

@import "tailwindcss";

tailwindcss -i assets/css/main.css -o assets/css/site.css --watch &
fugo server

Tailwind finds the classes in your layouts and content itself. It skips the files your .gitignore lists, such as public/; name other places with @source.

Themes

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

A theme is a project whose layouts, assets, content, data and i18n files are used under yours.

config.toml

theme = "my-theme"

fugo looks for themes/my-theme (or themesDir). theme may be a list: the first wins where themes provide the same file. A theme can import other themes with [[module.imports]].

Pagination

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

On a list page, paginator() splits the page’s list into pagers of pagerSize pages, written at /page/2/, /page/3/ and so on:

layouts/list.html

{% extends "baseof.html" %}
{% block main %}
 {% set pager = paginator() %}
 {% for p in pager.pages %}
 <h2><a href="{{ p.rel_permalink }}">{{ p.title }}</a></h2>
 {{ p.summary }}
 {% endfor %}
 {% include "_partials/pagination.html" %}
{% endblock main %}

To paginate another list, call paginate instead:

Privacy and services

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

The embedded shortcodes and partials read [services] and [privacy].

Services#

config.toml

[services]
 [services.googleAnalytics]
 id = "G-XXXXXXXXXX"
 [services.rss]
 limit = 20
 [services.x]
 disableInlineCSS = false
 [services.instagram]
 disableInlineCSS = false

config.json

{
 "services": {
 "googleAnalytics": {
 "id": "G-XXXXXXXXXX"
 },
 "instagram": {
 "disableInlineCSS": false
 },
 "rss": {
 "limit": 20
 },
 "x": {
 "disableInlineCSS": false
 }
 }
}

{% include "_partials/google_analytics.html" %} adds Google Analytics 4 with the id. services.rss.limit caps RSS feeds.

Summaries

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

page.summary is a page’s summary, and page.truncated tells whether the content goes on beyond it. There are three ways to get one, in this order of precedence:

Front matter: summary: A short description. — Markdown, rendered.
The divider:  in the content: everything before it is the summary.
Automatic: Whole paragraphs, until summaryLength words (70 by default) are reached.

html

{% for p in page.pages %}
 <article>
 <h2><a href="{{ p.rel_permalink }}">{{ p.title }}</a></h2>
 {{ p.summary }}
 {% if p.truncated %}<a href="{{ p.rel_permalink }}">Read more</a>{% endif %}
 </article>
{% endfor %}

In a shortcode or render hook, read another page’s summary with page_summary(page=p).

Post-processing

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

Some steps need the whole site, such as listing what every page used. Two tools delay work until all pages are rendered.

post_process#

post_process makes a resource’s URL and content placeholders that fugo fills in after the last page:

html

{% set css = get_asset(path="css/main.css") | minify | fingerprint | post_process %}
<link rel="stylesheet" href="{{ css.rel_permalink }}" integrity="{{ css.data.integrity }}">

To ship each page only the CSS rules it uses, see purge_css.

Security

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

Templates and themes are code. [security] limits what they can reach.

config.toml

[security]
 enableInlineShortcodes = false
 [security.exec]
 allow = ["^(dart-)?sass(-embedded)?$", "^go$", "^git$", "^npx$"]
 [security.funcs]
 getenv = ["^FUGO_", "^CI$"]
 [security.http]
 methods = ["(?i)GET|POST"]
 urls = [".*"]

config.yaml

security:
 enableInlineShortcodes: false
 exec:
 allow:
 - ^(dart-)?sass(-embedded)?$
 - ^go$
 - ^git$
 - ^npx$
 funcs:
 getenv:
 - ^FUGO_
 - ^CI$
 http:
 methods:
 - (?i)GET|POST
 urls:
 - .*

config.json

{
 "security": {
 "enableInlineShortcodes": false,
 "exec": {
 "allow": [
 "^(dart-)?sass(-embedded)?$",
 "^go$",
 "^git$",
 "^npx$"
 ]
 },
 "funcs": {
 "getenv": [
 "^FUGO_",
 "^CI$"
 ]
 },
 "http": {
 "methods": [
 "(?i)GET|POST"
 ],
 "urls": [
 ".*"
 ]
 }
 }
}

exec.allow, exec.osEnv: The programs fugo may run, and the environment variables they get (by default PATH, HOME, the proxy settings and a few more). fugo runs only git, for enableGitInfo.
funcs.getenv: Environment variables the get_env function may read. The names a project’s .env file defines are always readable.
http.urls, http.methods, http.mediaTypes: What get_remote may fetch.
enableInlineShortcodes: Allow shortcodes defined inside content files.

A blocked action is an error that names the setting to change.

Sitemaps and robots.txt

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

Sitemap#

fugo writes /sitemap.xml with every page that has a URL, from its embedded template. A multilingual site gets one sitemap per language and a /sitemap.xml index of them.

config.toml

[sitemap]
 changeFreq = "weekly"
 priority = 0.5
 filename = "sitemap.xml"
 disable = false

A page can change its entry, or leave it out:

URLs

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

Defaults#

A page’s URL is its path in content/, lower-cased, with spaces as -: content/Posts/My Post.md is /posts/my-post/. A leaf bundle’s directory is the page: content/posts/my-post/index.md is also /posts/my-post/.

Front matter#

slug: Replaces the last segment: slug: hello gives /posts/hello/.
url: Replaces the whole path: url: /about-us/.

Permalinks#

Patterns per section and kind:

config.toml

[permalinks]
 [permalinks.page]
 posts = "/:year/:month/:slug/"
 [permalinks.section]
 posts = "/articles/"

Token	Value
`:year`, `:month`, `:monthname`, `:day`, `:weekday`, `:weekdayname`, `:yearday`	parts of the date
`:section`, `:sections`	the top-level section, every section
`:title`, `:slug`	the title, the slug (else the title) — made URL-safe
`:slugorfilename`, `:filename`, `:contentbasename`	the slug or file name, the file name, the page’s name
`:slugorcontentbasename`	the slug, else the page’s name
`:term[categories]`	the first term the page names in that taxonomy, by its last segment (`rust`); empty when it names none
`:2006-01-02` and other Go date layouts	the date formatted with that layout

Aliases#

Redirect old URLs to a page:

CMS editor

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

[cms] adds the browser editor described in Editing in the browser to a build. Put it in the table of the environment that deploys it, [environments.production.cms] (see environments), so that other builds have no editor; the examples below write it at the root, as [cms]. Keys are case-insensitive, like every setting.

config.toml

[cms]
path = "admin"
workflow = "review"
media = "static/images/uploads"
maxUpload = 10

[cms.git]
host = "github"
repo = "you/site"
branch = "main"

[cms.login]
provider = ["github", "google"]

[cms.roles.writer]
edit = ["content/blog/**"]

[cms.roles.owner]
edit = ["**"]
publish = true

[cms.fields.summary]
label = "Short summary"
help = "Shown in lists and in search results."

Settings#

path: The editor’s directory under the site, admin by default: the editor is /admin/, its API /admin/api/. The editor replaces a page of the site at that path (with a warning).
title: The editor’s title. Default: the site’s title.
workflow: review (default): saves go to a draft per page (a branch, with a pull request labelled fugo-cms), and roles with publish publish drafts. direct: every save is a commit to the branch.
media: A directory for uploads to pages that are not bundles, inside a static directory, assets/ or the content directory (static/images/uploads). Front matter names its files by their URL path for a static directory (/images/uploads/photo.jpg), else by their path below the directory. Default: none (uploads go into page bundles only).
maxUpload: The largest file a save may write, in MiB, 1 to 25. Default: 10.
html: Let roles write .html and .htm content files. They are raw HTML pages, whose scripts run on the editor’s own address (see security notes). Default: false.

Git#

[cms.git] is the repository the editor commits to.

Build and minify

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

Build#

[build] is accepted for compatibility. cacheBusters, useResourceCacheWhen and noJSConfigInAssets are checked and have no effect: fugo always runs a pipeline’s steps, and writes no jsconfig.json.

buildStats (and the older writeStats) is no longer supported, and a warning says so: fugo writes no file of the classes and tags pages use. purge_css reads each page itself, and Tailwind CSS finds the classes in your layouts.

Minify#

fugo build --minify, or minifyOutput, minifies every HTML, CSS, JavaScript, JSON, SVG and XML file fugo writes. disableHTML, disableCSS, disableJS, disableJSON, disableSVG and disableXML turn off one type:

Links and cross references

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

Markdown links#

Link to another page by its content path:

See the [installation guide](/docs/install/) or the [next post](../second-post/).

By default a Markdown link is written as it is. To resolve link destinations, use the embedded link render hook:

config.toml

[markup.goldmark.renderHooks.link]
 useEmbedded = "fallback"

It resolves a relative destination to a page, a page resource or an asset and writes its URL, so the link stays right when a page’s URL changes (slug, url, permalinks). A query and a fragment (/docs/install/#linux) are kept; destinations that do not resolve are written as they are.

RSS feeds

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

The home page, sections, taxonomies and terms have the rss output format by default, so /index.xml, /posts/index.xml and /tags/rust/index.xml are RSS 2.0 feeds: the home page’s of every regular page, a section’s of its regular pages, a term’s of its pages.

config.toml

[services.rss]
 limit = 20

limit caps the number of items (-1, the default, means all). Feeds carry each page’s summary; the site’s params.author (a name or {name, email}) fills the author fields.

Development server

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

fugo server reads one part of [server]: its proxies. The Go implementation’s [[server.headers]] and [[server.redirects]] are not read.

Proxies#

A site whose pages call an API on their own origin (fetch("/api/items")) is published next to that API. While you develop, the API runs as a program of its own, on another port. A proxy sends the requests of a path to it, so that the pages fugo server serves reach the API as they will once published: on their own origin, with their cookies, without CORS.

Markdown

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

fugo renders Markdown the way goldmark, the Go implementation’s default renderer, does: CommonMark, plus these extensions, all on by default.

Tables: GitHub’s pipe tables, with alignment.
Strikethrough: ~~deleted~~.
Task lists: - [x] done and - [ ] to do.
Footnotes: Text[^1] and [^1]: The note.
Definition lists: A term on its own line, then : definition (like this list).
Linkify: Bare URLs become links.
Typographer: "quotes", -- and ... become typographic quotes, dashes and an ellipsis.

Attributes#

Attributes after a heading, and (with parser.attribute.block) on the line after a block:

Custom 404 page

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

layouts/404.html renders /404.html, with the home page as page:

layouts/404.html

{% extends "baseof.html" %}
{% block main %}
 <h1>Page not found</h1>
 <p><a href="{{ site.home.rel_permalink }}">Go to the home page</a></p>
{% endblock main %}

GitHub Pages, Netlify, Cloudflare Pages and most hosts serve /404.html for missing URLs without configuration. fugo server serves it too. A multilingual site gets one per language (/th/404.html).

Shortcodes

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

A shortcode calls a template from content. fugo ships some; your own live in layouts/_shortcodes/.

{{< youtube id="0RKpf3rK57I" >}}

{{< figure src="beach.jpg" alt="A beach" caption="Our first day" >}}

Calling shortcodes#

{{< name >}}: The shortcode’s output is inserted as HTML.
{{% name %}}: The output is Markdown, rendered with the page.

Arguments are positional ({{< name "a" "b" >}}) or named ({{< name x="a" >}}), not both. A shortcode can enclose content, which it receives as inner:

Syntax highlighting

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

fugo highlights code at build time with a port of Chroma v2.19, the Go highlighter: the same lexers, styles and HTML. No JavaScript runs in the browser.

Code fences#

Name the language after the opening fence, and add options in braces:

```rust {linenos=inline, hl_lines=[2, "4-5"]}
fn main() {
 let name = "fugo";
 println!("hello");
 println!("{name}");
 println!("bye");
}
```

rust

1fn main() {
2 let name = "fugo";
3 println!("hello");
4 println!("{name}");
5 println!("bye");
6}

linenos: true or table (numbers in a table column), inline, false.
linenostart: The first line number.
hl_lines: Lines to highlight: [2, "4-5"] or "2 4-5".
anchorlinenos, lineanchors: Make the line numbers links, with ids prefixed by lineanchors.
style: A Chroma style for this block (with inline styles).
noClasses: false for class names, true for inline styles.
hl_inline: Highlight without the <pre> wrapper.

Configuration#

config.toml

[markup.highlight]
 codeFences = true
 guessSyntax = false
 lineNos = false
 lineNumbersInTable = true
 noClasses = true
 style = "monokai"
 tabWidth = 4

config.json

{
 "markup": {
 "highlight": {
 "codeFences": true,
 "guessSyntax": false,
 "lineNos": false,
 "lineNumbersInTable": true,
 "noClasses": true,
 "style": "monokai",
 "tabWidth": 4
 }
 }
}

noClasses = true (the default) writes inline styles of style, so the page needs no CSS. With noClasses = false fugo writes Chroma’s class names (<span class="k">), and your stylesheet colours them: this lets you switch colours with light and dark modes. Use any Chroma style sheet; this documentation’s theme defines its own colours in its Sass.

Diagrams

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

GoAT diagrams#

A code block of the language goat becomes an SVG image, built by fugo’s port of GoAT:

```goat
 .---. .------. .------.
 | a +----->| fugo +----->| site |
 '---' '------' '------'
```

a f u g o s i t e

Attributes set the size and the class: ```goat {width=300 class="wide"}. The embedded render-codeblock-goat.html hook draws them; override it to change the markup, or call diagrams_goat(text=…) from your own template.

Mathematics

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

fugo renders LaTeX at build time with KaTeX (0.16.22, with mhchem), as transform.ToMath does in Go templates: pages get MathML and need no script.

Keep the math intact#

Enable the passthrough extension, so Markdown leaves the LaTeX alone and hands it to a render hook:

config.toml

[markup.goldmark.extensions.passthrough]
 enable = true
 [markup.goldmark.extensions.passthrough.delimiters]
 block = [["\\[", "\\]"], ["$$", "$$"]]
 inline = [["\\(", "\\)"]]

Render it#

layouts/_markup/render-passthrough.html

{%- set opts = {"displayMode": type == "block"} -%}
{{- inner | to_math(options=opts) -}}

Now $E = mc^2$ and

Multilingual sites

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

Languages#

config.toml

defaultContentLanguage = "en"
[languages]
 [languages.en]
 languageName = "English"
 weight = 1
 [languages.th]
 languageName = "ไทย"
 languageCode = "th-TH"
 title = "ตัวอย่าง"
 weight = 2
 [languages.th.params]
 subtitle = "เว็บไซต์ตัวอย่าง"

config.yaml

defaultContentLanguage: en
languages:
 en:
 languageName: English
 weight: 1
 th:
 languageCode: th-TH
 languageName: ไทย
 params:
 subtitle: เว็บไซต์ตัวอย่าง
 title: ตัวอย่าง
 weight: 2

config.json

{
 "defaultContentLanguage": "en",
 "languages": {
 "en": {
 "languageName": "English",
 "weight": 1
 },
 "th": {
 "languageCode": "th-TH",
 "languageName": "ไทย",
 "params": {
 "subtitle": "เว็บไซต์ตัวอย่าง"
 },
 "title": "ตัวอย่าง",
 "weight": 2
 }
 }
}

The default language is published at the root (/about/), the others under their key (/th/about/). defaultContentLanguageInSubdir = true puts the default language under /en/ too. disableLanguages = ["th"] leaves a language out of the build.

Data sources

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

Data files#

Files in data/ — JSON, TOML, YAML, CSV and XML — are site.data, by path: data/authors/jane.toml is site.data.authors.jane.

data/authors/jane.toml

name = "Jane Doe"
links = ["https://example.org/jane"]

html

{% set a = site.data.authors[page.params.author] %}
<p class="byline">By {{ a.name }}</p>

A CSV file is a list of rows, each a list of strings. Themes and modules can ship data files; the project’s win.

Content adapters

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

A content adapter is a template named _content.html in a directory of content/. It runs before the site is assembled and adds pages and resources to its directory, as if they were files there.

content/books/_content.html

{%- for b in site.data.books %}
 {{- add_page(page={
 "path": b.slug,
 "title": b.title,
 "dates": {"date": b.published},
 "params": {"author": b.author, "isbn": b.isbn},
 "content": {"mediaType": "text/markdown", "value": b.summary}
 }) -}}
{%- endfor %}

Each book becomes /books/<slug>/, rendered with the section’s layouts like any page, listed in the section, in taxonomies, feeds and the sitemap.

Build options

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

The build front matter decides whether a page is rendered, listed and published.

content/sidebar.md

+++
title = "Sidebar"
[build]
 list = "never"
 render = "never"
 publishResources = false
+++

render: always (default): the page is rendered and published. never: it is neither, but stays available to templates (get_page). link: it is not published, but has a URL.
list: always (default): the page is in page.pages, site.regular_pages and other lists. never: in no list. local: only in its section’s lists, not in site-wide ones.
publishResources: Whether its page resources are copied to the output (default true). Resources the templates use (rel_permalink) are published anyway.

Headless bundles#

A headless bundle holds content other pages use, without being a page itself:

Editing in the browser

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

With a [cms] table in its configuration, a build adds an editor to the site: a page at /admin/ where people edit pages, translations and images in a form, save drafts, and publish them. They sign in with their GitHub or Google account, and they never get access to the git repository: the editor’s API commits as one bot account, with each person as the author of their changes. The site’s usual build then publishes them.

Benchmarks

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

Every change to fugo’s main branch is measured on a GitHub Actions Linux runner, with the binary that CI builds for x86_64-unknown-linux-gnu. The Go implementation that fugo replaced (fugo was written in Go until version 0.148) was measured once, on 2026-10-05, in the same job as fugo, on the same machine: its results stay on the charts as a reference, the dashed blue line, dated in the caption. Hover over a point (or focus it) for the commit and the value. Runners are shared machines, so a single point can be off by a few percent: look at the trend. Lower is better everywhere.