From d9d822c8250fb212c3339f6a5df3bca0c4a917be Mon Sep 17 00:00:00 2001 From: Vincent Prouillet Date: Thu, 23 Mar 2017 21:58:40 +0900 Subject: [PATCH] Update readme --- README.md | 155 +++++++++++++++++++++++++++++++++++++++++++-------- ci/script.sh | 3 - notes.md | 2 + 3 files changed, 133 insertions(+), 27 deletions(-) create mode 100644 notes.md diff --git a/README.md b/README.md index 6554e197..43da7b87 100644 --- a/README.md +++ b/README.md @@ -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 `. +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. diff --git a/ci/script.sh b/ci/script.sh index ddd7f936..293504df 100644 --- a/ci/script.sh +++ b/ci/script.sh @@ -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 diff --git a/notes.md b/notes.md new file mode 100644 index 00000000..5d2baffb --- /dev/null +++ b/notes.md @@ -0,0 +1,2 @@ +## Make .themedump file: +`cargo run --example generate_themes themepack sublime_themes sublime_themes/all.themedump`