Update readme

This commit is contained in:
Vincent Prouillet 2017-03-23 21:58:40 +09:00
parent ba7d0c3672
commit d9d822c825
3 changed files with 133 additions and 27 deletions

155
README.md
View file

@ -2,39 +2,146 @@
[![Build Status](https://travis-ci.org/Keats/gutenberg.svg?branch=master)](https://travis-ci.org/Keats/gutenberg)
[![Build status](https://ci.appveyor.com/api/projects/status/h4t9r6h5gom839q0/branch/master?svg=true)](https://ci.appveyor.com/project/Keats/gutenberg/branch/master)
## Design
An opinionated static site generator written in Rust.
Can be used for blogs or general static pages
## Installation
You can get the latest release by going to the [Release page](https://..).
Alternatively, if you have the rust toolchain on your computer, you can also install it
through Cargo: `cargo install gutenberg`.
Commands:
## Usage
- new: start a new project -> creates the structure + default config.toml
- build: reads all the .md files and build the site with template
- serve: starts a server and watches/reload the site on change
### Creating a new site
Use `gutenberg init <a_directory_name>`.
This will create a folder with the name given and the base structure of a gutenberg site.
### Working on a site
Use `gutenberg serve` to spin up a server that will automatically live reload any changes to the
content, templates or static files.
All pages go into the `content` folder. Subfolder represents a list of content, ie
### Building a site
Use `gutenberg build` to generate the site in the `public/` directory.
```bash
├── content
│   ├── posts
│   │   └── intro.md
│   └── some.md
### Gutenberg terms
Some words are going to be repeated in the docs so let's make sure they are clear.
- Page: a markdown file in the `content` directory that has a name different from `_index.md`
- Section: a group of pages in the `content` directory that has `_index.md` in the same folder
### Configuration
Configuration is using the [TOML](https://github.com/toml-lang/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 false
- `highlight_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 false
- `generate_tags_pages`: Whether to generate tags and individual tag pages if some pages have them. Defaults to true
- `generate_categories_pages`: Whether to generate categories and individual category categories if some pages have them. Defaults to true
If 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
Templates live in the `templates/` directory.
Only [Tera](https://github.com/Keats/tera) templates are supported.
Each kind of page get their own variables:
// TODO: detail the schema of the variables
- index.html: gets `pages` that contain all pages in the site
- page.html: gets `page` that contains the data for that page
- section.html: gets `section` that contains the data for pages in it and its subsections
- tags.html: gets `tags`
- tag.html: gets `tag` and `pages`
- categories.html: gets `categories`
- category.html: gets `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.
### Static files
Everything in the `static` folder will be copied into the output directory as-is.
### Pages
Pages have to start with a front-matter enclosed in `+++`. Here is a minimal example:
```md
+++
title = "My page"
description = "Some meta info"
+++
A simple page with fixed url
```
`some.md` will be accessible at `mywebsite.com/some` and there will be other pages:
A front-matter requires a title, a description and has the following optional variables:
- `mywebsite.com/posts` that will list all the pages contained in the `posts` folder
- `mywebsite.com/posts/intro`
- date: a YYYY-MM-DD or RFC339 formatted date
- slug: what slug to use in the url
- url: this overrides the slug and make this page accessible at `{config.base_url}/{url}`
- tags: an array of strings
- category: only one category is allowed
- draft: whether the post is a draft or not
- template: if you want to change the template used to render that specific page
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.
### Building the site
Get all .md files in content, remove the `content/` prefix to their path
Split the file between front matter and content
Parse the front matter
markdown -> HTML for the content
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.
### Themes
Gallery at https://tmtheme-editor.herokuapp.com/#!/editor/theme/Agola%20Dark
Make .themedump file:
`cargo run --example generate_themes themepack sublime_themes sublime_themes/all.themedump`
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.
### Sections
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:
```md
+++
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 themes
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:
- base16-ocean-dark
- base16-ocean-light
- gruvbox-dark
- gruvbox-light
- inspired-github
- kronuz
- material-dark
- material-light
- monokai
- solarized-dark
- solarized-light
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.

View file

@ -13,9 +13,6 @@ main() {
cross test --target $TARGET
cross test --target $TARGET --release
cross run --target $TARGET
cross run --target $TARGET --release
}
# we don't run the "test phase" when doing deploys

2
notes.md Normal file
View file

@ -0,0 +1,2 @@
## Make .themedump file:
`cargo run --example generate_themes themepack sublime_themes sublime_themes/all.themedump`