Getting started

What you need#

Go 1.25 or newer, and nothing else: no Node, no package manager, no database. The first build needs the internet, to download the fonts from Google Fonts; they are kept in .cache/fonts/, and builds after that work offline.

Build and look#

A new site of your own, in a folder of its own, as with Jekyll:

go run github.com/spinneydev/coppice@latest -new my-site
cd my-site
go run github.com/spinneydev/coppice@latest -serve :8000

Or this whole example, with every feature at work, to change into yours:

git clone https://github.com/spinneydev/coppice.git my-site
cd my-site
go run . -serve :8000

Either way, coppice builds the site into public/. With -serve :8000 it then serves it on localhost:8000, answering a missing page with public/404.html as most hosts do, and builds it again whenever you save a file in content/, templates/, styles/, static/ or config.toml: reload the page to see the change. A change to the program itself, main.go or fonts.go, needs a fresh start: stop it with Ctrl+C and run it again.

Add -drafts to build drafts and posts dated after today too, to see them before they're published.

Where everything lives#

config.toml     every setting, explained in its comments
content/
  index.md      the home page's text
  <name>.md     a page, at /<name>/
  posts/        posts, at /posts/<name>/
  docs/         docs like these, at /docs/<name>/
static/         copied into the site as it is: pictures, the icon
templates/      changes to the HTML around every kind of page
styles/         changes to the stylesheet

A new site has only config.toml and content/: the templates and the stylesheet are coppice's, and a file of the same name in templates/ or styles/ changes them. This example has the whole of them as its own, with the program beside them: main.go, the build, and fonts.go, which downloads the fonts.

What you write goes in content/, pictures and other files in static/, and what you change about the site's look and behaviour in config.toml. The settings cover most of what people want to change; customising covers the rest.

Making it yours#

1. Set title, url and description in config.toml, and pick an animation, a colour theme and fonts.
2. Write content/index.md, a few lines about you, and your addresses in content/contact.md.
3. Rewrite or delete the examples: content/about.md, the gallery (content/gallery.md and static/images/gallery/), the posts and their pictures, and these docs (content/docs/). Remove the links to anything you delete from links in config.toml.
4. Put your own icon in static/images/favicon.ico (or .svg, or .png).
5. Write your first post: see pages, posts and docs.

When the build stops#

coppice would rather stop than build a broken site. When it does, it names the file and what is wrong:

• a setting it doesn't know, which is usually a typo, or a value it doesn't accept;
• a front matter line it doesn't know, or a value it can't read, such as a date in another order;
• a post without a date, or a page or post without a title;
• a page whose name is taken by part of the site, such as content/css.md;
• a link to a page, a file or a section of the site that isn't there, such as /about/ after deleting about.md, or /docs/settings/#colors for #colours;
• a gallery holding more than pictures.

With -serve, a build that stops leaves the last good site up: fix what it names, save, and it builds again. A picture without alt text, or a site without an icon, doesn't stop it, but is reported, so you can put it right.