106 lines
5.1 KiB
Markdown
106 lines
5.1 KiB
Markdown
# 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": "<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:
|
|
|
|
```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.
|