Themes

A theme is a directory that contains the template files and assets needed to generate the site. Currently, there is only one template index.html. Mercury uses Go’s html/template library, which is built upon text/template. You should read the documentation for the latter to get a feel for the templating language and read the former for any HTML-specific behavioural differences.

The template supplied in the default built-in theme should be a good jumping-off point. The top-level fields available are:

Name	Description
`.Name`	The name field from config.toml
`.URL`	The url field from config.toml
`.Owner`	The owner field from config.toml
`.Email`	The email field from config.toml
`.PageNo`	The current page number
`.Items`	A collection of feed items to be rendered

Each feed item has the following fields:

Name	Description	Extras
`.FeedName`	The name of the feed this item is from
`.SiteLink`	The site homepage for the feed
`.FeedLink`	The URL of the feed
`.FeedPublished`	The publication date/time of the feed	formattable
`.FeedUpdated`	The date/time of when the feed was updated	formattable
`.Title`	The title of the item
`.Summary`	A summary of the feed item, if available
`.Content`	The entire content of the feed item, if available
`.Link`	A link back to the original post
`.Author`	The author name, if available
`.Published`	The publication date/time of the entry	formattable
`.Updated`	The date/time when the entry was updated	formattable
`.Categories`	A collection of categories associated with the entry	rangeable

You can use text/template’s {{range}} action to iterate over the values in .Items. For instance, to print the title of each entry and its link, you’d do:

<ul>
{{range .Items}}
<li><a href="{{.Link}}">{{.Title}}</a></li>
{{end}}
</ul>

Mercury provides a number of utility filter functions you can use for formatting dates. isodate formats the date in ISO 8601/RFC 3339 format, which is machine readable and useful for the <time> tag’s datetime attribute. It also includes the Sprig template function library.

Here’s an example of both being used:

<time datetime="{{.Published | isodate}}">{{.Published | date "January 2, 2006 at 15:04:05 MST"}}</time>

Bill of Materials

A theme directory must also contain a theme.toml file. This contains metadata about the theme (currently just its name, which is given in the name field) and optionally a bill of materials listing the files to be copied across, each entry in which is introduced with [[bom]]. Here’s an example file:

name = "Community"

[[bom]]
path = "static/style.css"

[[bom]]
path = "static/images/banner.png"

This lists two files in its BOM, which are copied across when the output directory is populated.