From c2d4561f052624d4e1d6df4c892090a354473f06 Mon Sep 17 00:00:00 2001 From: Daniel Sockwell Date: Fri, 20 Jul 2018 03:16:57 -0400 Subject: [PATCH] Edit docs to say that sections require an `_index.md` file (#341) --- docs/content/documentation/content/page.md | 16 ++++++++++++++ docs/content/documentation/content/section.md | 21 +++++++++++++------ 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/docs/content/documentation/content/page.md b/docs/content/documentation/content/page.md index 3e6b8df6..048d5c6f 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** 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, diff --git a/docs/content/documentation/content/section.md b/docs/content/documentation/content/section.md index 2228544d..19ea0c46 100644 --- a/docs/content/documentation/content/section.md +++ b/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 -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: