Settings

Every setting lives in config.toml, and each has a comment there saying what it does. A setting the build doesn't know, which is usually a typo, stops it, as does a value it doesn't accept.

The site#

setting	what it is
title	the site's name: the home page's title, the end of every page's title, the feed's name. Required
url	where the site lives, such as https://example.com, without a slash at the end; the feed links to it. Required
description	one line about the site, for search engines, link previews and the feed
language	the language the site is written in, such as en, de or pt-BR; screen readers pronounce the text by it. en if left out
goatcounter	your GoatCounter count URL, to count page views, or "" for none

The home page#

links are the links under the home page's text, in order, and the menu of compact pages:

links = [
  { name = "About", url = "/about/" },
  { name = "Writings", url = "/writings/" },
]

A link can go to a page of the site, the writings list, the docs (/docs/), the feed (/feed.xml) or anywhere else. The build checks that every link to the site itself goes somewhere.

animation picks what home and compact pages show on top: shapes, curve, cycloid, mandelbrot, cycloid-horizontal, medley, ford, golden, nautilus, sine, penrose, chords or newton; random for one of them, picked once per visit; custom for one of those listed in custom, such as ["curve", "ford"]; or "" for none. A tour of coppice describes each.

Layout#

setting	what it is
width	how wide the text's column is, on every page, in any CSS unit: 44rem by default, about 700 pixels
contents	true for a contents list on posts with two or more ## headings, and each doc's sections in the docs' sidebar; false for none

Colours#

[colors] has two settings, each with a light and a dark side that follow the reader's system:

• site: paper, catppuccin, gruvbox, solarized, nord, rose-pine, tokyo-night, everforest, dracula, clrs or spinney. In every theme, text, quiet text and links have a contrast of at least 4.5:1.
• code: the colours of code blocks: github, catppuccin, gruvbox, solarized, rose-pine, tokyo-night, kanagawa, modus, xcode or monokai; or "" for plain blocks in the site's colours.

Licence#

[license] is the licence of your writing and pictures: name, such as cc by-sa 4.0, and url, a link to its text. It's shown under each post and in the feed; leave name empty to show none. It says nothing about coppice's own code, which is under the GPL.

Fonts#

[fonts] names two families from Google Fonts, as the site shows them: text for everything, mono for code. The build downloads them and the site serves them itself, so readers never contact Google. The defaults are Atkinson Hyperlegible Next and Atkinson Hyperlegible Mono, drawn by the Braille Institute for readers with low vision.

subsets lists the character sets downloaded, as Google Fonts names them: ["latin", "latin-ext"] by default. A site in Russian or Greek adds "cyrillic" or "greek", or its letters fall back to the reader's own fonts. A font that has none of them stops the build.

case sets the case of the site's own text, everywhere but in posts, docs and the writings list, which keep the case they're written in: lowercase, the default, normal (as typed), uppercase, capitalize or small-caps. Type the site's text in sentence case, and every choice reads well.

Sizes#

[sizes] sets the size of each kind of text, in any CSS unit, used as typed:

size	of
text	the body text: 1.25rem, 20 pixels, by default, and a tenth smaller on phones
title	a page's, post's or doc's title
subtitle	a post's or doc's description, under its title
heading, subheading, minor	##, ### and #### headings
date	dates, the licence line and the back link
notes	sidenotes and margin notes
references	everything after a ## References heading
code	code, in a line and in blocks
captions	the words under pictures and in galleries
tables, quotes	tables and quotations
contents	the contents list and the docs' sidebar

An em size is relative to the text around it, so it follows text; rem and px stay put whatever text is. A size left out keeps its default.

Docs from another repository#

[docs] adds docs that live somewhere else, such as a program's own manual in its repository, read as they are: plain markdown, with no front matter. Each page's # heading is its title, and links between the pages go to their pages here; a link to any other file of the repository goes to it in files.

[docs]
source = "../../canopy"   # a checkout of it, from the site's folder
repo = "https://github.com/spinneydev/canopy"
files = "https://github.com/spinneydev/canopy/blob/main/"
pages = [
  { file = "deploy.md", slug = "deploy", name = "Deploying", description = "Putting it on a server." },
  { file = "config/README.md", slug = "configuration", name = "Configuration" },
]

The pages come in this order, before any doc of content/docs/ without an order. name is a page's name in the sidebar, the pager and /docs/, and each page links to its markdown in files, as "View this page's source". With no source there, as on a host that builds from git, the build clones repo into .cache/repos/ and reads it there, bringing it up to date at the first build of each run. With -serve, a page saved in source rebuilds the site.

Words#

[words] holds the words the site writes itself, for a site in another language: the back links, Contents, Previous and Next, the 404 page, the docs' search box, the titles of callouts, and the names screen readers give the parts of a page. Each is English unless set; config.toml lists them all, with their English:

language = "de"

[words]
back_home = "Zurück zur Startseite"
contents = "Inhalt"
long_date = "2. January 2006"
months = ["Januar", "Februar", "März", "April", "Mai", "Juni", "Juli",
  "August", "September", "Oktober", "November", "Dezember"]

date, for the writings list, and long_date, under a post's title, are how dates are written, as Go writes the day 2 January 2006 (its layouts); the month's name comes from months, which needs all twelve. A word set to "" stops the build.