Vincent Prouillet a6b8caf6de | 7 years ago | |
---|---|---|
benches | 7 years ago | |
ci | 7 years ago | |
examples | 7 years ago | |
src | 7 years ago | |
sublime_themes | 7 years ago | |
test_site | 7 years ago | |
tests | 7 years ago | |
.editorconfig | 8 years ago | |
.gitignore | 7 years ago | |
.travis.yml | 7 years ago | |
CHANGELOG.md | 7 years ago | |
Cargo.lock | 7 years ago | |
Cargo.toml | 7 years ago | |
README.md | 7 years ago | |
appveyor.yml | 7 years ago | |
notes.md | 7 years ago |
An opinionated static site generator written in Rust.
You can get the latest release by going to the Release page.
Alternatively, if you have the rust toolchain on your computer, you can also install it
through Cargo: cargo install gutenberg
.
Use gutenberg init <a_directory_name>
.
This will create a folder with the name given and the base structure of a gutenberg site.
Use gutenberg serve
to spin up a server that will automatically live reload any changes to the
content, templates or static files.
Use gutenberg build
to generate the site in the public/
directory.
Some words are going to be repeated in the docs so let's make sure they are clear.
content
directory that has a name different from _index.md
content
directory that has _index.md
in the same folderConfiguration is using the TOML language.
Only 2 parameters are required: title
and base_url
.
The other options are:
highlight_code
: Whether to highlight all code blocks found in markdown files. Defaults to falsehighlight_theme
: Which themes to use for code highlighting. Defaults to “base16-ocean-dark”language_code
: The language used in the site. Defaults to “en”generate_rss
: Whether to generate RSS, defaults to falsegenerate_tags_pages
: Whether to generate tags and individual tag pages if some pages have them. Defaults to truegenerate_categories_pages
: Whether to generate categories and individual category categories if some pages have them. Defaults to trueIf you want to add some of your own variables, you will need to put them in the [extra]
table in config.toml
or
they will be silently ignored.
Templates live in the templates/
directory.
Only Tera templates are supported.
Each kind of page get their own variables:
// TODO: detail the schema of the variables
pages
that contain all pages in the sitepage
that contains the data for that pagesection
that contains the data for pages in it and its subsectionstags
tag
and pages
categories
category
and pages
Additionally, all pages get a config
variable representing the data in config.toml
.
If you want to know all the data present in a template content, simply put {{ __tera_context }}
in the templates and it will print it.
Everything in the static
folder will be copied into the output directory as-is.
Pages have to start with a front-matter enclosed in +++
. Here is a minimal example:
+++
title = "My page"
description = "Some meta info"
+++
A simple page with fixed url
A front-matter requires a title, a description and has the following optional variables:
{config.base_url}/{url}
You can also, like in the config, add your own variables in a [extra]
table.
The front-matter will be accessible in templates at the page.meta
field.
By default, the URL of a page will follow the filesystem paths. For example, if you have
a page at content/posts/python3.md
, it will be available at {config.base_url}/posts/python3/
.
You can override the slug created from the filename by setting the slug
variable in the front-matter.
Quite often, a page will have assets and you might want to co-locate them with the markdown file.
Gutenberg supports that pattern out of the box: you can create a folder, put a file named index.md
and any number of files
along with it that are NOT markdown.
Those assets will be copied in the same folder when building so you can just use a relative path to use them.
A summary is only defined if you put <!-- more -->
in the content. If present in a page, the summary will be from
the start up to that tag.s
Sections represent a group of pages, for example a tutorials
section of your site.
Sections are only created in Gutenberg when a file named _index.md
is found in the content
directory.
This _index.md
file needs to include a front-matter as well, but won't have content:
+++
title = "Tutorials"
description = ""
+++
Both title
and description
are mandatory, you can also set the template
variable to change
which template will be used to render that section.
Sections will also automatically pick up their subsections, allowing you to make some complex pages layout and table of contents.
Code highlighting can be turned on by setting highlight_code = true
in config.toml
.
When turned on, all text between backticks will be highlighted, like the example below.
```rust
let site = Site::new();
```
If the name of the language is not given, it will default to plain-text highlighting.
Gutenberg uses Sublime Text themes for syntax highlighting. It comes with the following theme built-in:
A gallery containing lots of themes at https://tmtheme-editor.herokuapp.com/#!/editor/theme/Agola%20Dark. More themes can be easily added to gutenberg, just make a PR with the wanted theme.