Contextual Sections

A document is comprised of sections within it. However, before being processed by the templating engine, several sections are appended to the document. This is where most of the template sections will be added.

The sections are added based on the document’s position in the folder structure – by its path.

Each folder can gave one document called _settings.md. This is a document like any other, with sections and meta.

When a document is requested, the templating engine walks up the folder tree from where it’s positioned and collects all the _settings.md documents back to the root path. It adds these to the bottom of the document that was requested, in order from “closest” to the document (for example, in the same directory) to “furthest” from the document (from the root directory).

Based on the above rules, the _settings.md document in the root well be added to the very end of all requested documents. This document is where many of the default templates are located – things like _template and _template:*, as well as other common design elements: _template:list, _template:code, _template:aside, etc.

Given the prior templating rules which dictate that the engine uses the first matching template it finds, this means that when looking for a template, the engine will find them in this order:

• A matching template in the document itself
• A matching template added from a _settings.md file in the same folder
• A matching template added from a _settings.md file in any of the folders between the requested document and the root folder
• A matching template added from the _settings.md file in the root directory

The same is true of metadata. Since the sections are added to the bottom of the document, any request to doc.Meta.Get<T>() will return the first meta it finds. This might come from the document itself, or from any of the sections added from context.

Example

Consider the following directory structure leading to the target document:

/foo/bar/document.md

Assume the following:

• The document contains FIVE sections
• The bar directory contains a _settings.md document which adds THREE more sections to the bottom
• The foo directory has no _settings.md document
• The root directory contains a _settings.md document which adds NINE more sections to the bottom

The resulting document that’s processed by the templating engine has 17 sections:

• 5 from the actual document, then…
• 3 from the bar settings, then…
• 9 from the root settings

Remember that template and metadata searching goes from the top down, so templates or meta from the document itself will take precedence over templates or meta from foo, and they will both take precedence over templates or meta from the root.

It’s common for a document to end up with a couple of dozen “template sections,” of which it only uses 2-3 for templating, depending on what “editorial sections” are present. Since the template sections are hidden (they start with an underscore), anything not used is ignored.