Browse Source

Merge pull request #278 from andradei/master

Fix documentation typos and minor changes:
index-subcmd
Vincent Prouillet GitHub 6 years ago
parent
commit
9d2f6f0b23
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 51 additions and 53 deletions
  1. +1
    -1
      docs/content/documentation/content/overview.md
  2. +11
    -13
      docs/content/documentation/content/section.md
  3. +28
    -28
      docs/content/documentation/getting-started/configuration.md
  4. +9
    -9
      docs/content/documentation/getting-started/directory-structure.md
  5. +2
    -2
      docs/content/documentation/themes/creating-a-theme.md

+ 1
- 1
docs/content/documentation/content/overview.md 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).

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.



+ 11
- 13
docs/content/documentation/content/section.md View File

@@ -3,12 +3,10 @@ title = "Section"
weight = 20
+++

A section is automatically created when a folder is found
in the `content` section, unless it only contains a `index.md` file and is actually
a page with assets.
A section is automatically created when a folder is found in the `content` section, unless it only
contains a `index.md` file and is actually a page with assets.

You can add `_index.md` file to a folder to augment a section and give it
some metadata and/or content.
You can add `_index.md` file to a folder to augment a section and give it some metadata and/or content.

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

@@ -33,17 +31,17 @@ description = ""
sort_by = "none"

# Used by the parent section to order its subsections.
# Higher values means it will be at the end.
# Lower values have priority.
weight = 0

# Template to use to render this section page
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
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
paginate_path = "page"

@@ -56,7 +54,7 @@ insert_anchor_links = "none"
# `build_search_index` is set to true in the config
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
# to be used directly
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
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`.

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

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.

### `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.


+ 28
- 28
docs/content/documentation/getting-started/configuration.md View File

@@ -56,7 +56,7 @@ compile_sass = false
build_search_index = false

# 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.
# Example:
# ignored_content = ["*.{graphml,xlsx}", "temp.*"]
@@ -74,34 +74,34 @@ ignored_content = []

Gutenberg currently has the following highlight themes available:

- 1337: https://tmtheme-editor.herokuapp.com/#!/editor/theme/1337
- agola-dark: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Agola%20Dark
- ascetic-white: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Ascetic%20White
- axar: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Axar
- [1337](https://tmtheme-editor.herokuapp.com/#!/editor/theme/1337)
- [agola-dark](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Agola%20Dark)
- [ascetic-white](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Ascetic%20White)
- [axar](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Axar)
- base16-ocean-dark
- base16-ocean-light
- bbedit: https://tmtheme-editor.herokuapp.com/#!/editor/theme/BBEdit
- boron: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Boron
- charcoal: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Charcoal
- cheerfully-light: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Cheerfully%20Light
- classic-modified: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Classic%20Modified
- demain: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Demain
- dimmed-fluid: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Dimmed%20Fluid
- gray-matter-dark: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Gray%20Matter%20Dark
- gruvbox-dark: https://github.com/morhetz/gruvbox
- gruvbox-light: https://github.com/morhetz/gruvbox
- idle: https://tmtheme-editor.herokuapp.com/#!/editor/theme/IDLE
- inspired-github: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Inspiredgithub
- ir-white: https://tmtheme-editor.herokuapp.com/#!/editor/theme/IR_White
- kronuz: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Kronuz
- material-dark: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Material%20Dark
- material-light: https://github.com/morhetz/gruvbox
- monokai: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Monokai
- solarized-dark: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Solarized%20(dark)
- solarized-light: https://tmtheme-editor.herokuapp.com/#!/editor/theme/Solarized%20(light)
- subway-madrid: 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
- base16-ocean-light
- [bbedit](https://tmtheme-editor.herokuapp.com/#!/editor/theme/BBEdit)
- [boron](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Boron)
- [charcoal](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Charcoal)
- [cheerfully-light](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Cheerfully%20Light)
- [classic-modified](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Classic%20Modified)
- [demain](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Demain)
- [dimmed-fluid](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Dimmed%20Fluid)
- [gray-matter-dark](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Gray%20Matter%20Dark)
- [gruvbox-dark](https://github.com/morhetz/gruvbox)
- [gruvbox-light](https://github.com/morhetz/gruvbox)
- [idle](https://tmtheme-editor.herokuapp.com/#!/editor/theme/IDLE)
- [inspired-github](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Inspiredgithub)
- [ir-white](https://tmtheme-editor.herokuapp.com/#!/editor/theme/IR_White)
- [kronuz](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Kronuz)
- [material-dark](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Material%20Dark)
- [material-light](https://github.com/morhetz/gruvbox)
- [monokai](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Monokai)
- [solarized-dark](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Solarized%20(dark))
- [solarized-light](https://tmtheme-editor.herokuapp.com/#!/editor/theme/Solarized%20(light))
- [subway-madrid](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)

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

+ 9
- 9
docs/content/documentation/getting-started/directory-structure.md 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`.

## `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).

## `content`
Where all your markup content lies: this will most likely be mostly `.md` files.
Each folder in the `content` directory represents a [section](./documentation/content/section.md)
that contains [pages](./documentation/content/page.md) : your `.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)
that contains [pages](./documentation/content/page.md) : your `.md` files.

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.

## `templates`
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
and the variables available.
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 about default templates
and available variables.

## `themes`
Contains themes that can be used for that site. If you are not planning to use themes, you can safely ignore
this folder and let it be. If you want to learn about themes, head to the [themes documentation](./documentation/themes/_index.md).
Contains themes that can be used for that site. If you are not planning to use themes, leave this folder empty.
If you want to learn about themes, head to the [themes documentation](./documentation/themes/_index.md).

+ 2
- 2
docs/content/documentation/themes/creating-a-theme.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
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.

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

## Submitting a theme to the gallery


Loading…
Cancel
Save