Documents are dived into header and body parts.
---
title: Logya Documentation
template: page.html
created: 2012-03-18 13:59:16
image: /path/to/image.png
---
The header is in YAML format. It starts and ends with 3 dashes. The header is used for setting document attributes, that can be of arbitrary complexity and are accessible in templates. You can set a meta description, the scripts and stylesheets to include and whatever is useful in your scenario. The following attributes are reserved to have special meanings.
Don't set a body
attribute in the document header. It will be set to the body of the document automatically. An existing value will be overwritten.
This is the only required attribute. Set it to the Jinja2 template to use for rendering the document. The template file name has to be specified relative to the templates
directory.
Setting a document title
is highly recommended, but if not present the stem part of the content file name will be set as the document title.
You can manually set a url
attribute, which must be unique and can be used to refer to a document in templates. If you omit the url
it will be created from the file name, e. g. the document in content/book/chapter-1.html
will get the URL /book/chapter-1/
with the file extension removed. File extensions are removed from HTML and Markdown files.
If you specify a created
datetime, you must use the format YYYY-MM-DD HH:MM:SS
as shown in the example. Otherwise it will be set to the file modification time. I recommend setting this manually to the date of first publication. When you call the get_docs
function in templates, by default documents will be sorted by created
in descending order, so newest documents show up first. This is also the order in which documents appear in automatically created collection pages.
The updated
datetime works like created
and should show when the document was last edited. This can be useful if you want to highlight an edit, but typically the default value is fine.
Use pre_render
to enable the use of Jinja template syntax and documents. A sample use case would be for creating absolute URLs for internal links using the base_url
setting.
<a href="{{ base_url }}/path/to/page/">Link text</a>
For this to work you have to set pre_render
to a list of attribute names. To pre-render the body
add the following line to the document header.
pre_render: [body]
You can create document collections using content attributes and corresponding settings in site.yaml
. An example is to categorize content using a tags
attribute.
tags: [source code, python, programming]
For each value in tags
a collection is created, that contains all documents where value appears in the tags
attribute. For each tag value a page is automatically created where you can show the documents in that collection. The URL of the collection page is created from the collection path
value in site.yaml
and the value, e. g. the source code
collection URL could be /tag/source-code/
.
For each collection in a document an additional template variable will be available named from the collection name and the suffix _links
, e. g. tags_links
. This can be used in templates to create a list of links to the collection pages on a content page.
<ul>
{% for url, anchor in tags_links %}
<li><a href="{{ url }}">{{ anchor }}</a></li>
{% endfor %}
</ul>
Only use letters and underscores in the names of collections and set the document attribute to a list of string values.
The part after the second ---
separator is the document body
. Text written in Markdown will be converted to HTML, if the corresponding file name ends with .md
or .markdown
.