emelie/zola
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

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

Browse source
This commit is contained in:
Daniel Sockwell 2018-07-20 03:16:57 -04:00 committed by Vincent Prouillet
parent 8a23c539c7
commit c2d4561f05
2 changed files with 31 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
docs/content/documentation/content/page.md
View file

@ -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,

21
docs/content/documentation/content/section.md
View file

@ -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: