From 486c979761539c9bc977df1f0f6821e42937113a Mon Sep 17 00:00:00 2001 From: Isaac Andrade Date: Sun, 1 Apr 2018 18:33:59 -0600 Subject: [PATCH 1/2] 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 --- .../content/documentation/content/overview.md | 2 +- docs/content/documentation/content/section.md | 24 ++++---- .../getting-started/configuration.md | 56 +++++++++---------- .../getting-started/directory-structure.md | 18 +++--- .../documentation/themes/creating-a-theme.md | 4 +- 5 files changed, 51 insertions(+), 53 deletions(-) diff --git a/docs/content/documentation/content/overview.md b/docs/content/documentation/content/overview.md index 7aa69075..c5eac346 100644 --- a/docs/content/documentation/content/overview.md +++ b/docs/content/documentation/content/overview.md @@ -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. diff --git a/docs/content/documentation/content/section.md b/docs/content/documentation/content/section.md index 7ec9ac7e..397c661a 100644 --- a/docs/content/documentation/content/section.md +++ b/docs/content/documentation/content/section.md @@ -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 actuallya 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. diff --git a/docs/content/documentation/getting-started/configuration.md b/docs/content/documentation/getting-started/configuration.md index 58df27ad..0cf21b79 100644 --- a/docs/content/documentation/getting-started/configuration.md +++ b/docs/content/documentation/getting-started/configuration.md @@ -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). diff --git a/docs/content/documentation/getting-started/directory-structure.md b/docs/content/documentation/getting-started/directory-structure.md index 33006da1..69c499f6 100644 --- a/docs/content/documentation/getting-started/directory-structure.md +++ b/docs/content/documentation/getting-started/directory-structure.md @@ -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). diff --git a/docs/content/documentation/themes/creating-a-theme.md b/docs/content/documentation/themes/creating-a-theme.md index 0ba63402..793fe796 100644 --- a/docs/content/documentation/themes/creating-a-theme.md +++ b/docs/content/documentation/themes/creating-a-theme.md @@ -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 From f9186118a08207d885179ac36c68b296089e4e8b Mon Sep 17 00:00:00 2001 From: Isaac Andrade Date: Tue, 3 Apr 2018 10:24:53 -0600 Subject: [PATCH 2/2] Fix typo. --- docs/content/documentation/content/section.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/documentation/content/section.md b/docs/content/documentation/content/section.md index 397c661a..2228544d 100644 --- a/docs/content/documentation/content/section.md +++ b/docs/content/documentation/content/section.md @@ -4,7 +4,7 @@ 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 actuallya page with assets. +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.