ReferenceBuilt-in steps
layout
Wraps HTML pages in their layouts, following the layout chain.
uses: layout wraps HTML pages in their layouts: it renders the layout a page names in layout with the page's HTML
as content, then the layout named in that layout's front matter, and so on.
| Shape | map |
Default match |
**/*.html |
| Default workflow | yes, as step layout (after markdown, before write) |
What it doesLink to this heading
- Resolves
layoutlike any name of the page: its front matter, its folder data and the parent folders' data, then the site data. A folder data file (blog/blog.ymlwithlayout: post) or_data/layout.ymlcan set it for many pages. A page without alayout(or with an empty one) passes through unchanged. - Loads the layout from the includes folder (or
includes). A name without an extension is tried as is, then with.liquid, then with.html. - Renders it with the page's data and
content, the page's HTML, which{{ content }}writes as it is. Values are HTML encoded otherwise. - When the layout's front matter has a
layout, renders that one with the result ascontent, up to 32 levels. - Names resolve through the page's data and scopes first, then through the front matter of the layouts, the innermost layout first: a layout's front matter gives defaults that a page can override.
- Only the content changes; the path and data of the page do not.
Layouts apply to HTML files only: a feed or a sitemap (feed.xml.liquid) is not laid out unless the step's match
includes it.
OptionsLink to this heading
| Option | Type | Default | Meaning |
|---|---|---|---|
includes |
string | the site's includes folder | Another folder of the source folder to load layouts from |
CachingLink to this heading
A page depends on the layouts it used (and the includes and shortcodes they used) and on the names it resolved.
Editing a layout lays out again the pages that use it. The markdown section of douze.yml is part of the step's
version, since tags such as image read its defaults.
ErrorsLink to this heading
layout 'post' not found in '/_includes/' (used by '/_content/blog/a.md')
layout chain is longer than 32: base -> page -> base -> ...
These fail the page at build time.
ExampleLink to this heading
steps:
pages:
inputs: "**/*.md"
uses: frontmatter
markdown:
needs: pages
uses: markdown
layout:
needs: markdown
uses: layout
with:
includes: theme/layouts
write:
needs: layout
uses: write
---
layout: base
section: docs
---
<article data-section="{{ section }}">{{ content }}</article>
Saved as theme/layouts/page.liquid, this layout is used by pages with layout: page, and is itself wrapped in
theme/layouts/base.liquid.
RelatedLink to this heading
- Template data
- markdown, headings, write
- Guides: Layouts, Includes and shortcodes