Fix documentation typos and minor changes:

- Fix some typos
- Some small changes to documentation to make it more clear
- Change the themes list from text to links
This commit is contained in:
Isaac Andrade 2018-04-01 18:33:59 -06:00
parent 5dd42c5566
commit 486c979761
5 changed files with 51 additions and 53 deletions

View file

@ -27,7 +27,7 @@ Each page path (the part after the `base_url`, for example `blog/cli-usage/`) ca
attribute of the [page front-matter](./documentation/content/page.md#front-matter). attribute of the [page front-matter](./documentation/content/page.md#front-matter).
You might have noticed a file named `_index.md` in the example above. You might have noticed a file named `_index.md` in the example above.
This file will be used for the metadata and content of the section itself and is not considered a page. This file is used to store both metadata and content of the section itself and is not considered a page.
To make sure the terminology used in the rest of the documentation is understood, let's go over the example above. To make sure the terminology used in the rest of the documentation is understood, let's go over the example above.

View file

@ -3,12 +3,10 @@ title = "Section"
weight = 20 weight = 20
+++ +++
A section is automatically created when a folder is found A section is automatically created when a folder is found in the `content` section, unless it only
in the `content` section, unless it only contains a `index.md` file and is actually contains a `index.md` file and is actuallya page with assets.
a page with assets.
You can add `_index.md` file to a folder to augment a section and give it You can add `_index.md` file to a folder to augment a section and give it some metadata and/or content.
some metadata and/or content.
The index page is actually a section created automatically like any other: you can add metadata The index page is actually a section created automatically like any other: you can add metadata
and content by adding `_index.md` at the root of the `content` folder. and content by adding `_index.md` at the root of the `content` folder.
@ -18,7 +16,7 @@ and content by adding `_index.md` at the root of the `content` folder.
The front-matter is a set of metadata embedded in a file. In Gutenberg, The front-matter is a set of metadata embedded in a file. In Gutenberg,
it is at the beginning of the file, surrounded by `+++` and uses TOML. it is at the beginning of the file, surrounded by `+++` and uses TOML.
While none of the front-matter variables are mandatory, the the opening and closing `+++` are required. While none of the front-matter variables are mandatory, the opening and closing `+++` are required.
Here is an example `_index.md` with all the variables available: Here is an example `_index.md` with all the variables available:
@ -33,17 +31,17 @@ description = ""
sort_by = "none" sort_by = "none"
# Used by the parent section to order its subsections. # Used by the parent section to order its subsections.
# Higher values means it will be at the end. # Lower values have priority.
weight = 0 weight = 0
# Template to use to render this section page # Template to use to render this section page
template = "section.html" template = "section.html"
# How many pages to be displayed per paginated page. # How many pages to be displayed per paginated page.
# No pagination will happen if this isn't set or if the value is 0 # No pagination will happen if this isn't set or if the value is 0
paginate_by = 0 paginate_by = 0
# If set, will be the path used by paginated page and the page number will be appended after it. # If set, will be the path used by paginated page and the page number will be appended after it.
# For example the default would be page/1 # For example the default would be page/1
paginate_path = "page" paginate_path = "page"
@ -56,7 +54,7 @@ insert_anchor_links = "none"
# `build_search_index` is set to true in the config # `build_search_index` is set to true in the config
in_search_index = true in_search_index = true
# Whether to render that section homepage or not. # Whether to render that section homepage or not.
# Useful when the section is only there to organize things but is not meant # Useful when the section is only there to organize things but is not meant
# to be used directly # to be used directly
render = true render = true
@ -81,11 +79,11 @@ To enable pagination for a section's pages, simply set `paginate_by` to a positi
paginate by this much. See [pagination template documentation](./documentation/templates/pagination.md) for more information paginate by this much. See [pagination template documentation](./documentation/templates/pagination.md) for more information
on what will be available in the template. on what will be available in the template.
You can also change the pagination path - the word displayed while paginated in the URL, like `page/1` - You can also change the pagination path (the word displayed while paginated in the URL, like `page/1`)
by setting the `paginate_path` variable, which defaults to `page`. by setting the `paginate_path` variable, which defaults to `page`.
## Sorting ## Sorting
Sections' pages can be sorted three different ways, not counting the unsorted default and Sections' pages can be sorted three different ways, not counting the unsorted default and
is enabled by setting the `sort_by` front-matter variable. is enabled by setting the `sort_by` front-matter variable.
Any page that cannot be sorted, for example if missing the date variable while sorting by `date`, will be ignored and Any page that cannot be sorted, for example if missing the date variable while sorting by `date`, will be ignored and
@ -101,6 +99,6 @@ This will sort all pages by their `date` field, from the most recent to the olde
This will be sort all pages by their `weight` field. Heavier weights fall at the bottom: 5 would be before 10. This will be sort all pages by their `weight` field. Heavier weights fall at the bottom: 5 would be before 10.
### `order` ### `order`
This will be sort all pages by their `order` field. Order is the opposite of weight, think of it as enumerating This will be sort all pages by their `order` field. Order is the opposite of weight, think of it as enumerating
the content: this is my first post, my second, etc. A page with `order: 5` will appear after a page with `order: 10` in the sorted list. the content: this is my first post, my second, etc. A page with `order: 5` will appear after a page with `order: 10` in the sorted list.

View file

@ -56,7 +56,7 @@ compile_sass = false
build_search_index = false build_search_index = false
# A list of glob patterns specifying asset files to ignore when # A list of glob patterns specifying asset files to ignore when
# processing the content directory. # processing the content directory.
# Defaults to none, which means all asset files are copied over to the public folder. # Defaults to none, which means all asset files are copied over to the public folder.
# Example: # Example:
# ignored_content = ["*.{graphml,xlsx}", "temp.*"] # ignored_content = ["*.{graphml,xlsx}", "temp.*"]
@ -74,34 +74,34 @@ ignored_content = []
Gutenberg currently has the following highlight themes available: Gutenberg currently has the following highlight themes available:
- 1337: https://tmtheme-editor.herokuapp.com/#!/editor/theme/1337 - [1337](https://tmtheme-editor.herokuapp.com/#!/editor/theme/1337)
- agola-dark: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Agola%20Dark - [agola-dark](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Agola%20Dark)
- ascetic-white: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Ascetic%20White - [ascetic-white](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Ascetic%20White)
- axar: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Axar - [axar](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Axar)
- base16-ocean-dark - base16-ocean-dark
- base16-ocean-light - base16-ocean-light
- bbedit: https://tmtheme-editor.herokuapp.com/#!/editor/theme/BBEdit - [bbedit](https://tmtheme-editor.herokuapp.com/#!/editor/theme/BBEdit)
- boron: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Boron - [boron](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Boron)
- charcoal: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Charcoal - [charcoal](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Charcoal)
- cheerfully-light: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Cheerfully%20Light - [cheerfully-light](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Cheerfully%20Light)
- classic-modified: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Classic%20Modified - [classic-modified](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Classic%20Modified)
- demain: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Demain - [demain](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Demain)
- dimmed-fluid: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Dimmed%20Fluid - [dimmed-fluid](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Dimmed%20Fluid)
- gray-matter-dark: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Gray%20Matter%20Dark - [gray-matter-dark](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Gray%20Matter%20Dark)
- gruvbox-dark: https://github.com/morhetz/gruvbox - [gruvbox-dark](https://github.com/morhetz/gruvbox)
- gruvbox-light: https://github.com/morhetz/gruvbox - [gruvbox-light](https://github.com/morhetz/gruvbox)
- idle: https://tmtheme-editor.herokuapp.com/#!/editor/theme/IDLE - [idle](https://tmtheme-editor.herokuapp.com/#!/editor/theme/IDLE)
- inspired-github: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Inspiredgithub - [inspired-github](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Inspiredgithub)
- ir-white: https://tmtheme-editor.herokuapp.com/#!/editor/theme/IR_White - [ir-white](https://tmtheme-editor.herokuapp.com/#!/editor/theme/IR_White)
- kronuz: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Kronuz - [kronuz](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Kronuz)
- material-dark: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Material%20Dark - [material-dark](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Material%20Dark)
- material-light: https://github.com/morhetz/gruvbox - [material-light](https://github.com/morhetz/gruvbox)
- monokai: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Monokai - [monokai](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Monokai)
- solarized-dark: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Solarized%20(dark) - [solarized-dark](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Solarized%20(dark))
- solarized-light: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Solarized%20(light) - [solarized-light](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Solarized%20(light))
- subway-madrid: https://github.com/idleberg/Subway.tmTheme - [subway-madrid](https://github.com/idleberg/Subway.tmTheme)
- subway-moscow: https://github.com/idleberg/Subway.tmTheme - [subway-moscow](https://github.com/idleberg/Subway.tmTheme)
- visual-studio-dark: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Visual%20Studio%20Dark - [visual-studio-dark](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Visual%20Studio%20Dark)
Gutenberg uses the Sublime Text themes, making it very easy to add more. Gutenberg uses the Sublime Text themes, making it very easy to add more.
If you want a theme not on that list, please open an issue or a pull request on the [Gutenberg repo](https://github.com/Keats/gutenberg). If you want a theme not on that list, please open an issue or a pull request on the [Gutenberg repo](https://github.com/Keats/gutenberg).

View file

@ -21,13 +21,13 @@ After running `gutenberg init`, you should see the following structure in your f
Here's a high level overview of each of these folders and `config.toml`. Here's a high level overview of each of these folders and `config.toml`.
## `config.toml` ## `config.toml`
A mandatory configuration file of Gutenberg in TOML format. A mandatory configuration file of Gutenberg in TOML format.
It is explained in details in the [Configuration page](./documentation/getting-started/configuration.md). It is explained in details in the [Configuration page](./documentation/getting-started/configuration.md).
## `content` ## `content`
Where all your markup content lies: this will most likely be mostly `.md` files. Where all your markup content lies: this will be mostly comprised of `.md` files.
Each folder in the `content` directory represents a [section](./documentation/content/section.md) Each folder in the `content` directory represents a [section](./documentation/content/section.md)
that contains [pages](./documentation/content/page.md) : your `.md` files. that contains [pages](./documentation/content/page.md) : your `.md` files.
To learn more, read [the content overview](./documentation/content/overview.md). To learn more, read [the content overview](./documentation/content/overview.md).
@ -40,10 +40,10 @@ The directory structure of the `sass` folder will be preserved when copying over
Contains any kind of files. All the files/folders in the `static` folder will be copied as-is in the output directory. Contains any kind of files. All the files/folders in the `static` folder will be copied as-is in the output directory.
## `templates` ## `templates`
Contains all the [Tera](https://tera.netlify.com) templates that will be used to render this site. Contains all the [Tera](https://tera.netlify.com) templates that will be used to render this site.
Have a look at the [Templates](./documentation/templates/_index.md) to learn more on the default templates Have a look at the [Templates](./documentation/templates/_index.md) to learn more about default templates
and the variables available. and available variables.
## `themes` ## `themes`
Contains themes that can be used for that site. If you are not planning to use themes, you can safely ignore Contains themes that can be used for that site. If you are not planning to use themes, leave this folder empty.
this folder and let it be. If you want to learn about themes, head to the [themes documentation](./documentation/themes/_index.md). If you want to learn about themes, head to the [themes documentation](./documentation/themes/_index.md).

View file

@ -46,12 +46,12 @@ A simple theme you can use as example is [Hyde](https://github.com/Keats/hyde).
As a theme is just a site, you can simply use `gutenberg serve` and make changes to your As a theme is just a site, you can simply use `gutenberg serve` and make changes to your
theme, with live reloading working as expected. theme, with live reloading working as expected.
Make sure to commit every directory (including `content`) in order for other people Make sure to commit every directory (including `content`) in order for other people
to be able to build the theme from your repository. to be able to build the theme from your repository.
### Caveat ### Caveat
Please note that [include paths](https://tera.netlify.com/docs/templates/#include) can only be used in used in normal templates. Please note that [include paths](https://tera.netlify.com/docs/templates/#include) can only be used in normal templates.
Theme templates should use [macros](https://tera.netlify.com/docs/templates/#macros) instead. Theme templates should use [macros](https://tera.netlify.com/docs/templates/#macros) instead.
## Submitting a theme to the gallery ## Submitting a theme to the gallery