akpain.net documentation

Content templating

The site/content directory will be walked with any files and directories starting with _ being ignored. Files included in templates (eg. site/content/_layouts/*) are except from this and can be accessed via Jinja.

Filenames should not have any dots (.) in them apart from those separating the file name and extension as this may interfere with processing.

*.html files will be templated
*.md files will be rendered to HTML then wrapped in HTML boilerplate
other files, or files with the above types that do not have valid YAML frontmatter, will be copied directly to the output.

When being templated, files are executed with the following context:

{
    "site": "<parsed YAML content of the site/config.yml file>: any",
    "page": "<parsed YAML frontmatter of the template>: any",
}

Frontmatter is templated with the context of {"site": "<as above>"}.

Some frontmatter keys that are treated specially are:

title: the page title, used in the <title> tag and metadata
description: the page description, used in the page's metadata
canonicalURL: the canonical URL of the page, used in the page's metadata. When blank, this will be derived from the filepath.
preserveCanonicalURL: this will prevent the canonical URL from being overridden if left blank when set to true
imageURL: the URL of an image to be used in the page's metadata
asDirectory: if set, controls if this file is rendered as a directory
- When true, a template called /credits.html will be rendered to /credits/index.html
- If unset, the page will be rendered as a directory if its stem is not index
hideAside: boolean, hides the aside panel if True
isTemplate: will execute the file as a Jinja template if true - defaults to true in HTML files and false in regular Markdown (and is not defined for Markdown blog posts)
showToc: in normal Markdown files only (ie. not blog posts), will show a table of contents in the aside. Tables of contents will exclude h1 headers.

Blog content

The site/blog directory will be walked with any files and directories starting with _ being ignored.

*.md files will be templated and rendered using the site/content/_layouts/blog/post.html template using the frontmatter below; other files will be copied directly to the output.

The filename of the Markdown file will be used as the slug of the post. If the filename is content.md, the name of the parent directory of the file will be used as the post slug.

When being rendered, the following context is provided:

{
    "site": "<parsed YAML content of the site/config.yml file>: any",
    "post": "<parsed YAML frontmatter of the post>: any",
    "content": "<rendered HTML content of the post>: str"
}

The frontmatter is not templated.

Some frontmatter keys that are treated specially are:

title: required, the post title
description: the post description
imageURL: the URL of an image to be used in the page's metadata
publishedDate: required, date in the form YYYY-MM-DD
updatedDate: a list of dates in the form YYYY-MM-DD. These are sorted in descending order before being passed to templates.
hidden: a boolean value, omits the post from the listing and feeds if true
tags: a list of tags that can be applied to a post

Any post with the special tag favourite is highlighted in the main post listing.

Writing in Markdown

Markdown rendering is controlled by generator/markdown.py, which makes use of Mistune. This is where information on the currently enabled plugins and directives can be found. All enabled directives use the fenced style.

The rendering code has been extended to support variable header level increases and code syntax highlighting.

Redirects

Redirects are defined in a redirects.yml file in the site's base directory. Its internal structure should be an array of objects like this:

- from: "/tools/maths"
  to: "/tools/mathsEditor"
  code: 301
  transform: false

The keys have the following meanings:

from: required
to: required
code: the HTTP status code to perform the redirect with. Must be within the 300 <= n < 400 range. Default is 302.
transform: when set to true, when the from value does not end with a /, an identical, duplicate entry is created, except with the from value being followed by a /. Default is true.

Deployment

The site can be generated as follows:

poetry run python3 generator/ site/

By default, this will output the site to _dist - however this can be controlled with the --output-dir flag. Site content is generated in the html directory.

When building for production, the --production flag should be used, which does extra postprocessing (eg. compressing images).

Redirects and 404 handling are implemented by generating a Caddy configuration that is shipped with the generated site (caddy_config.json).

The Dockerfile included will build and package the site into a functional container by using a bundled Caddy server that will serve content on port 8080.

5.1 KiB Raw Permalink Blame History