Add more docs pages

This commit is contained in:
Vincent Prouillet 2017-10-01 12:51:43 +09:00
parent dee1dbe667
commit 57b87aa50a
16 changed files with 243 additions and 9 deletions

View file

@ -14,6 +14,7 @@
- Remove `insert_anchor_links` from the config: it wasn't used
- Add `class` variable to `gist` shortcode
- Add reading analytics to sections content
- Add config to sitemap template
## 0.1.3 (2017-08-31)

View file

@ -35,7 +35,6 @@ pub struct SectionFrontMatter {
pub paginate_path: Option<String>,
/// Whether to insert a link for each header like the ones you can see in this site if you hover one
/// The default template can be overridden by creating a `anchor-link.html` in the `templates` directory
/// This can also be set in a section front-matter if you only want it for
pub insert_anchor_links: Option<InsertAnchor>,
/// Whether to render that section or not. Defaults to `true`.
/// Useful when the section is only there to organize things but is not meant

View file

@ -647,6 +647,7 @@ impl Site {
}
}
context.add("tags", &tags);
context.add("config", &self.config);
let sitemap = &render_template("sitemap.xml", &self.tera, &context, self.config.theme.clone())?;

View file

@ -64,7 +64,7 @@ impl Taxonomy {
// Find all the tags/categories first
for page in all_pages {
// Don't consider pages without pages for tags/categories as that's the only thing
// Don't consider pages without dates for tags/categories as that's the only thing
// we can sort pages with across sections
// If anyone sees that comment and wonder wtf, please open an issue as I can't think of
// usecases other than blog posts for built-in taxonomies

View file

@ -24,7 +24,7 @@ This option is set at the section level, look up the `insert_anchor_links` varia
[Section front-matter page](./documentation/content/section.md#front-matter).
The default template is very basic and will need CSS tweaks in your project to look decent.
If you want to change the anchor template, itt can easily be overwritten by
If you want to change the anchor template, it can easily be overwritten by
creating a `anchor-link.html` file in the `templates` directory.
## Internal links

View file

@ -47,7 +47,6 @@ paginate_by = "page"
# Whether to insert a link for each header like the ones you can see in this site if you hover one
# The default template can be overridden by creating a `anchor-link.html` in the `templates` directory
# This can also be set in a section front-matter if you only want it for
# Options are "left", "right" and "none"
insert_anchor_links = "none"

View file

@ -75,14 +75,14 @@ Both page and section have a `toc` field which corresponds to an array of `Heade
A `Header` has the following fields:
```ts
// the hx level
// The hX level
level: 1 | 2 | 3 | 4 | 5 | 6;
// the generated slug id
// The generated slug id
id: String;
// the text of the header
// The text of the header
title: String;
// a link pointing directly to the header, using the inserted anchor
// A link pointing directly to the header, using the inserted anchor
permalink: String;
// all lower level headers below this header
// All lower level headers below this header
children: Array<Header>;
```

View file

@ -0,0 +1,28 @@
+++
title = "Pagination"
weight = 30
+++
A paginated section gets the same `section` variable as a normal
[section page](./documentation/templates/pages-sections.md#section-variables) and will use
the template mentioned in the section front-matter or the default one.
In addition, a paginated section gets a `paginator` one, which has a `Pager` type:
```ts
// How many items per page
paginate_by: Number;
// Permalink to the first page
first: String;
// Permalink to the last page
last: String;
// Permalink to the previous page, if there is one
previous: String?;
// Permalink to the next page, if there is one
next: String?;
// All pages for the current page
pages: Array<Page>;
// All pagers for this section, but with their `pages` attribute set to an empty array
pagers: Array<Pagers>;
// Which page are we on
current_index: Number;
```

View file

@ -0,0 +1,14 @@
+++
title = "Robots.txt"
weight = 70
+++
Gutenberg will look for a `robots.txt` file in the `templates` directory or
use the built-in one.
Robots.txt is the simplest of all templates: it doesn't take any variables
and the default is what most site want.
```jinja2
User-agent: *
```

View file

@ -0,0 +1,16 @@
+++
title = "RSS"
weight = 50
+++
Gutenberg will look for a `rss.xml` file in the `templates` directory or
use the built-in one. Currently it is only possible to have one RSS feed for the whole
site, you cannot create a RSS feed per section or taxonomy.
**Only pages with a date and that are not draft will be available.**
The RSS template gets two variables in addition of the config:
- `last_build_date`: the date of the latest post
- `pages`: see [the page variables](./documentation/templates/pages-sections.md#page-variables) for
a detailed description of this variable.

View file

@ -0,0 +1,23 @@
+++
title = "Sitemap"
weight = 60
+++
Gutenberg will look for a `sitemap.xml` file in the `templates` directory or
use the built-in one.
The sitemap template gets four variables in addition of the config:
- `pages`: all pages of the site
- `sections`: all sections of the site, including an index section
- `tags`: links the tags page and individual tag page, empty if no tags
- `categories`: links the categories page and individual category page, empty if no categories
As the sitemap only requires a link and an optional date for the `lastmod` field,
all the variables above are arrays of `SitemapEntry` with the following type:
```ts
permalink: String;
date: String?;
```

View file

@ -0,0 +1,30 @@
+++
title = "Tags & Categories"
weight = 40
+++
Tags and categories actually get the same data but with different variable names.
The default templates for those pages are the following:
- `tags.html`: list of tags, gets variable `tags`
- `tag.html`: individual tag, gets variable `tag`
- `categories.html`: list of categories, gets variable `categories`
- `category.html`: individual category, gets variable `category`
You can override any of those templates by putting one with the same name in the `templates` directory.
`tags` and `categories` both are an array of `TaxonomyItem` sorted alphabetically, while `tag` and `category`
are a `TaxonomyItem`.
A `TaxonomyItem` has the following fields:
```ts
name: String;
slug: String;
// Permalink to the generated page
permalink: String;
pages: Array<Page>;
```
Currently, there is no way to define different taxonomy templates per section, change
the path used for them or paginate them.

View file

@ -0,0 +1,53 @@
+++
title = "Creating a theme"
weight = 30
+++
Creating is exactly like creating a normal site with Gutenberg, except you
will want to use many [Tera blocks](https://tera.netlify.com/docs/templates/#inheritance) to
allow users to easily modify it.
A theme also need to have a `theme.toml` configuration file with the
following fields, here's the one from a [real template](https://github.com/Keats/hyde):
```toml
name = "hyde"
description = "A classic blog theme"
license = "MIT"
homepage = "https://github.com/Keats/gutenberg-hyde"
# The minimum version of Gutenberg required
min_version = "0.1"
# Any variable there can be overriden in the end user `config.toml`
# You don't need to prefix variables by the theme name but as this will
# be merged with user data, some kind of prefix or nesting is preferable
# Use snake_casing to be consistent with the rest of Gutenberg
[extra]
hyde_sticky = true
hyde_reverse = false
hyde_theme = ""
hyde_links = [
{url = "https://google.com", name = "Google.com"},
{url = "https://google.fr", name = "Google.fr"},
]
# The theme author info: you!
[author]
name = "Vincent Prouillet"
homepage = "https://vincent.is"
# If this is porting a theme from another static site engine, provide
# the info of the original author here
[original]
author = "mdo"
homepage = "http://markdotto.com/"
repo = "https://www.github.com/mdo/hyde"
```
A theme will also need three directories to work:
- `static`: any static files used in this theme
- `templates`: all templates used in this theme
- `sass`: Sass stylesheets for this theme, can be empty
A simple theme you can use as example is [Hyde](https://github.com/Keats/hyde).

View file

@ -0,0 +1,52 @@
+++
title = "Installing & using themes"
weight = 20
+++
## Installing a theme
The easiest way to install to theme is to clone its repository in the `themes`
directory.
```bash
$ cd themes
$ git clone THEME_REPO_URL
```
Cloning the repository using Git or another VCS will allow you to easily
update it but you can also simply download the files manually and paste
them in a folder.
## Using a theme
Now that you have the theme in your `themes` directory, you only need to tell
Gutenberg to use it to get started by setting the `theme` variable of the
[configuration file](./documentation/getting-started/configuration.md). The theme
name has to be name of the directory you cloned the theme in.
For example, if you cloned a theme in `templates/simple-blog`, the theme name to use
in the configuration file is `simple-blog`.
## Customizing a theme
Any file from the theme can be overriden by creating a file with the same path and name in your `templates` or `static`
directory. Here are a few examples of that, assuming the theme name is `simple-blog`:
```plain
templates/pages/post.html -> will override themes/simple-blog/pages/post.html
templates/macros.html -> will override themes/simple-blog/macros.html
static/js/site.js -> will override themes/simple-blog/static/js/site.jss
```
Most themes will also provide some variables that are meant to be overriden: this happens in the `extra` section
of the [configuration file](./documentation/getting-started/configuration.md).
Let's say a theme uses a `show_twitter` variable and sets it to `false` by default. If you want to set it to `true`,
you can update your `config.toml` like so:
```toml
[extra]
show_twitter = false
```
You can modify files directly in the `themes` directory but this will make updating harder and live reload won't work with those
files.

View file

@ -0,0 +1,10 @@
+++
title = "Overview"
weight = 10
+++
Gutenberg has built-in support for themes in a way that are easy to customise
but still easy to update if needed.
All themes can use the full power of Gutenberg, from shortcodes to Sass compilation.

View file

@ -0,0 +1,8 @@
+++
title = "List of themes"
weight = 40
+++
The following themes are available for Gutenberg:
- [Hyde](https://github.com/Keats/gutenberg-hyde)