title: plates-cli part_of: 'plates' audience: public

plates-cli

The plates command: a static site generator over a prov archive.

cargo install plates-cli

installs plates, which finds the archive by walking up from the current directory the same way prov does. The crate is plates-cli; the installed command is plates.

This is the application layer, and the only one in the workspace allowed to have the opinions a library must not: where a build lands, when to build, and how loudly to say what went wrong. What a site is lives in plates; what a page looks like lives in plates-render. Another application over the same archive format replaces this crate and keeps the other two.

The four verbs

They are four views of one build. build writes it to a directory, watch keeps writing it, serve hands it to a browser, and clean takes back exactly what build put down — with one collector and one renderer underneath all four, which is the property that stops a preview and a deploy drifting apart.

--base-url https://example.org is what canonical links, the sitemap, robots.txt and the feeds are written against. Without one they are skipped, which is the right default for a preview whose address is localhost.

_site is underscore-prefixed by the static-site convention, which is not decoration: it sorts away from the archive's own directories, and the hosts that auto-publish a repository skip it, so a build committed by accident does not become a second copy of the site.

Declaring a site

A site is an export. prov's exports.<name> is already a named, gated set of documents that may leave the archive, which is the whole of what a site needs to exist. The render-facing half it cannot carry — a front page, a shell, a stylesheet, a language, extra grammars — is written on the term node of the gate field's vocabulary, which is where a value that is a document keeps what is true of it.

So plates declares no config vocabulary of its own. What a site is, this archive answers.

# The config document, or the root's own `prov:` block.
exports:
  docs:
    label: plates                 # what a reader sees; defaults to the name, humanized
    gate:
      field: audience             # the document field the gate judges
      value: public               # the value that admits a document
    hold: draft                   # a page declaring `draft: true` waits; absent, nothing waits
    view: daily                   # a prov view, for the arrangement; default is containment
fields:
  audience:
    values: closed                # an unknown value is a `prov check` finding
    vocabulary: '[Audiences](/vocab/audiences.md)'
    reify: true                   # each term is a node, not a row

The entry's name is the site's path segment in every published URL — deliberately not the gate value, since the honest name for a readership is routinely one its members should never read off a URL.

The term node

reify: true makes the vocabulary an index node whose contents: are the terms, each an ordinary document with a body, a stable id and backlinks. The term whose term: (or, absent that, title:) is the gate's value is the one plates reads:

# vocab/public.md
---
title: Public
term: public
part_of: '[Audiences](/vocab/audiences.md)'
front_page: '[Home](id:7f3a91c)'
site:
  shell: .config/sites/docs/shell.html
  stylesheet: .config/sites/docs/style.css
  header: .config/sites/docs/header.md
  footer: .config/sites/docs/footer.md
  lang: en
  syntaxes:                       # grammars for languages the built-in 213 miss
    - .config/sites/docs/wat.sublime-syntax
---

Anyone; safe to publish. Everything here has left the archive on purpose.

Every one of them has a defensible default, and the defaults are plates::SiteSpec's. A key inside site: that plates does not read costs the site one setting and is reported; refusing to build the other four sites over it would be a worse answer.

The render keys are nested under site: rather than written bare because a term node's frontmatter is the author's: a top-level shell: is claimed by convention only, and collides with a field the archive already had or with the next tool that wants one. front_page: is exempt because it is not payload — it is a relation, and a declared relation is its own registration.

A term node declaring no audience: of its own is published to nobody, which is the default and the right one: an archive that wants its audiences described on its own site opts in per term, deliberately.

An archive that declares no vocabulary at all keeps working throughout — every render key takes its default and the front page is synthesized from the site's entries.

The deprecated sites: block

Until plates 0.2 a site was declared in a top-level sites: block, on the argument that a site's spelling is a dialect a different host could replace wholesale:

sites:
  blog:
    label: Field notes
    audience: public
    gate_field: clearance        # the field `audience` is compared against
    view: daily
    index: '[Home](id:7f3a91c)'
    shell: .config/sites/blog/shell.html
    stylesheet: .config/sites/blog/style.css
    lang: en
    syntaxes:
      - .config/sites/blog/wat.sublime-syntax

It is read from the same two surfaces prov reads its own config from, in the same order: the root document's frontmatter first, then the config document the root links to, which wins. Where it exists it still wins outright over exports:, block for block — an archive that has not migrated builds exactly what it built before — and every site it declares is named in a warning alongside the export entry and the term node that replace it. plates 0.3 removes it.

Migrating one site is two moves: audience/gate_field become exports.<name>.gate.value/.field, and index/shell/stylesheet/lang/ syntaxes become front_page: and site: on the term node. label and view keep their names and meanings under exports.<name>. hold has no sites: spelling and will not get one — the block is frozen at what it read the day it was deprecated, so a site that wants to hold its drafts back migrates.

What a build remembers

A build records every path it wrote in .plates-build at the destination root.

Two problems, one answer. A rebuild after a document is deleted, renamed or taken off a site leaves the old .html sitting in the destination, and it will be deployed alongside the new ones: a page that is no longer part of the site, still reachable, still in the sitemap of whatever indexed it. And clean given a directory has no way to tell the site it built from a directory somebody typed one character wrong.

So the next build removes what the last one wrote and this one did not, and clean removes exactly the listed set. Nothing ever deletes a file no build of ours recorded writing — which is what makes it safe to point --out at a directory that also holds something else, and why clean refuses a destination with no record rather than guessing. --out typed one character wrong is not a way to delete somebody's work.

It is a dotfile because it ships with the site: a build directory is the deployable artifact, and a memory kept somewhere else would be gone at exactly the moment the next build needed it. Every static host and every web server already declines to serve dot-prefixed files, so the record of the site is not part of the site.

plates serve

Three threads' worth of machinery, and no more. A builder thread owns the archive — every prov future is !Send, so the workspace never crosses a thread boundary; what crosses is the finished bytes. It re-opens the archive for each build rather than reusing one, because a rebuild has to see files that did not exist when the server started, including a changed config document, which is where views and sites are declared. The accept loop hands each connection to a short-lived thread serving from the current snapshot, so serving never blocks on a build and a build never blocks a request; a request mid-rebuild is answered from the previous snapshot, which is what a static host would do.

Change detection is a stat walk compared against the last one — no filesystem-watch dependency, since the platform APIs disagree about what an event is and need a fallback poll anyway for the network and synced volumes an archive often lives on, and the whole of what is wanted here is one bit. It runs only while a browser is actually watching, so an unattended plates serve costs nothing, which matters when the archive is tens of thousands of files rather than a blog.

Served HTML carries one thing a built page does not: a small script that polls a build number and reloads when it moves. It is injected at serve time and never written into a build, so plates build output is byte-identical to what the server renders.

Attachments are never pulled through memory to render a page of text: collection is told they are already accounted for and carries each one's path, length and MIME type forward, so build copies them and serve reads one when a browser asks for it.

Features

Forwarded to plates and plates-render, which forward to prov, which forwards to fig. With a format off, its parser is left out of the build and prov stops recognizing it, so at least one must be on. plates-render is taken with its templating feature here: running the render pipeline is the caller's job, and this is the caller — without it, a body's template directives would be published as literal text.

prov is deliberately not a dependency of this crate. Workspace discovery, the config document and the id registry are all reached through plates::prov, which plates re-exports for exactly this reason: one prov in the tree, and no way for this crate to resolve a different version of the Workspace it hands to collect_site.

License

MIT or Apache-2.0, at your option.