From 57b87aa50adc5ee9611dc4e6b9ca283c29a44010 Mon Sep 17 00:00:00 2001 From: Vincent Prouillet Date: Sun, 1 Oct 2017 12:51:43 +0900 Subject: [PATCH] Add more docs pages --- CHANGELOG.md | 1 + components/front_matter/src/section.rs | 1 - components/site/src/lib.rs | 1 + components/taxonomies/src/lib.rs | 2 +- docs/content/documentation/content/linking.md | 2 +- docs/content/documentation/content/section.md | 1 - .../documentation/templates/pages-sections.md | 10 ++-- .../documentation/templates/pagination.md | 28 ++++++++++ .../content/documentation/templates/robots.md | 14 +++++ docs/content/documentation/templates/rss.md | 16 ++++++ .../documentation/templates/sitemap.md | 23 ++++++++ .../templates/tags-categories.md | 30 +++++++++++ .../documentation/themes/creating-a-theme.md | 53 +++++++++++++++++++ .../themes/installing-and-using-themes.md | 52 ++++++++++++++++++ docs/content/documentation/themes/overview.md | 10 ++++ .../documentation/themes/themes-list.md | 8 +++ 16 files changed, 243 insertions(+), 9 deletions(-) create mode 100644 docs/content/documentation/templates/pagination.md create mode 100644 docs/content/documentation/templates/robots.md create mode 100644 docs/content/documentation/templates/rss.md create mode 100644 docs/content/documentation/templates/sitemap.md create mode 100644 docs/content/documentation/templates/tags-categories.md create mode 100644 docs/content/documentation/themes/creating-a-theme.md create mode 100644 docs/content/documentation/themes/installing-and-using-themes.md create mode 100644 docs/content/documentation/themes/overview.md create mode 100644 docs/content/documentation/themes/themes-list.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 276695ed..22f97043 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/components/front_matter/src/section.rs b/components/front_matter/src/section.rs index 72f8e964..096e0140 100644 --- a/components/front_matter/src/section.rs +++ b/components/front_matter/src/section.rs @@ -35,7 +35,6 @@ pub struct SectionFrontMatter { pub paginate_path: Option, /// 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, /// Whether to render that section or not. Defaults to `true`. /// Useful when the section is only there to organize things but is not meant diff --git a/components/site/src/lib.rs b/components/site/src/lib.rs index f87c4ec8..fa1ea54e 100644 --- a/components/site/src/lib.rs +++ b/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())?; diff --git a/components/taxonomies/src/lib.rs b/components/taxonomies/src/lib.rs index ec8287fa..d942e710 100644 --- a/components/taxonomies/src/lib.rs +++ b/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 diff --git a/docs/content/documentation/content/linking.md b/docs/content/documentation/content/linking.md index afc78813..92980874 100644 --- a/docs/content/documentation/content/linking.md +++ b/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 diff --git a/docs/content/documentation/content/section.md b/docs/content/documentation/content/section.md index c789c44a..1b1f97d8 100644 --- a/docs/content/documentation/content/section.md +++ b/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" diff --git a/docs/content/documentation/templates/pages-sections.md b/docs/content/documentation/templates/pages-sections.md index 54a2b17f..a6aa1ae3 100644 --- a/docs/content/documentation/templates/pages-sections.md +++ b/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
; ``` diff --git a/docs/content/documentation/templates/pagination.md b/docs/content/documentation/templates/pagination.md new file mode 100644 index 00000000..cf782ee9 --- /dev/null +++ b/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; +// All pagers for this section, but with their `pages` attribute set to an empty array +pagers: Array; +// Which page are we on +current_index: Number; +``` diff --git a/docs/content/documentation/templates/robots.md b/docs/content/documentation/templates/robots.md new file mode 100644 index 00000000..8cc5855a --- /dev/null +++ b/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: * +``` diff --git a/docs/content/documentation/templates/rss.md b/docs/content/documentation/templates/rss.md new file mode 100644 index 00000000..f1c8d0b3 --- /dev/null +++ b/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. diff --git a/docs/content/documentation/templates/sitemap.md b/docs/content/documentation/templates/sitemap.md new file mode 100644 index 00000000..a63f3f6e --- /dev/null +++ b/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?; +``` diff --git a/docs/content/documentation/templates/tags-categories.md b/docs/content/documentation/templates/tags-categories.md new file mode 100644 index 00000000..bdd24986 --- /dev/null +++ b/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; +``` + +Currently, there is no way to define different taxonomy templates per section, change +the path used for them or paginate them. + diff --git a/docs/content/documentation/themes/creating-a-theme.md b/docs/content/documentation/themes/creating-a-theme.md new file mode 100644 index 00000000..607481a4 --- /dev/null +++ b/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). diff --git a/docs/content/documentation/themes/installing-and-using-themes.md b/docs/content/documentation/themes/installing-and-using-themes.md new file mode 100644 index 00000000..66b1d9a2 --- /dev/null +++ b/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. diff --git a/docs/content/documentation/themes/overview.md b/docs/content/documentation/themes/overview.md new file mode 100644 index 00000000..982f515d --- /dev/null +++ b/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. + diff --git a/docs/content/documentation/themes/themes-list.md b/docs/content/documentation/themes/themes-list.md new file mode 100644 index 00000000..4e9299f6 --- /dev/null +++ b/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)