Add more docs pages

CHANGELOG.md

@@ -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)
 

components/front_matter/src/section.rs

@@ -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

components/site/src/lib.rs

@@ -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())?;
 

components/taxonomies/src/lib.rs

@@ -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

docs/content/documentation/content/linking.md

@@ -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

docs/content/documentation/content/section.md

@@ -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"
 

docs/content/documentation/templates/pages-sections.md

@@ -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>;
 ```

docs/content/documentation/templates/pagination.md

@@ -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;
+```

docs/content/documentation/templates/robots.md

@@ -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: *
+```

docs/content/documentation/templates/rss.md

@@ -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.

docs/content/documentation/templates/sitemap.md

@@ -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?;
+```

docs/content/documentation/templates/tags-categories.md

@@ -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.
+

docs/content/documentation/themes/creating-a-theme.md

@@ -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).

docs/content/documentation/themes/installing-and-using-themes.md

@@ -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.

docs/content/documentation/themes/overview.md

@@ -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.
+

docs/content/documentation/themes/themes-list.md

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