Syntax edge cases
Non-normative.
This guide explains what ambiguous-looking source means in practice. The formal rules live in the grammar; examples here focus on the result an author sees.
1. Italic /text/ vs File Paths
Problem: Slashes are common in paths and URLs.
Resolution: Carve uses a word-boundary emphasis rule that is stricter than Djot (Djot's _/* rule is purely whitespace-flanking; Carve adds word-boundary conditions so intraword a/b/c, foo_bar_baz, and snake_case stay literal). This rule applies to every bare delimiter (/ * _ ~ =, all single-char), so foo*bar*baz and foo~bar~baz are literal too. For deliberate intraword emphasis use the forced {X … X} family (PART 9 §22), e.g. foo{*bar*}baz. The normative statement lives in resources/grammar.ebnf PART 9 §9, the inline pairing procedure; in summary, for any bare delimiter:
- opens only if not followed by whitespace and preceded by the start of the line/block, whitespace, or punctuation, but not by an alphanumeric,
_, or the same delimiter (so(/x/)anda./b/open, whilesnake_/case/and//a/do not) - closes only if not preceded by whitespace and not followed by an alphanumeric (so
x /a/b ystays literal: the candidate closer is followed byb) - inner
/characters become literal content (bare same-type spans do not nest)
The same-delimiter adjacency part of that rule applies to all five single-character delimiters: a delimiter adjacent to another of the same delimiter (before or after) does not open. So a doubled delimiter is always literal: **x**, ~~x~~, and ==x== render verbatim, exactly like //x// and __x__. (^ and , are not delimiters at all; superscript/subscript are the braced {^x^} / {,x,} forms only.)
A span holding its own delimiter between two word characters does not form:/usr/local/, _my_var_ and *a*b* render as written. A single segment has the shape of an italic word, so /etc/ still renders <em>etc</em>. An intraword path fragment like a/b/c stays literal because the / is alphanumeric-flanked and cannot open; x /a/b y stays literal because the closing / is followed by an alphanumeric.
Recommendation: For paths that sit in an emphasizing position, use code fencing - they're code anyway:
The config is in `/etc/nginx/nginx.conf` for setup.
Use /italic/ for emphasis.Examples:
| Input | Output | Reason |
|---|---|---|
/italic/ | italic | Valid emphasis |
/etc/nginx/ | etc/nginx | Also valid (inner / is content) |
`/etc/nginx/` | /etc/nginx/ | Code span - recommended for paths |
!`/etc/nginx/` | /etc/nginx/ | Inline literal - literal text, no code styling |
the/path/here | the/path/here | No whitespace before opener |
/ spaced / | / spaced / | Whitespace after opener - invalid |
Best practice: Paths, URLs, and file references should use backticks - they're technical/code content.
If you want the path to read as ordinary prose rather than monospace code, use the inline literal !`…` prefix instead (PART 9 §27): it suppresses all markup inside the span - so _, /, * stay literal - but emits plain text with no <code> wrapper. So !`/etc/nginx_foo/` renders the bare string /etc/nginx_foo/ with no emphasis and no code styling, whereas the backtick form `/etc/nginx_foo/` renders it as a <code> span.
2. Caret ^ Overloading
The ^ character has four meanings:
| Context | Meaning | Example |
|---|---|---|
| Braced inline | Superscript | x{^2^} |
| Inline footnote opener | Note | ^[content] |
| Table cell | Rowspan | | ^ | |
| Line start after block | Caption | ^ Figure 1 |
Resolution rules:
- Caption:
^at line start, immediately after image/quote/table/code block/display math - Rowspan:
^as sole content of a table cell (with optional whitespace) - Superscript: only the braced
{^text^}; a bare^is otherwise literal (unless it opens an inline footnote^[…])
Examples:
x{^2^} + y{^2^} = z{^2^} # Superscript (braced form)
| Category | Item |
| ^ | Apple | # Rowspan (^ is sole cell content)

^ Figure 1: Caption # Caption (^ at line start after image)
The answer is ^ 42. # Literal ^ (plain text)
x^2^ + y^2^ # Literal ^ (no bare superscript)Edge case - table cell with just ^2^:
| Value |
| ^2^ |This is literal text ^2^ in a cell (not rowspan: the ^ is not alone; not superscript: there is no bare superscript). Superscript in a cell is the braced | {^2^} |.
3. Less-than < Overloading
| Context | Meaning | Example |
|---|---|---|
| Table cell | Colspan | | < | |
| Inline | Smart typography | <-- → ← |
| Autolinks | URL wrapper | <https://...> |
Resolution rules:
- Colspan:
<as sole content of a table cell - Autolink:
<followed by URL scheme or email pattern - Smart typography:
<--,<-->,<==,<=>,<=patterns (and the deprecated<-/<->), matched longest-first - Literal: Everything else
Examples:
| Header | < | # Colspan
<https://example.com> # Autolink
The arrow points <-- that way # Smart typography (←)
if (x < 5) # Literal <4. Asterisk * Contexts
| Context | Meaning | Example |
|---|---|---|
| Inline | Bold | *bold* |
| Line start | List item | * item |
After *[ | Abbreviation | *[HTML]: ... |
Resolution rules:
- List:
*at line start followed by space - Abbreviation:
*[at line start - Bold:
*text*with content between asterisks - Literal: Standalone
*or escaped\*
Examples:
* List item # List
*bold text* # Bold
*[HTML]: HyperText... # Abbreviation
5 * 3 = 15 # Literal (spaces around)Edge case - bold at line start:
*This whole line is bold*
*This is NOT bold - no closing delimiter, stays literalThe first line is bold, not a list item, because * is NOT followed by whitespace. The second stays literal text: an opener without a matching closer never emphasizes.
List requires * (asterisk + space). Bold opener requires * + non-whitespace AND a valid closer ahead.
5. @mention Boundaries
Problem: Where does a mention end?
Resolution rules:
- Starts with
@followed by alphanumeric - Continues with alphanumeric,
_,-, and interior dots (a dot followed by another name character) - Ends at whitespace, other punctuation, or end of line; a trailing dot is sentence punctuation, not part of the name
Examples:
| Input | Mention | Remainder |
|---|---|---|
@john | @john | - |
@john-doe | @john-doe | - |
@john_doe | @john_doe | - |
@john.doe | @john.doe | - |
@john. | @john | . |
@john's | @john | 's |
@john! | @john | ! |
email@domain.com | - | (not a mention, no word boundary before @) |
The same name rule applies to #tags (#release-1.0 is one tag). A name holds at least one ASCII letter, so @5 and #123 are text.
6. #tag vs Headings
| Context | Meaning | Example |
|---|---|---|
| Line start | Heading | # Heading |
| Inline | Tag | #project-x |
Resolution rules:
- Heading:
#at line start, followed by space, then text - Tag:
#preceded by whitespace or start of inline content, followed by a name that holds at least one ASCII letter
Examples:
# Heading 1 # Heading
Check out #project-x # Tag
Issue #123 # Text (a tag name needs a letter)
Version #v2 # Tag
#notaheading # Tag (no space after #)7. Abbreviation *[ vs Bold
Problem: *[ could start bold with a link inside.
*[HTML]: HyperText Markup Language # Abbreviation definition
*[link text](url)* more text # Bold containing a linkResolution rules:
- Abbreviation:
*[at line start, followed byWORD]:pattern - Bold with link:
*[inline, link syntax inside, closed with*
Examples:
*[HTML]: HyperText Markup Language
# → Abbreviation (line start, ]: pattern)
See *[the docs](url) for more* info
# → Bold span containing a link8. Nested Emphasis
Rule: Bare same-type nesting is invalid. Explicit braced children may repeat an active kind; different-type nesting remains valid. See explicit same-kind emphasis nesting for the rule and implementation status.
/This /does not/ nest/ # One italic span: This /does not
/This *does* nest/ # Valid: italic with bold inside
*Bold with /italic/ inside* # Valid
/*Bold italic*/ # Valid: combinedParsing: A bare opener matches the nearest reachable valid closer of the same type, subject to the boundary rules in §1. Bare same-type delimiters inside the span are literal content (bare same-type spans do not nest), so /a /b/ is <em>a /b</em>. Different-type spans nest fully (*Bold with /italic/ inside*). Resolution uses a delimiter stack in a single left-to-right pass: linear time, no backtracking.
For /This /does not/ nest/, the slash before does cannot close because it follows whitespace. The slash after not is the nearest reachable valid closer, so the output is <em>This /does not</em> nest/ inside a paragraph. A span whose content holds its own delimiter between two word characters does not form, so /usr/local/ and _my_var_ stay text. See PART 8's disambiguation rule and PART 9 §9.
9. Table Cells with Special Characters
Problem: Pipes and other characters in cell content.
| Command | Description |
| `ls | grep foo` | Filter output |
| Price | $50 \| $100 |Resolution rules:
- Code spans (backticks) protect content
- Backslash escapes pipe:
\| - Pipes inside inline elements (code, links) are protected
10. Comments (%% and %%%)
Line comments:
%%is a comment marker when preceded by whitespace or at the start of the inline run (line start counts), including a trailing comment after text:Visible. %% this tail is a commentkeeps onlyVisible.- The comment runs to the end of the line; it never crosses a line break
- Without preceding whitespace
%%is literal:The value is 50%% increasestays literal text, so percentages are safe \%%(escaped first percent) is literal- A whole-line comment may be indented: leading whitespace before
%%does not matter, so an indented line whose first non-whitespace content is%%is a comment line just like one in the first column. It is erased before layout: it renders nothing and does not interrupt an open paragraph (PART 0 S1, CARVE-P0-005) - The column does not matter inside a container either. Below a list item's content column a comment is erased too, so the open paragraph continues and no item closes (
- a/%% c/moreis one itema more)
Block comments:
%%%must start the line to open/close; the leading run of%is the delimiter and any trailing text on that line is ignored, so%%% TODO,%%% notesand%%%htmlall open a comment and%%% endcloses one%%%has no info string: a raw passthrough block is a code fence with an=FORMATinfo string (```=html), so%%% htmlis a comment and its body stays hidden, never raw output- Content can contain anything except the same-length delimiter
- Use more
%to nest:%%%%can contain%%% - An unterminated
%%%(no matching closer anywhere ahead) does not open a block: the line falls back to a%%line comment, so the following blocks still render instead of vanishing. Same rule as:::, and for the same reason: an unclosed opener must not swallow the rest of the document carve fmtkeeps an opener's trailing text as the comment's first body line (nothing is lost); a closer's trailing text is dropped
Container ownership: An unmatched %%% opener is a line comment for both visibility and ownership. A comment closes no list item, description body or footnote body at any column: the next visible line picks the owner. Here that line stands at column 0, so it closes the item and is a document paragraph:
- x
%%%
y<ul>
<li>x</li>
</ul>
<p>y</p>Replacing %%% with %% z gives the same result. With y at the item's content column, y stays in the item, because the comment ended the paragraph and closed nothing. See S2 in the ownership procedure.
Provenance marker (tool-written):
- Tooling such as
carve fmt --stampwrites a trailing comment recording the spec version a document was processed under and the engine that wrote it, e.g.%% carve-version: 0.1; generated-by: carve-js 0.1.0(or the%%%block form) - It is an ordinary comment, so it renders nothing; it is identified by its
carve-version:first field - Deterministic (no timestamp) and replace-in-place (a tool updates the existing marker, never appends a second), and it sits at the end of the document
- Authors do not hand-write it; a plain
carve fmtpreserves it unchanged
Examples:
%% This is a comment
Text with 50%% is not a comment (no whitespace before %%).
Visible text. %% trailing comment, consumed to end of line
%%%
Block comment with %% inside is fine.
%%%
> A quoted paragraph.
%% Below the quote's marker, and still a comment.In code blocks: %% and %%% are literal (code blocks protect everything).
11. Code Blocks Override Everything
Content inside code spans and code blocks is never parsed for Carve syntax.
```python
# This is not a Carve heading
*this* is not bold
/path/to/file is just text
```
Inline `*not bold*` and `/not/italic/` are literal.12. Caption Timing
Problem: When does ^ become a caption vs literal text?
Rules:
- Caption
^must be at line start - Must immediately follow an image, blockquote, table, fenced code block (a captioned code block is a numbered listing), or standalone display-math block (a numbered equation)
- Blank line allowed between block and caption (for readability)

^ This is a caption

^ This is also a caption (blank line OK)

Some other text
^ This is NOT a caption (intervening content)13. The Three Faces of +
Note: + is not a Carve bullet (unlike Markdown/Djot). Carve bullets are - and * only; + is reserved for two unrelated continuation roles plus plain text.
- item
+ # List-continuation marker (lone +): attaches
> note # the following block at its column to `item`
| Cell |
+ cont | # Table continuation (+ line WITH pipe structure)
+ not a bullet # Plain paragraph text (+ then content, no pipe)Resolution:
- A lone
+at an open container's marker column or directly after quote markers attaches one following block at that same column. At an open list item's marker column, a following list item at that column is a sibling, so the+is refused: it renders nothing and the refused-marker lint reports it (markup-carve/carve#3421, markup-carve/carve#5013). - A
+ ... |line (pipe structure) is a table continuation - A
+at no open marker column is ordinary text or fence payload, placed by its own column. A+ xline is ordinary paragraph text;+never starts a list
14. Escaping
Backslash escapes any ASCII punctuation:
\*literal asterisks\*
\/not italic\/
\@not-a-mention
\#not-a-tag
\^ not a caption markerInside code spans, backslash is literal:
`\*still has backslash\*`15. Smart Typography Conflicts
| Pattern | Output | Could conflict with |
|---|---|---|
-- | – (en-dash) | Strikethrough delimiter start? No, ~ is used |
--- | — (em-dash) | Horizontal rule? Only at line start alone |
... | … (ellipsis) | Nothing |
--> | → | Nothing |
<-- | ← | Less-than? Requires full pattern |
==> | ⇒ | Nothing |
<== | ⇐ | <=? Yes - the longer run wins, so <== is the arrow and a bare <= stays ≤ |
<=> | ⇔ | <=? Same rule. <==> is <== then >, and renders ⇐> |
<= | ≤ | Less-than-equal? Yes, context-dependent |
Resolution: Smart typography only applies to specific patterns, not partial matches, and a longer pattern is matched before a shorter one it contains. The single-hyphen -> / <- / <-> still render and are deprecated; => was removed and renders literally, because key => value is prose about code.
16. Empty/Whitespace-Only Elements
** # Not bold (no content)
// # Not italic (no content between //)
{^^} # Not superscript (no content)
|| # Empty table cells (valid)Rule: Emphasis requires non-whitespace content between delimiters.
17. Block Openers Interrupt Paragraphs (Paragraph Interruption)
Rule: a visible block (except a list marker) interrupts an open paragraph with no blank line before it, at the document top level and inside nested content (list item, block quote, admonition/div body). A continuation line that begins such a block is parsed as that block; the paragraph ends on the line before it. This is the Markdown-like rule (CommonMark "a paragraph can be interrupted") for those blocks. List markers follow Djot: a list needs a blank line before it, so a bullet or ordered marker after a prose line folds into the paragraph as lazy continuation.
Die Frage ist x = 5
* 3 + 17 wahr.This is one paragraph (Die Frage ist x = 5\n* 3 + 17 wahr.): a list marker does not interrupt a paragraph, so a hard-wrapped prose line beginning with a bullet stays prose. Add a blank line before the marker to start a list.
Symmetric list rule. Neither a bullet (- /* , - [x] task) nor an ordered marker (1., 2., 1985., a., i.) interrupts a paragraph; they behave identically. This avoids the CommonMark 1.-only heuristic Djot removed, and removes the old false positive where a wrapped prose line became a list.
In a marker body a marker opens a list. The fold is for paragraphs of the document and of quotes. In a list item, description body or footnote body a marker at or past the content column opens a list with no blank line, and a marker below that column closes the body:
:: term
: first line
- a list in the description
- a list after the definition listA wrapped line that starts with - 1 or * 2 inside one of these bodies becomes a list too (markup-carve/carve#4860).
A heading and a blockquote are different: a list marker ends an open heading (a bounded title) and starts a top-level sibling list. A blockquote is not ended: a quoted line ends in an open paragraph, so a list marker folds into it as lazy continuation: > q / - a is one quote whose paragraph is q\n- a, not a quote plus a sibling list. That holds only while the line misses nothing but quotes: - > q / - a closes the quote and gives the item a sublist. Nothing folds into a heading at all, plain text included - a heading ends at the newline (§18). The blockquote half of this matches Djot; the heading half deliberately does not.
Other carve-outs:
- No closer lookahead - a valid code or raw fence (
```/~~~) interrupts a paragraph whether or not a closer follows, as in CommonMark. An unclosed fence runs to the end of its container. A:::opener behaves the same way: it opens without a closer and closes at its container boundary or end of input (§12). So does a%%%comment fence, which hides everything up to that point (§28, markup-carve/carve#4907). - Image excluded — a bare image
is inline content, not a block, so it renders inside the paragraph.
Block-level invisible constructs (footnote definitions, %%% comments and {…} block-attribute lines) interrupt with no blank line: they produce no block of their own, so they are collected/consumed (an attribute line floats forward to the next block, §15). A %% line comment and a one-line link or abbreviation definition are erased before layout and interrupt nothing (PART 0 S1, markup-carve/carve#5012).
| Input | Result | Reason |
|---|---|---|
Text / - a / - b | one paragraph | list marker folds (no blank line) |
x = 5 / * 3 + 17 | one paragraph | list marker folds (no false positive) |
Text / 1. a (or 2. a, 1985. a) | one paragraph | list marker folds |
Text / (blank) / - a | paragraph + list | blank line starts the list |
Text / # H | paragraph + heading | heading interrupts |
Text / ``` / code / ``` | paragraph + code block | fence interrupts |
Text / ``` / code | paragraph + code block | an unclosed fence runs to the end |
Text / --- / more | paragraph + <hr> + paragraph | thematic break interrupts |
Text /  | one paragraph (inline image) | image excluded |
Text / ^ cap | one paragraph | a caption line is not an interrupter (I7); §4 attaches only to a captionable host |
 / ^ cap | <figure> | the paragraph IS the image, so §4 has a host and the caption attaches |
See[^m]. / [^m]: note | paragraph + endnotes | invisible construct |
# H / - item | heading + sibling list | list marker ENDS the heading |
# H / 1. one | heading + sibling list | list marker ENDS the heading (ordered too) |
> q / - a | one quoted paragraph | the bullet folds in (lazy continuation) |
> text / > # H | quote: paragraph + heading | heading interrupts inside the quote |
> p / > - x | one quoted paragraph | quoted bullet folds (paragraph interruption inside the quote) |
- a / - b | nested sublist | indented sublist still nests (content column) |
- a / - b | two sibling items | a marker of the same kind below the content column is a sibling (carve#3885) |
1. a / - b | one item (folds) | a marker of another kind below the content column is lazy text |
1. a / [r]: /u / after | one item, paragraph a after, and r registers | a one-line definition is erased before layout at any column (PART 0 S1) |
1. a / [r]: /u / after | one item, paragraph a after, and r registers | erased below the content column too; it closes nothing |
1. a / [r]: /u / after | one item, paragraph a after | erased at the item's content column as well |
- text / # H | item: text + heading | heading interrupts inside the item |
The formal statement is in resources/grammar.ebnf, PART 9 §10.
18. Single-Line Headings (Nothing Folds INTO a Heading)
Rule: a heading ends at the newline. Nothing folds into it - the next line begins whatever block it begins, exactly as after any other closed block. A ^ caption line is no exception: it does not fold in, and it does not attach either, because a heading is not one of §4's captionable hosts. It opens an ordinary paragraph.
The heading id derives from that single line.
# Title
outsideHeading plus paragraph: <h1 id="Title">Title</h1> then <p>outside</p>.
See divergence-from-djot §14 for the rationale.
# Title
outsideIdentical output: the blank line changes nothing.
Summary: Parser Priority
When multiple interpretations are possible, use this order:
- Code spans/blocks - Highest priority, content is literal
- Escapes -
\xmakesxliteral - Block-level constructs - Headings, lists, tables, code blocks
- Captions -
^at line start after captionable block - Autolinks -
<url>pattern - Links/Images -
[text](url), - Emphasis -
/italic/,*bold*, etc. - Smart typography -
--,-->, etc. - Extensions -
@mention,#tag,:type[content] - Plain text - Everything else