Expand description
The site shell as named slots, and the substitutor that fills a caller-supplied template with them.
A shell template is the outer HTML document a page is wrapped in: everything
from <!DOCTYPE html> down to </html>, with the parts this crate computes
left as named slots. The built-in shell in crate::html fills exactly the
same ShellSlots, so a template is a replacement for that document rather
than a second, parallel notion of what a page is made of.
§Why not handlebars
The reason that decides it is that handlebars-rust has no configurable
delimiters — {{ is hardcoded in its grammar. A shell is an HTML
document, which is exactly where inline <style> and <script> braces
live, and the braces_that_are_not_slots_pass_through test below guarantees
that <style>a{b:c}</style> and <script>if(x){{y()}}</script> survive a
shell verbatim. Handlebars would read {{y()}} as an expression, breaking
every existing theme in favour of \{{.
Two further reasons used to be listed here and are recorded as refuted,
since both are contradicted by this crate’s own code: that handlebars
escapes by its own rule (register_escape_fn installs one, so
crate::page::html_escape could have been it), and that a misspelled
variable cannot be reported precisely (Template::elements is pub, so
walking the compiled AST to validate slot names is a short function).
Bodies pay no delimiter cost, because a body is Markdown — which is why
[crate::template] spells its values with a directive instead, and why this
module keeps a substitutor of its own rather than sharing one. It is
deliberately small: named slots, no expressions, no control flow. Anything a
shell wants to vary per page it varies by rendering a different site.
§Syntax
{{name}} inserts a text slot, HTML-escaped. {{{name}}} inserts a
raw HTML slot verbatim. Whitespace inside the braces is allowed
({{ site_title }}). The two spellings are not interchangeable: each slot is
one kind or the other, and writing it the other way is an error rather than a
silently escaped <div>. Anything that is not a well-formed slot reference —
{{ in an inline script, a CSS block, a {{}} with no name — passes through
literally.
Structs§
- Shell
Error - A shell template that could not be compiled. Carries a message written for whoever wrote the template, since that is the only person who can fix it.
- Shell
Slots - The named values a shell template is filled with.
- Shell
Template - A compiled shell template.