💾 Archived View for talon.computer › wiki › Kiln captured on 2023-11-04 at 11:25:37. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-09-08)
-=-=-=-=-=-=-
Last updated: 2023-08-22 00:00:00
git clone https://git.sr.ht/~adnano/kiln cd kiln make sudo make install
and then create a capsule:
kiln new [name of capsule]
This page is intended to be a crash course to get you started using kiln right away. The man page provided by kiln upon installation is very good and you'll want to reference it a lot probably:
man kiln
The soul of the capsule is here and kiln gives files in this folder a few powers: frontmatter and templating. Templating will be discussed below. Frontmatter is metadata that is used in a few different ways. It's colon-separated key-value pairs at the top of the file sandwhiched between three hyphens like this:
--- title: kiln date: 2023-08-21 params: summary: kiln is the command-line tool I use to build this capsule. ---
That's the actual frontmatter for the page you're reading right now! Title and date are built-in to kiln in that when you build the capsule these will be provided to the templates and will also be used internally to create the final build folder. Custom params can be provided in the params key. Pages in this wiki folder all have a summary that gets used by the index template for the wiki. The date will also affect in which order the template shows pages, newest first.
And that's pretty much it. Frontmatter is just a special way to keep metadata about a document with the document. We'll see how as a user you can tap into this metadata in the templates now...
kiln new gives you a few _default templates. the atom.xml one can be ignored for now because it's less personalizable and works fine out of the box. The index.gmi and page.gmi templates are what you're going to want to modify copy and remix. The magic behind these templates is Go...which has a nice templating library. Although I find myself futzing with whitespace a bit too much.
read the Go template documentation
An important excerpt from the man page:
Files with the name "_index" are treated specially. They can be used to provide frontmatter and content for the parent directory which will other‐wise have none. If an "_index" file is present in a directory, an index page (e.g. "index.gmi") for that directory will be generated and written to the output directory.
The _index.gmi files live under content and pull from the index.gmi files in the templates folder. The _default index.gmi that you get with kiln new looks like this:
# {{ .Title }}
{{ if .Content }}
{{ .Content }}{{ end }}
{{ range .Pages }}=> {{ .Path }} {{ if not .Date.IsZero -}}
{{ .Date.Format "2006-01-02" }} {{end}}{{ .Title }}
{{ end -}}
It might take a second to squint past the curly-brackets but they are a special syntax for accessing the variables provided to the index by kiln when building. The above template would render the frontmatter title from _index.gmi through {{ .Title }} and if that file has any content that would be rendered via {{ .Content }}
{{ range .Pages }} will run for each page that's not _index.gmi in that specific content folder. For a typical blog that would likely look like a bunch of date prefixed .gmi files. (ex. 2023-08-22-name.gmi) Adding a date prefix to a filename in kiln is just like providing the date in frontmatter, you can use either method but it's a good idea to stick to one at least in each content folder. I like the date prefix because then sorting by filename sorts by date.
Inside the {{ range.Pages }} loop you have access to the page variables. These are not the index variables.
The _default page.gmi template looks like this:
# {{ .Title }}
{{- if not .Date.IsZero }}
Posted on {{ .Date.Format "2006-01-02" }}{{ end }}
{{ .Content }}
Not much new here in terms of syntax, you've made it past the worst part really. The man page for kiln has all the doumented page and index variables (and feed!) as well as the available template functions for things like string and path manipulation. This is where you go off and get creative with these new powers.
