From bedf469d16f313f020f952d5983414f08d186fe5 Mon Sep 17 00:00:00 2001 From: Daniel Sockwell Date: Sun, 29 Jul 2018 15:54:36 -0400 Subject: [PATCH] Update docs for removal of order --- docs/content/documentation/content/page.md | 58 +++++++----- docs/content/documentation/content/section.md | 92 +++++++++++++++---- 2 files changed, 109 insertions(+), 41 deletions(-) diff --git a/docs/content/documentation/content/page.md b/docs/content/documentation/content/page.md index 04cb6c23..08105242 100644 --- a/docs/content/documentation/content/page.md +++ b/docs/content/documentation/content/page.md @@ -6,6 +6,22 @@ weight = 30 A page is any file ending with `.md` in the `content` directory, except files named `_index.md`. +If a file ending with `.md` is named `index.md`, then it will generate a page +with the name of the containing folder (for example, `/content/about/index.md` would +create a page at `[base_url]/about`). (Note the lack of an underscore; if the file +were named `_index.md`, then it would create a **section** at `[base_url]/about`, as +discussed in the prior part of this documentation. But naming the file `index.md` will +create a **page** at `[base_url]/about`). + +If the file is given any name *other* than `index.md` or `_index.md`, then it will +create a page with that name (without the `.md`). So naming a file in the root of your +content directory `about.md` would also create a page at `[base_url]/about`. + +As you can see, creating an `about.md` file is exactly equivalent to creating an +`about/index.md` file. The only difference between the two methods is that creating +the `about` folder allows you to use asset colocation, as discussed in the +[Overview](./documentation/content/overview.md) section of this documentation. + ## Front-matter The front-matter is a set of metadata embedded in a file. In Gutenberg, @@ -13,7 +29,8 @@ it is at the beginning of the file, surrounded by `+++` and uses TOML. While none of the front-matter variables are mandatory, the opening and closing `+++` are required. -Here is an example page with all the variables available: +Here is an example page with all the variables available. The values provided below are the default +values. ```md +++ @@ -22,8 +39,15 @@ description = "" # The date of the post. # 2 formats are allowed: YYYY-MM-DD (2012-10-02) and RFC3339 (2002-10-02T15:00:00Z) -# Do not wrap dates in quotes, the line below only indicates that there is no default date -date = +# Do not wrap dates in quotes, the line below only indicates that there is no default date. +# If the section variable `sort_by` is set to `date`, then any page that lacks a `date` +# will not be rendered. +date = + +# The weight as defined in the Section page +# If the section variable `sort_by` is set to `weight`, then any page that lacks a `weight` +# will not be rendered. +weight = 0 # A draft page will not be present in prev/next pagination draft = false @@ -38,28 +62,18 @@ slug = "" # It should not start with a `/` and the slash will be removed if it does path = "" -# A dict of taxonomies: the key is the name of the taxonomy which must match -# one of the taxonomy defined in `config.toml` and the value is a list of -# strings -[taxonomies] +# An array of strings allowing you to group pages with them +tags = [] -# The order as defined in the Section page -order = 0 +# An overarching category name for that page, allowing you to group pages with it +category = "" -# The weight as defined in the Section page -weight = 0 - -# Use aliases if you are moving content but want to redirect previous URLs to the -# current one. Each element in the array of aliases may take one of two forms: -# * "some/alias/path", which will generate "some/alias/path/index.html" -# * "some/alias/path.html", which will generate "some/alias/path.html" -# -# The former is useful if your previous site had the form "example.com/some/alias/path", -# the latter is useful if your previous site had the form "example.com/some/alias/path.html" +# Use aliases if you are moving content but want to redirect previous URLs to the +# current one. This takes an array of path, not URLs. aliases = [] # Whether the page should be in the search index. This is only used if -# `build_search_index` is set to true in the config and the parent section +# `build_search_index` is set to true in the config and the parent section # hasn't set `in_search_index` to false in its front-matter in_search_index = true @@ -75,7 +89,7 @@ Some content ## Summary -You can ask Gutenberg to create a summary if you only want to show the first +You can ask Gutenberg to create a summary if you only want to show the first paragraph of each page in a list for example. To do so, add <!-- more --> in your content at the point @@ -83,6 +97,6 @@ where you want the summary to end and the content up to that point will be also available separately in the [template](./documentation/templates/pages-sections.md#page-variables). -An anchor link to this position named `continue-reading` is created so you can link +An anchor link to this position named `continue-reading` is created so you can link directly to it if needed for example: `Continue Reading` diff --git a/docs/content/documentation/content/section.md b/docs/content/documentation/content/section.md index 2228544d..7baba791 100644 --- a/docs/content/documentation/content/section.md +++ b/docs/content/documentation/content/section.md @@ -3,22 +3,32 @@ 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 created whenever a folder (or subfolder) in the `content` section contains an +`_index.md` file. If a folder does not contain an `_index.md` file, no section will be +created, but markdown files within that folder will still create pages (known as orphan pages). -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. +The index page (i.e., the page displayed when a user browses to your `base_url`) is a section, +which is created whether or not you add an `_index.md` file at the root of your `content` folder. +If you do not create an `_index.md` file in your content directory, this main content section will +not have any content or metadata. If you would like to add content or metadata, you can add an +`_index.md` file at the root of the `content` folder and edit it just as you would edit any other +`_index.md` file; your `index.html` template will then have access to that content and metadata. ## Front-matter +The `_index.md` file within a folder defines the content and metadata for that section. To set +the metadata, add front matter to the file. + 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. +After the closing `+++`, you can add content that will be parsed as markdown and will be available +to your templates through the `section.content` variable. + 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. The values provided below are the +default values. ```md @@ -27,7 +37,7 @@ title = "" description = "" -# Whether to sort by "date", "order", "weight" or "none". More on that below +# Whether to sort pages by "date", "weight", or "none". More on that below sort_by = "none" # Used by the parent section to order its subsections. @@ -83,22 +93,66 @@ You can also change the pagination path (the word displayed while paginated in t 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 -is enabled by setting the `sort_by` front-matter variable. +It is very common for Gutenberg templates to iterate over pages or sections +to display all pages/sections a given directory. Consider a very simple +example: a `blog` directory with three files: `blog/Post_1.md`, +`blog/Post_2.md`, and `blog/Post_3.md`. To iterate over these posts and +create a list of links to the posts, a simple template might look like this: -Any page that cannot be sorted, for example if missing the date variable while sorting by `date`, will be ignored and -won't be rendered. The terminal will warn you if this is happening. +```j2 +{% for post in section.pages %} +

{{ post.title }}

+{% endfor %} +``` -If several pages have the same date/weight/order, their permalink will be used to break the tie following -an alphabetical order. +This would iterate over the posts, and would do so in a specific order +based on the `sort_by` variable set in the `_index.md` page for the +containing section. The `sort_by` variable can be given three values: `date`, +`weight`, and `none`. If no `sort_by` method is set, the pages will be +sorted in the `none` order, which is not intended to be used for sorted content. + +Any page that is missing the data it needs to be sorted will be ignored and +won't be rendered. For example, if a page is missing the date variable the +containing section sets `sort_by = "date"`, then that page will be ignored. +The terminal will warn you if this is happening. + +If several pages have the same date/weight/order, their permalink will be used +to break the tie following an alphabetical order. + +## Sorting Pages +The `sort_by` front-matter variable can have the following values: ### `date` -This will sort all pages by their `date` field, from the most recent to the oldest. +This will sort all pages by their `date` field, from the most recent (at the +top of the list) to the oldest (at the bottom of the list). Each page will +get `page.earlier` and `page.later` variables that contain the pages with +earlier and later dates, respectively. ### `weight` -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, from lightest weight +(at the top of the list) to heaviest (at the bottom of the list). Each +page gets `page.lighter` and `page.heavier` variables that contain the +pages with lighter and heavier weights, respectively. -### `order` -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. +When iterating through pages, you may wish to use the Tera `reverse` filter, +which reverses the order of the pages. Thus, after using the `reverse` filter, +pages sorted by weight will be sorted from lightest (at the top) to heaviest +(at the bottom); pages sorted by date will be sorted from oldest (at the top) +to newest (at the bottom). +`reverse` has no effect on `page.later`/`page.earlier`/`page.heavier`/`page.lighter`. + +## Sorting Subsections +Sorting sections is a bit less flexible: sections are always sorted by `weight`, +and do not have any variables that point to the next heavier/lighter sections. + +Based on this, by default the lightest (lowest `weight`) subsections will be at +the top of the list and the heaviest (highest `weight`) will be at the top; +the `reverse` filter reverses this order. + +**Note**: Unlike pages, permalinks will **not** be used to break ties between +equally weighted sections. Thus, if the `weight` variable for your section is not set (or if it +is set in a way that produces ties), then your sections will be sorted in +**random** order. Moreover, that order is determined at build time and will +change with each site rebuild. Thus, if there is any chance that you will +iterate over your sections, you should always assign them weight.