Customising

The settings cover colours, fonts, sizes, width, case and the site's own words. For anything more, the site is yours to change: everything is in plain files, and the build has no plugins to learn.

The stylesheet#

The look is in styles/, one file for each part of the site, which the build joins, in the order of their names, into the one stylesheet readers download, css/site.css:

file	styles
01-colors.css	the colour themes, light and dark
02-base.css	the page column, type, headings, links, and the default sizes
03-content.css	quotations, callouts, code and its copy button, tables, pictures, mathematics
04-galleries.css	galleries and their viewer
05-sidenotes.css	sidenotes and margin notes
06-contents.css	the contents list, and the sidebar it becomes on wide screens
07-pages.css	the animations, the home page, writings, the 404, the licence and the back link
08-docs.css	the docs' list, menu, search, heading links and previous and next
09-motion.css	moving between pages, and less motion for those who ask

Change a part, or add one: 05-footnotes.css would come after 05-sidenotes.css. The settings in config.toml arrive as CSS variables, such as --width and --size-text, so a change can use them too. With -serve, saving a stylesheet rebuilds the site; reload with Ctrl+Shift+R if the browser keeps the old one.

The templates#

The HTML around each kind of page is in templates/, in Go's template language:

template	for
base.html	every page: the head, the back link, the animations' markup and the docs' sidebar
index.html	the home page
post.html	a post
writings.html	the writings list
page.html	a page, in either layout
doc.html, docs.html	a doc, and the list at /docs/
404.html	the page for addresses that don't exist

The site's own words, such as "Back to" or "Contents", come from [words], as {{.Site.Words.Contents}}; add a new one to Words in main.go, with its English. They are set in the chosen case by the stylesheet; give them the class ui inside posts and docs.

A site of its own#

coppice works as Jekyll does: a site is a folder, or a repository, of its own, and coppice is run in it. Its look, the templates, the stylesheet's parts and the scripts, is built into the program, so the folder needs only what's the site's:

go run github.com/spinneydev/coppice@latest -new mysite   # a config.toml, a home page, a first post
cd mysite
go run github.com/spinneydev/coppice@latest -serve :8000

Or go install github.com/spinneydev/coppice@latest once, then coppice -new mysite, coppice and coppice -serve :8000; -site builds a site in another folder than the one it's run in. A site's .cache/ holds the fonts, thumbnails and cloned docs, and public/ the site; neither belongs in git.

A site's folder has its own config.toml, content/ and static/, which needn't hold more than its icon. The look is coppice's, and the site can change any of it with files of its own:

• templates/: a template of the same name as one of coppice's, such as index.html or page.html, takes its place. site.html, if there is one, comes last, and fills the blocks base.html leaves for it: head, at the end of <head>; header, above the page; back, the link one level up, which it can drop; and footer, under the page. It can also replace any other template, such as an animation.
• styles/: each stylesheet joins coppice's, in the order of all their names, so 50-mine.css comes after coppice's own parts and can change them; one named as one of coppice's takes its place.
• static/: copied as it is, over coppice's scripts in js/.

spinney's own sites are built this way, each from its own repository: spinney.dev, a home page and two compact pages under one animation, and canopy.spinney.dev, whose docs are canopy's own markdown. Both change coppice's templates and styles to keep the look they had, and say "powered by coppice" at their foot.

The example site, coppice's own repository, has the whole theme as its own files, so that a change to templates/, styles/ or static/js/ there shows at once, without rebuilding coppice; the sections below are about those files.

A colour theme#

A theme is two blocks in styles/01-colors.css: :root[data-theme="name"] for the light side, and the same inside @media (prefers-color-scheme: dark) for the dark side, each setting --bg, --fg, --muted, --border, --tint, --tint-hover and --accent. Then add its name to themes in main.go, so config.toml can pick it. Keep --fg, --muted and --accent at a contrast of at least 4.5:1 against --bg, as every theme does.

An animation#

An animation is a script in static/js/, run by loop.js, which pauses it off screen and holds it still for readers who ask for less motion. Its markup is a template in base.html, and its name goes in animations in main.go. tools/gifs records each one as a GIF, from the real script: run go -C tools/gifs run ., or go -C tools/gifs run . golden for one.

The program#

main.go is the build, in one file: front matter, markdown, notes, callouts, galleries and thumbnails, the feed, the sitemap, the docs' search index and the checks; fonts.go downloads the fonts. Run go test ./... after changing it: besides its own tests, it builds this example site and checks every link in it.