Update docs for removal of order

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
-
-# The weight as defined in the Section page
-weight = 0
+# An overarching category name for that page, allowing you to group pages with it
+category = ""
 
-# 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 <code>&lt;!-- more --&gt;</code> 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:
 `<a href="{{ page.permalink }}#continue-reading">Continue Reading</a>`

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:
+
+```j2
+{% for post in section.pages %}
+  <h1><a href="{{ post.permalink }}">{{ post.title }}</a></h1>
+{% endfor %}
+```
 
-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.
+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.
 
-If several pages have the same date/weight/order, their permalink will be used to break the tie following
-an alphabetical order.
+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.
 
-### `date`
-This will sort all pages by their `date` field, from the most recent to the oldest.
+If several pages have the same date/weight/order, their permalink will be used
+to break the tie following an alphabetical order.
 
-### `weight`
-This will be sort all pages by their `weight` field. Heavier weights fall at the bottom: 5 would be before 10.
+## Sorting Pages
+The `sort_by` front-matter variable can have the following values:
 
-### `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.
+### `date`
+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, 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.
+
+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.