Edit docs to say that sections require an _index.md file (#341)

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** ad `[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,

docs/content/documentation/content/section.md

@@ -3,19 +3,28 @@ title = "Section"
 weight = 20
 +++
 
-A section is automatically created when a folder is found in the `content` section, unless it only
+A section is created whenever a folder (or subfolder) in the `content` section contains an 
-contains a `index.md` file and is actually a page with assets.
+`_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 (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.
-The index page is actually a section created automatically like any other: you can add metadata
+If you do not create an `_index.md` file in your content directory, this main content section will
-and content by adding `_index.md` at the root of the `content` folder.
+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: