Escapes & special characters

Most of the time you need no escape: characters that only look like markup stay prose. When you do want a marker shown as itself, put a backslash before it.

One rule

A backslash before any punctuation character makes that character literal, everywhere, and the backslash is removed. Before a letter, digit or space it is an ordinary character, so paths keep theirs.

source

Use \@weil, \#tag, \*not bold\*, \_not italic\_ and \~ here.
Write \(if \@x) or \<% in docs. C:\Users\mara stays as typed.

result

Use @weil, #tag, *not bold*, _not italic_ and ~ here. Write (if @x) or <% in docs. C:\Users\mara stays as typed.

<p>Use @weil, #tag, *not bold*, _not italic_ and ~ here.
Write (if @x) or &lt;% in docs. C:\Users\mara stays as typed.</p>

A doubled backslash \\ gives one backslash.

In parameter values

The same rule works inside parentheses. Escape a comma to keep a positional value whole, or a parenthesis that would otherwise close the list:

#cite(author, year)
::author:: (::year::)
cite#

@cite(Weil\, S., 1952) — @img(src: wink.png, alt: a wink \;\))

<p>Weil, S. (1952) — <img src="wink.png" alt="a wink ;)"></p>

Named values rarely need it: a value already runs to the next declared key, so @cite(author: Weil, S., year: 1952) works as written. In a record, a value in double quotes is always text: { author: "Boud, D." }.

What needs no escape

Prose stays prose wherever no construct can use a character. None of these need a backslash:

source

Email jane.doe@uni.edu about C# and F#, see https://x.org/docs#intro, or tweet
#MeToo. It took ~5 minutes (if any) to compute 5*6*7 in snake_case_names.
The result was surprising!! See doi:10.1/abc.

result

Email jane.doe@uni.edu about C# and F#, see https://x.org/docs#intro, or tweet #MeToo. It took ~5 minutes (if any) to compute 5*6*7 in snake_case_names. The result was surprising!! See doi:10.1/abc.

That renders as one paragraph, exactly as typed. Escape only when the text really would open something — a @name that is a defined node, a line starting ~, an _emphasis_ pair, a (name … name) pair with a known name.

Raw bodies

Inside @@name … name@@ and @@@name … name@@@, Wit syntax is inert and backslashes are kept verbatim — CSS and code escapes survive. To show a {{…}} hole as text, use the frozen three-@@@ form (see Literal & raw nodes).

Common mistakes