Awesome
gnrt - lightweight, fast and extensible static site generator
About
A lightweight static site generator written in Python.
Features:
- Markdown-based content
- Frontmatter support
- Jinja2 templating
- Optional YAML-based configuration
Requirements
- Python 3.6+
Installation
pip install --upgrade gnrt
You may need to add $HOME/.local/bin
to your $PATH
.
Usage
gnrt
gnrt
will look for an optional config.yml
file in the current working directory, optional Jinja2 templates in the templates
folder, markdown files in the content
folder, then write the generated output files in the public
folder, while respecting the content
folder and sub-folders structure.
To get a list of options, use:
gnrt -h
Configuration
Configuration is stored in config.yml
. Any key-value pair is allowed. These keys and their values can be used in the content and template files.
---
sitename: My awesome blog
baseurl: https://example.com
language: en
foo: bar
If the config.yml
file exists, gnrt
will look for the defaults
and lists
entries.
Defaults
This is where you define default configuration values, which can be overridden in content files.
Example:
defaults:
template: default.j2
markdown-extras:
- break-on-newline
- fenced-code-blocks
nav: includes/nav.html
bar: foo
Reserved keys
These keys have a specific meaning, and their values can be overridden in content files, like any other default
.
markdown-extras
: allows to enable Markdown extensions, see Extras for a list of valuestemplate
: sets the default Jinja template to be used while rendering content files
Lists
This is where lists of content are defined, allowing the generation of lists of links for instance.
Example:
lists:
nav1:
filter:
key: category
value: page
template: nav-page.j2
nav2:
filter:
key: category
value: article
sort: published
reverse: true
template: nav-article.j2
rss:
filter:
key: category
value: article
sort: published
reverse: true
template: rss.j2
target: public/rss.xml
Lists can select content through a filter
, which gets a metadata key
and a value
to match.
They can be sorted by metadata value (e.g. a published date, an integer, ...), in forward (default) or reverse
order.
During rendering, the generated content is saved in the includes
folder (for caching), while the file path can be customized through the target
key. This allows to generate a RSS feed for instance.
Content files
Content files have the .md
extension and are stored in the content
folder.
Frontmatter
Content files may have a frontmatter - i.e. structured metadata - written in YAML.
This is where default values can be overridden.
Example:
---
id: home
title: Home
link: /
nav-order: 3
---
Reserved keys
id
: the current item identifier, which can be used in any content file to access this item's metadatalink
: URL of the generated pagetarget
: path of the generated filetitle
: title of the current item
Body
Content body
is written in Markdown.
It may also contain Jinja2 syntax and placeholders, allowing injection of dataset
values, such as links to other pages:
Check the [about]({{ data.about.link }}) page or read the [articles]({{ data.articles.link }})!
Example
See the example website in docs/example
, which you can generate by installing gnrt
, cloning this repository, moving to gnrt/docs/example
and executing gnrt
.
You can then browse it at http://localhost:8080/
by moving to the generated public
folder and executing python3 -m http.server 8080
.
You may also want to check a live gnrt-generated blog and read this article about gnrt.