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: ```python { "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](https://mistune.lepture.com/en/latest/). 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: ```yaml - 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.

# 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: ```python { "site": ": any", "page": ": any", } ``` Frontmatter is templated with the context of `{"site": ""}`. Some frontmatter keys that are treated specially are: * `title`: the page title, used in the \ 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: ```python { "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](https://mistune.lepture.com/en/latest/). 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: ```yaml - 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.