diff --git a/CHANGELOG.md b/CHANGELOG.md index 64577c0..7fde2ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ ### Changed +- `toc` is a key the build owns now (the table of contents): a layout's schema that declares it must rename it. - **A storefront page's "last changed" date is the author's, never git's.** Git's last commit counts a typo fix or a reformat as a change, so it is no longer used for anything a reader or a search engine sees. A page sets `updated: YYYY-MM-DD` for a real change instead. What changes for an existing site: @@ -36,6 +37,17 @@ ### Added +- **Regions.** A layout declares regions besides the body on `page.regions` (`"x-pd-regions": ["sidebar"]`) and writes + each as `{{{page.regions.sidebar}}}`, null when the page puts nothing there. A placed component goes into one with + `region="sidebar"` on its tag, or its schema's `"x-pd-region"`; components keep the page's order there. A region + another layout has is left out without a message; one no layout has stops the page with a "did you mean". `` + names the filled regions (`data-pd-regions="sidebar"`), so a skin's grid can collapse an empty one. `header`, + `footer`, `nav` and `main` are the layout's own landmarks and can't be regions, and a component in a region can't + bring a main, banner or contentinfo. +- **The table of contents in a region:** the skin's `components/toc`, with `items: [{ text, href, level }]`. + `toc: true` in a page (or `x-pd-toc` on its layout) shows it with the page's headings of level 2 and 3; `toc: false` + keeps it out. `` places it in the markdown, with the derived items or a list of links of its own, whose + `#anchors` must be headings of the page. The starter has a `doc` layout with a sidebar and a `components/toc`. - **Search with Pagefind.** `pd build` indexes each page's own content (its markdown and placed components, never the layout's header, navigation or listings) and writes the index into the site at `_pd/search/`, under the site's path, with `section`, `tag` and `category` filters by label. Pagefind is the project's own diff --git a/docs/guide/storefront.md b/docs/guide/storefront.md index 5ebfd5d..380a3d5 100644 --- a/docs/guide/storefront.md +++ b/docs/guide/storefront.md @@ -212,10 +212,11 @@ lede: Three folders make a site. | `draft` | `true` shows the page in `pd dev` and leaves it out of `pd build`. See [Drafts](#drafts) | | `sort` | On a folder's `index.md` only: `date` lists the folder's pages newest first; `order`, the default, in the folder's order | | `view` | On a folder's `index.md` only: the view its listing is shown in, `views/` in the skin. See [Listing views](#listing-views) | +| `toc` | `true` shows the table of contents in its region; `false` keeps it out, whatever the layout says. See [The table of contents](#the-table-of-contents) | | any other key | Must be declared by the layout's schema | `layout`, `childLayout`, `order`, `image`, `index`, `redirectFrom`, `date`, `updated`, `tags`, `categories`, `draft`, -`sort` and `view` belong to the build: they never reach the layout as keys of their own, and a layout's schema may not declare any of +`sort`, `view` and `toc` belong to the build: they never reach the layout as keys of their own, and a layout's schema may not declare any of them (a layout shows them through `page.date`, `page.updated`, `page.tags` and `page.categories`). **The layout's schema is the frontmatter contract.** A layout is a component, and its @@ -416,6 +417,73 @@ it: a new commit is seen on restart. Two limits: - **A page moved into the pages folder from outside it** counts as created at the move: the history read is limited to the pages folder, so that move reads as an add. +### Regions + +A layout can have regions besides the body: places, such as a sidebar, that a page's placed components go into. A page +with nothing for a region has an empty one, so the layout leaves it out: the sidebar is there or not by what the page +holds. + +**A layout declares them** on `page.regions` in its schema, and writes each where it wants it: + +```json +"page": { "properties": { "regions": { "x-pd-regions": ["sidebar"], "x-pd-toc": true } } } +``` + +```handlebars +{{#if page.regions.sidebar}}
{{{page.regions.sidebar}}}
{{/if}} +``` + +- `page.regions.` is the region's HTML, or null when the page puts nothing there. +- `x-pd-toc` (optional) shows the [table of contents](#the-table-of-contents) on the layout's pages. +- **CSS is told what is filled:** a page whose layout declares regions names the filled ones on its ``, + `` (empty when none), so a skin switches its grid without `:has()`: + + ```css + body[data-pd-regions~="sidebar"] .doc { grid-template-areas: "content sidebar"; } + ``` + +**A component goes into a region** by its tag, `region="sidebar"` on the `pd-` tag, or by its default, `"x-pd-region": +"sidebar"` at its schema's root. The tag wins. Inside a region, components keep the page's order, and each is checked +against its schema wherever it ends up. + +- A region another layout of the skin has, and this page's layout doesn't: the component is left out, with no + message. Some layouts have a sidebar, some don't. +- A region no layout of the skin declares stops the page, with a "did you mean". +- `region` on a tag is Pattern Dump's: a component whose schema declares a `region` property can't be placed with it. + +**The layout's own landmarks are not regions:** `header`, `footer`, `nav` and `main` (the body itself). A layout may use +them as grid-area names for its own markup, but declaring one as a region stops its pages, and so does a tag or a +default region naming one (the message lists the regions the layout offers). A component in a region may not bring a +landmark of its own either: a `
`, or a `
` or `