The block vocabulary
区块词汇表
Every kind that ships with the package: text, lists, emphasis and data, photographs, and the seven optional kinds a family opts into — plus what an editor may change in place and what it takes to register a new kind.
Reference
A body is a stream of blocks. Each block has a kind, a short id and the fields its kind declares.
The composer may only emit kinds the page family allows, the validator refuses the rest, and the theme has a rule for each. This page lists the kinds that ship with the package.
Text
- lead: the opening paragraph, set larger by most themes; at most one per page
- p: a paragraph of body text
- h: a sub-heading; the renderer derives its level from position, so the model never chooses h2 against h3
- verse: a stanza of free verse, one string per line, kept exactly as pasted
Lists
- ul: unordered points, one string each
- ol: numbered points, each with a title and an optional body paragraph
Emphasis and data
- quote: a pull quote with an optional attribution, allowed only when the source names the speaker
- facts: a labelled fact strip for event logistics such as date, place, audience and size
- table: a comparison table whose every row has exactly as many cells as the head
Photographs
- fig: one photograph placed at this point in the text, referenced by its manifest number, with an optional caption used only when it adds information the text lacks
- sheet: a contact sheet of several photographs by manifest number
Photos never travel through the model. It sees a numbered manifest with a one-line description of each picture and refers to them by number; the server resolves the numbers to stored assets and their derived sizes.
Optional kinds
Seven kinds are registered but sit in no type's default vocabulary. A family opts in by naming them in its allow-list.
- video: a YouTube, Vimeo or Bilibili page URL, or a direct video file, with an optional caption
- link: a link card with a title and an optional description
- cta: one call to action near the end of a page, with a sentence and a short button label
- faq: questions with their answers, both taken from the source; for programme and application pages
- timeline: dated or ordered milestones, each with the date or stage label as the source states it, a short title and an optional sentence
- note: a short aside with a tone the composer chooses for what it is: note for context, tip for advice, warn for a caution the source states
- code: commands, code or configuration kept verbatim, never reformatted or translated
Links to this site's own pages are written as a page reference, family and slug, never as a URL. The server refuses a reference to a page that does not exist and the renderer builds the address for the reader's language, so internal links survive a domain change and a renamed slug. Links to outside pages carry a URL that must appear in the source material; an invented URL is flagged by the fidelity check.
The tone of a note is the one variant the composer chooses, and it is a semantic choice. Everything visual about a kind, such as whether a photo is wide or a table is numeric, is computed by the renderer from the data or decided by the theme.
What an editor can change in place
Every kind has a plain-text form: one line per list item, a blank line between numbered points, a last line beginning with a dash for a quote's attribution, a caption field for a figure.
The in-situ editor lets an editor change the words and the photos of any block. It does not let them change a block's kind or add a block; those requests go back to the composer as a sentence.
Adding a kind
A site registers a new kind with its schema, its one-line documentation for the prompt, its text form for the editor, its search text function and a React renderer. Then it adds the kind to a family's allow-list and writes a theme rule. The renderer always wraps a custom block in the package's own element so the editor's hooks survive.