Layouts
Handlebars layouts for Pattern Dump sites: what a layout template receives, every page key Pattern Dump fills, regions, the table of contents and tag pages.
{
"type": "object",
"required": ["title"],
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"page": {
"type": "object",
"properties": {
"next": {},
"date": {},
"tags": {}
}
}
}
}
A layout is a component that renders a site page. Its schema says what a page may set and which of Pattern Dump's page data it wants, as the starter's layouts/page above: a title, a description, and the next page, the date and the tags. Sites explains the idea; Frontmatter has the checks on what a page sets.
What is a layout
A layout is a base component directly under layouts/, named by its folder (layouts/<name>), or a component in pages/ or templates/ (numbers in front of the folder are ignored, so 04-templates counts) whose schema has "x-pd-layout": "<name>" at its root. A variant is never a layout.
x-pd-layout- A layout name: lowercase letters, digits and hyphens, with no hyphen at either end or two in a row. Else:
x-pd-layout must be a layout name: lowercase letters, digits and hyphens, such as "article" (got …). - Outside
pages/andtemplates/it makes no layout, and is a problem on the component:x-pd-layout makes a page or template pattern a layout; <id> is in neither pages/ nor templates/, so it is no layout: move it there, or include it in one that is. - On a component in
layouts/:<id> is the layout "<folder>" by its folder, and x-pd-layout would give it a second name ("<x>"): remove x-pd-layout. The folder's name stands.
One name for two layouts makes neither a layout: layout "<n>" is set twice: <file> (x-pd-layout) and <file> (a layouts/ folder): rename one, on both components and on every page that asks for it.
The skin's components
layouts/page- The default layout, for a page that names none and takes none from a folder.
partials/base- Declares
site: whatsite.globalsin the config may hold. partials/head- Optional. Adds to every page's
<head>. See The page document. components/toc- The table of contents.
What a layout gets
A layout's template gets every key its schema declares, null where the page sets none; the page's markdown as body; nav, the navigation; site; and page, only when its schema declares page.
body- The page's rendered markdown, or in the property the schema's root
x-pd-contentnames. That property must be a declared string with"contentMediaType": "text/markdown"; else the page fails,layout "<n>" puts the page's markdown into "<p>" (x-pd-content), which it does not declare(or…, which must be a string with "contentMediaType": "text/markdown"), and the markdown goes intobody. nav- The navigation, one level deep, with
current: trueon every entry whose route is the page's. Navigation and routes has its shape. site- The values of
site.globals, checked againstpartials/base's schema, withnavigationswhenpartials/baselists any,categorieswhen it lists them, andcollections, deprecated, when listed. page- Pattern Dump's data for the page, below.
Page data
Pattern Dump fills exactly these sub-keys of page, and each query the layout declares. A layout gets only the ones it declares, each null when there is nothing to fill. Any other: <layout> declares "page.<k>", which Pattern Dump does not fill (it fills page.headings, …, page.regions). There is no page.toc, page.related, page.pages or page.progress; in the starter's skins, related and pages are query names.
page.headings- Every heading of the page,
{ level, text, anchor }. The anchor is a GitHub-style slug, with-1,-2added for repeats. - A heading whose anchor is already an id on the page, the layout's or a symbol image's, gets the next free number, with a note:
<page>: heading "<t>" is #<new>, because the layout uses id="<old>"(orbecause a symbol image on the page uses id="<old>",because the symbol set "<set>" on the page uses id="<old>"). A layout that builds ids frompage.headingsgets… even after the suffix: the layout must not make ids from page.headings. page.section- The top-level navigation entry of the page's first path segment,
{ route, title }. A top-level page, and Home, is its own section;nullwhen no entry holds the page. page.breadcrumbs- Home, then each folder above the page by its
index.md,{ route, title }: from the folders, so deeper than the navigation. The page itself is left out; empty on Home. page.prev,page.next- The neighbours in the navigation, read depth first (an entry, then its children), across sections.
nullat the ends and for a page that isn't in the navigation. page.created- The author date of the page's first commit in git (ISO 8601), following renames back to when it was added.
null, with a note, when git doesn't know the page. Inpd buildfrom a shallow clone, it fails a page whose layout declares it. page.date- The page's
date, else the day of its first commit (YYYY-MM-DD), elsenull;nullon the 404 page. page.updated- The page's
updated, elsenull. Never from git. page.tags,page.categories{ key, label, description, route }each, in the page's order;[]without. An undeclared tag's label is its key, androuteis its tag or category page, ornull.page.term,page.terms- On a tag or category page, the term,
{ key, label, description, route, count }; on the index, every term with a page, by label.nullelsewhere. page.children,page.listing- A folder's pages, as data and through a view. Collections and queries has both.
page.regions{ <region>: html | null }for each region the layout declares.
page.modified is retired: <layout> declares "page.modified", which Pattern Dump no longer fills: git's last commit counts a typo fix as a change. Declare "page.updated" instead: …. Neither is there a guide-progress or pager feature beyond page.prev and page.next.
Sample data
A layout's sample data, and that of every component it includes at any depth (except a card), may set only the keys the layout declares, plus body, nav, site, and page when declared. Else: the sample data of <id> (<file>) sets "<key>", which <layout> does not declare, so it would show on every page using that layout.
Inside page, only declared sub-keys, and only fields of Pattern Dump's shape, at any depth: … sets "page.prev.extra", which is not part of the page data Pattern Dump fills …. Inside site, only keys partials/base declares, and only listed navigation and collection names. A card is checked against a listing's page fields instead: … sets "<key>", which is not a field of a page in a listing, so it would show on every card of <layout>. A variant's sample data is not checked.
Errors in a layout
- A template that throws
- Fails the page with
<page>: <error>, status 500, never an unhandled error. - A field named like a helper
- Fails the page with the workbench's
SCHEMA_INVALIDmessage. - Tags written as text
- Since 0.5.0 a tag is an object, and a template that writes one as text fails the page:
<id> (<file>:<line>): {{#each <list>}} writes {{<item>}}, but a tag is an object since 0.5.0 (key, label, description, route): write {{label}} to show it ({{key}} is its URL segment, {{route}} its page). A schema that declares tags as strings:… declares tags as a list of strings, but a tag is an object since 0.5.0 ….
Regions
A layout declares regions on page.properties.regions, with "x-pd-regions": [<names>] and, optionally, "x-pd-toc": true; only those keys and description are allowed. A name is lowercase letters, digits and hyphens, starting with a letter; header, footer, nav and main are the layout's own.
A component placed on a page goes into a region by region="<name>" on its root pd- tag, else by its schema's root "x-pd-region"; the tag wins. In a region, components keep their order on the page. With regions declared, the <body> gets data-pd-regions="<filled names>", empty when none is filled.
- A reserved name
<id> (page.regions): header is reserved for the layout's own landmark: …- A name that isn't one
"<n>" is not a region name: lowercase letters, digits and hyphens, starting with a letter. Listed twice:"<n>" is listed twice.x-pd-tocthat isn't a boolean:"x-pd-toc" is true or false.region=without a value<pd-…>: region names a region of the layout, such as region="sidebar". On a component that declares aregionproperty:… region="..." is Pattern Dump's …: rename that property to place it in a region.- A region this layout doesn't have
- Left out without a word when another layout of the skin has it; the component is still checked. A region no layout has:
region "<n>" is no layout's region: did you mean "<x>"? (the skin's regions are …). A reserved one:the <n> belongs to the layout, so no component goes into it (<layout> offers "…"). - A landmark in a region
- A region's content may not bring a
<main>orrole="main", nor a<header>or<footer>outsidearticle,aside,navorsection, norrole="banner"orrole="contentinfo".
Table of contents
The table of contents is the skin's components/toc, rendered with items: [{ text, href, level }], from the page's h2 and h3 headings. toc: true on a page, or x-pd-toc on a layout's regions, puts it first in its region; a page's toc: false wins over the layout. A page without h2 or h3 gets none, and the 404 page never does.
A components/toc whose schema names no x-pd-region: <what>: components/toc names no region (x-pd-region at its schema's root), so the table of contents has no place on the page. No components/toc at all, or one whose schema has no items, is a problem too. <pd-toc> places one by hand: see Markdown.
Tag and category layouts
Pattern Dump generates a page for each tag a published page uses at /tags/<key>/, with the layout tag, and their index at /tags/ with tags when there is at least one tag; likewise /categories/<key>/ with category and /categories/ with categories. Each is generated only when the skin has its layout.
site.tagPages,site.categoryPages- Left out: on when the skin has the term's layout (the index only with the index's layout too), and nothing said otherwise.
false: off.trueor{ path, title }: on, withpathfor the URL segment andtitlefor the index's title (default "Tags", "Categories"); a missing layout is then a problem:site.tagPages asks for tag pages, but the skin has no layout "tags" (the index of the tags): add layouts/tags, or mark a page or template pattern with "x-pd-layout": "tags", or set tagPages to false, and likewise for the others.
A generated page's layout must declare title, which gets the term's label or the index's title: <layoutId>: a tag page's title is the tag's label, so the layout declares "title". description is passed only when the term has one and the layout declares it.
Term pages come from published pages only, no drafts or scheduled pages, in pd dev too, and list every page with the term: there is no pagination. Terms are sorted by label, then key. An old key with a page forwards: /tags/<old>/ is a redirect to /tags/<key>/. Generated pages are in /api/pages and the sitemap, not in the navigation, a listing or the search index, and take no folder defaults.
- A page file at a generated route
<file> is the page at <route>, which is <what> as well: rename <top>, or give the <kind> pages another path (site.<kind>Pages: { path: "..." }). AredirectFromthat claims one:<file>: redirectFrom "<route>" is <what>: a route can't both be a page and forward to one.
The page document
<title><title> · <site.title>, or the title alone when the two are equal or there is no site title. The page's title is its layout'stitlewhen declared and text, else its route; "Page not found" on the 404 page.<meta name="description">- The layout's
description, only when declared. <html lang>site.lang, defaulten, on every page, the 404 page and redirect pages. A document listing a page's problems is alwaysen.
The <head> holds, in order: the title, the description, the SEO tags, JSON-LD (with site.url, not on the 404 page), /_pd/code.css on a page that shows code, partials/head, site.head, the stylesheets (the base layer, assets.css, the layout's and its components'), and the module scripts (globalScripts, then the scripts the layout and the placed components ask for, each once). There are no theme stylesheets. Every page carries <meta name="pd-base-path" content="<base>">, / at a host's root.
partials/head is rendered with { site, body: null, nav: null }. It may hold only meta, link, script, style and noscript, and never <title>, <base>, a canonical link, a description, robots or twitter:* meta, og:* or JSON-LD: partials/head: <x> is written by Pattern Dump on every page; a head partial must not write it, or <tag> does not belong in <head>: …. Text is refused. Its problems and its sample data are problems of the whole site, and a render error fails every page.
Landmarks
A page has exactly one main landmark and one <h1>: the page has no <main>: …, the page has <n> main landmarks (<main> or role="main"): …, the page has no <h1>: one heading names the page, the page has <n> <h1> headings: …. Warnings in pd dev, errors in pd build.
A page with problems
A page with problems is answered with status 500 and a document titled Problems · <route>, with <h1>The page <route> cannot be built</h1> and the problems in a ul.pd-problems list. In pd dev, a page's links, anchors and images are checked as warnings, warning: <page>…; in pd build, image problems fail the page, and links are checked once the whole site is built. A problem of the whole site is shown on every page and listed once by pd build.