Document header

#Writing the header

A document opens with a starred attribute group — * at the start of a line, followed by ( ). It is the first thing in the file, it carries no body, and it is the one construct written with the * sigil.

*(
    title: The 68–95–99.7 rule, live
    description: However you set k, the band from mu - k sigma to mu + k sigma holds the same share.
    tags: statistics, probability, normal-distribution
    lesson
)

scene{
    …
}

Inside, it is an ordinary attribute group: key: value pairs, one per line or separated by semicolons, with the boolean shorthand for the flags — lesson, not lesson: true.

#The header attributes

The header is typed like any attribute group. title is the one required key — a document without one does not compile — and a key outside the set below is a header error, not something carried along.

• title — the document's name, shown wherever it is listed or linked. Required. Alias name. It also names the subject every scene answers to — see What a document covers.
• description — one sentence, used for cards, previews and search results. A card clamps it — four lines, fewer in a dense listing — so the part of a long description that decides whether to open the document has to be in the first line of it.
• tags — a comma-separated list, used for subject browsing. Deduplicated, and capped at seven.
• lesson — flags structured teaching material. Filterable under Explore's Lessons.
• template — renders the Template badge in the title header, nothing more.
• private — the document is visible only to its author and the people it is shared with. For a document published from a GitHub repository this is the one visibility control there is: a push to the default branch publishes, and there is no draft state.

#Placement

At the top of the document, once. A partial spliced in with @include is source, not a document of its own, so it carries no header — the metadata belongs to the file that is being compiled.

Below it, a document holds two nodes: scene, which is the document, and cite, which declares a source and renders nowhere. Anything else at that level is a content-policy error. Directives are the exception, having no placement rules at all, so a @data or @let may stand between scenes.