Core Ideas
NCM has a small set of nouns. Learn these nouns first. Then the format makes sense.
Element versus block
An element is the syntactic read of the Markdown. It says what pattern the parser saw. A heading line is a header element. A fenced code region is a code element. Elements have no identity.
A block is the semantic result. It says what the document means to a product. Every block has an identity. Most elements map to one block. Some elements become a richer block through promotion.
The parser builds elements first. Then it builds blocks. See Parse and Render a Document.
Block identity
Every block has a positional identity. The first body block is b1. The next is b2. Nested items use a dotted form such as b4.1.
Most blocks also have a stable identity. An author can set it with an anchor. A heading can use a slug. Other blocks fall back to a hash of their content.
The positional identity can shift when you insert or reorder content. The stable identity is meant to survive those edits. See Block Identity.
Promotion
Promotion turns one or more elements into a richer block. A callout blockquote becomes an admonition. A mermaid fence becomes a diagram. An embed plus the next line of caption becomes a figure.
Promotion is not a new syntax family. You still write Markdown. The block layer reads a familiar pattern and gives it a type. See Promotion.
Preset and extension
A preset is a named set of parse choices. CommonMark is strict base Markdown. GFM adds tables, strikethrough, and task lists. NCM adds the promotions that this format is for.
An extension is one promotion you can switch on or off. Figures, admonitions, and footnotes are on in the default NCM preset. Definition lists, spoilers, and asides stay off unless you turn them on. See Presets and Extensions.
Frontmatter
Frontmatter is a YAML block at the very start of the document. It carries metadata such as title, tags, and dates. Custom fields must stay flat. If you omit a title, the first level-one heading can supply it. See Add Metadata with Frontmatter.
Embed and wikilink
An embed places media or a file in the document as its own block. Images are blocks. They are not inline.
A wikilink points at another document by title. A wiki embed places another document or file by title. Mesh can resolve those targets. The parser itself does not look them up. A renderer can show a link as resolved, missing, or ambiguous.
Admonition
An admonition is a callout block. You write it as a blockquote that starts with a type marker. The types are note, warning, tip, danger, info, success, question, and quote. See Use Callouts Diagrams and Figures.
Figure
A figure is an embed plus a caption. You write the embed. You put the caption on the next line. Do not put a blank line between them. Promotion joins them into one figure block.
Page marker
A page marker records a source page from a PDF parse. It is an HTML comment of the form <!--page:1-->. It does not draw on the page. A viewer uses it to stay in step with the source pages.
How the nouns relate
You write Markdown. The parser reads syntax into elements. Promotion and identity turn elements into blocks. A preset chooses which promotions run. Frontmatter sits at the front as metadata. Embeds, wiki links, admonitions, figures, and page markers are block types in that tree.
Start with Write Your First NCM Document if you want to see the nouns in a document.