Feature availability

Use this page to see what works without configuration, what can be switched off, and what needs an extension. For syntax examples, start with the cheat sheet.

What is available by default

Features fall into three groups: always available, available by default with an opt-out, and opt-in or application-supplied - for example Mermaid rendering in a documentation site.

---

Core syntax

Familiar document features

Feature	Carve Syntax	Status
Smart typography	--, ---, ..., quotes	✅ In spec (4.18)
@mentions	@username	✅ In spec (4.20)
#tags	#tagname	✅ In spec (4.20)
Admonitions	::: note, ::: warning	✅ In spec (4.12)
Frontmatter	--- YAML block	✅ In spec (4.23)
Footnotes	[^ref]	✅ In spec (4.11)
Definition lists	:: term / : definition	✅ In spec (4.5)
Task lists	- [ ], - [x]	✅ In spec (4.5)
Profiles	Feature restriction	✅ In spec (4.21)
Attributes	{#id .class key=value}	✅ In spec (4.10)
Extensions	:type[content]{attrs}	✅ In spec (4.20)

Carve-specific features

These features are part of Carve today. The comparison column shows the equivalent spelling in djot-php, one of the projects Carve originally drew experience from. Grammar references point at resources/grammar.ebnf.

Feature	djot-php Syntax	Carve Syntax	Status
Captions	^ caption after block	^ caption	✅ In grammar (caption rule; image/blockquote/table placement).
Abbreviations	*[ABBR]: expansion	*[ABBR]: expansion	✅ In grammar (PART 5: Abbreviations).
Semantic spans	[text]{.kbd} → <kbd>	[text]{kbd}	✅ Core reserves three span attributes - abbr, time, kbd (PART 9 §9). samp, var, cite, dfn are the Tier-2 SemanticSpan extension's; code and mark are nobody's, since `x` and =x= already write those elements. The :name[…] spelling is soft-deprecated in the extension.
Autolinks	<url> / <email>	Angle-bracket autolinks only	✅ In spec (4.3). Bare URLs are not auto-linked (djot-aligned).
Inline footnotes	[content]{.fn}	^[content]	✅ Tier-1 core, in grammar (§16). A carve addition (not in djot); pandoc-style ^[content], numbered into the shared endnotes.
Table alignment	:--, --:, :--:	|=< / |=> / |=~ markers	✅ In spec (4.8).
Rowspan/colspan	^ and < markers	^ and < markers	✅ In grammar (span_cell / rowspan_marker / colspan_marker).
Multi-line cells	+ continuation	+ continuation	✅ In grammar (table multi-line cells).

---

Features Carve adds

The features below are part of Carve syntax; the examples provide a quick feature-level reference.

1. Captions (^)

![Photo](image.jpg)
^ Figure 1: A beautiful sunset

> To be or not to be
^ Shakespeare, Hamlet

|= Col 1 |= Col 2 |
| Data   | Data   |
^ Table 1: Sample data

Output varies by context:

• Images → <figure> + <figcaption>
• Tables → <caption> element
• Blockquotes → <figure> + <figcaption>, which is where the HTML Standard puts a quotation's attribution: outside the <blockquote>, never inside it

2. Abbreviations

The HTML spec defines WWW standards.

*[HTML]: HyperText Markup Language
*[WWW]: World Wide Web

• Definitions at document end (or anywhere, processed first pass)
• Word-boundary matching only
• Not applied inside code

3. Semantic Inline Elements

The attribute form names the element:

Press [Ctrl+C]{kbd} to copy.
The term [markup]{dfn} means...
[HTML]{abbr="HyperText Markup Language"} is a standard.

abbr, time and kbd are core; dfn (with samp, var and cite) needs the SemanticSpan extension and is an ordinary attribute until it is enabled.

This shipped as an attribute rather than as the :type[content]{attrs} pattern this document originally proposed: a consumed name renames the span, so the id and classes an author wrote land on the produced element, and several names combine on one span where the :type[…] form cannot nest.

4. Table Enhancements (from proposals)

Multi-line cells:

| Name   | Description        |
|--------|---------------------|
| Item 1 | A long description |
+        | that continues     |

Rowspan (^) and Colspan (<):

| Category | Item   | Price |
|----------|--------|-------|
| Fruits   | Apple  | $1.00 |
| ^        | Banana | $0.50 |
| ^        | Orange | $0.75 |

| Name  | Contact Info      | <     |
|-------|-------------------|-------|
| Alice | alice@example.com | x5234 |

---

Optional and application features

These should remain implementation-specific, not part of Carve syntax:

djot-php extension	Why it stays outside core syntax
ExternalLinksExtension	HTML attribute concern (target, rel)
DefaultAttributesExtension	Implementation convenience
HeadingPermalinksExtension	Rendering/UI concern
TableOfContentsExtension	Derived content, not source syntax
MermaidExtension	Third-party tool integration
CodeGroupExtension	UI/framework concern (tabs)
TabsExtension	UI/framework concern
SmartQuotesExtension	Locale config, not syntax
WikilinksExtension	Context-dependent (wiki software)
HeadingReferenceExtension	Implementation of </#id> resolution

---

Summary

Added to Carve native syntax:

1. Captions (^)
2. Abbreviations (*[ABBR]: ...)
3. Table multi-line (+), rowspan (^), colspan (<)

Native, confirmed in spec:

1. Semantic elements via :type[content] extension syntax
2. Angle-bracket autolinks (<url> / <email>) - bare URLs stay literal

Keep as implementation extensions:

• External link attributes
• Heading permalinks
• Table of contents generation
• Mermaid/diagram support
• Tabbed UI components
• Wiki-style links (context-dependent)

---

Disabling / Restricting Features

Can a processor turn features off? It depends on the tier; the availability summary below gives the full split.

This MUST / SHOULD / MAY split is the same model as the Tier-1/2/3 taxonomy in the normative extensions contract: MUST = Tier-1 core (not disableable); SHOULD = Tier-1 default-on but a processor MAY disable it; MAY = Tier-2 (spec-listed, off by default) / Tier-3 (per-impl). The extensions contract has the consolidated feature → tier table.

Tier	Features	Disableable?
Core (MUST)	captions, abbreviations, tables (rowspan/colspan/multi-line), autolinks, emphasis family, links, math, footnotes, crossrefs, the :type[content] extension syntax	No. Corpus-pinned; identical across implementations. Disabling one means the processor is no longer Carve-conformant.
Default-on (SHOULD)	@mention, #tag, smart typography	Yes. On by default in the conformant core; a processor MAY disable them. Normative: resources/grammar.ebnf PART 9 §19.
Out of core (MAY)	includes ({{ … }}) - specified in PART 9 §19 (processor-level; the core leaves the directive literal), the extension registry beyond the generic fallback, all "implementation extensions" above	Yes / opt-in. Processor-level; a conformant core MAY omit them entirely (e.g. leave {{ … }} literal). Includes now have a full normative spec (syntax, host-resolver contract, collision + limit + security rules) even though the core builds none of it.

Separately, Profiles (case-study spec §4.21) restrict which features are allowed in a given context rather than disabling output globally. A profile (Profile::comment(), Profile::article(), …) marks node types as disallowed and applies a STRIP / TO_TEXT / ERROR action. This is a processor-level mechanism; it is not encoded in resources/grammar.ebnf.

---

Availability summary

The availability split answers what an author can use everywhere and what requires configuration. Exact output rules live in resources/grammar.ebnf; this section stays at the feature level.

Always available

• Blocks: headings (+ <section> wrapping, §13), paragraphs, thematic breaks, fenced code, blockquotes, lists (ordered decimal/alpha/roman with . and ) delimiters + start, §10/§11; unordered, task; tight/loose §17), tables (|= headers, alignment, rowspan/colspan/multi-line), the two-tier ::: model (canonical <aside class="admonition …"> / custom <div class="…">, §12), figures/captions, abbreviation definitions, raw blocks, comments.
• Inline: emphasis family (bare / * _ ~ = + /* */; sup/sub braced-only {^ ^} / {, ,}, §9), code spans, raw inline (`…`{=format} passthrough, §20), links (inline / reference / collapsed), angle-bracket autolinks (<url> / <email>), images, spans (§14), math (djot form, §18), footnotes (reference form, §16), abbreviations, editorial markup, crossrefs (</#id>, markup-preserving §19), hard/soft breaks.
• Semantics: automatic heading ids (jgm/djot#393 run-replacement, case-preserving, non-ASCII preserved, smart typography reversed to ASCII before slugging; opt-in lowercase and opt-in ASCII fold; cross-references resolve case-insensitively), id de-duplication, order-independent reference/abbreviation/footnote resolution.

Available by default, with an opt-out

• @mention and #tag shorthands, smart typography (grammar PART 9 §19).

Opt-in or supplied by an application

• Includes ({{ … }}) - specified in PART 9 §19 (host-resolver model, collision + limit + security rules; the File inclusion page); processor-level, and the core leaves the directive literal.
• The :type[content] extension registry beyond the generic fallback.
• Everything under "Keep as implementation extensions" above.

Not implemented, and not planned

• Sidenotes ([>content]), dismissed: a sidenote is footnote content placed in the margin by CSS, so it needs no syntax of its own. [> is unclaimed and [>foo] is literal text. See dismissed-syntax.md. (Both note forms that do exist, [^label] and inline ^[content], are implemented; see §16.)
• Setext (underline) headings — intentionally excluded (matches djot).

Deliberate gaps (will not implement)

• Djot's both-parens ordered-list delimiter (1) / (a) / (i). Carve supports the decimal/alpha/roman dialects and the . and ) delimiters, which cover the practical need. The (1) form is the most prose-ambiguous marker (a wrapped line beginning (1) … reads as a parenthetical aside), and supporting it adds leading-paren marker detection for no real gain. The rendered paren glyph is a CSS list-style concern.