Flexspan lets you invent your own inline markup. You choose a pair of delimiters in the document metadata and say what the enclosed text should become: coloured text, highlighted text, a LaTeX command, a Typst function, or a CSS class.
flexspan:
- left: "!!"
color: redA !!red!! word, **bold text with a !!red!! word** and *!!red emphasis!!*.That is all that is needed: the example above gives red text in HTML, PDF (LaTeX), Typst, Word (docx), revealjs and beamer, with nothing else to define.
flexspan is self-contained: no other extension is needed. (For icons it can optionally be paired with fontawesome-raw, see Icons.)
quarto install extension gpappasunb/flexspan
---
filters:
- flexspan
---To apply it to every document of a project, add it to _quarto.yml:
project:
type: book
filters:
- flexspanFlexspan can be embedded in another extension, for example a slide theme, so
that documents using that theme get flexspan without installing it. From the
directory that holds the other extension's _extensions/ folder:
quarto add gpappasunb/flexspan --embed unb-slidesor, from a local copy of this repository (packages only the filter, not the test files):
./embed.sh ~/quarto/extensions/unb-slides unb-slidesThen list it among the host extension's filters, in its _extension.yml:
contributes:
formats:
revealjs:
filters:
- flexspanThe filter does nothing in documents without a flexspan: metadata key, so it
is safe to include by default. Run embed.sh again to update the embedded copy.
Copy _extensions/flexspan/flexspan.lua to ~/.pandoc/filters (or anywhere
else) and run:
pandoc -s doc.md -t html -L flexspan.lua
pandoc -s doc.md -o doc.docx --lua-filter=flexspan.luaPandoc 3.0 or later is required.
These rules work without any metadata (since version 2.2; ++ since 2.3):
| Write | Result |
|---|---|
!!text!! |
red, bold |
==text== |
yellow background |
++text++ |
sea green (#2e8b57), bold |
%[ls -la] |
inline code, like backticks |
-=text=-(blue) |
no style of its own: the style is given as options, e.g. -=text=-(white, bg=navy, bold) |
-=text=-r =-g =-b =-c =-p =-o |
shortcuts: bold red, green, blue, aqua, purple, orange |
+-text-+ |
underline |
!-text-! |
strike-out, grey |
((text)) |
class note (HTML) / character style (Word), blue italic |
Your own rules are added to these. A rule with the same left and
right delimiters as a built-in one replaces it completely (keys are not
merged), so this makes !! blue and not bold:
flexspan:
- left: "!!"
color: blueThe same holds between layers: a format's rules (for example from an
extension such as unb-slides) replace the built-in ones, and the rules of the
project (_quarto.yml) and of the document replace those of the format. The
last definition wins.
To remove one rule, repeat its delimiters with disable: true; to remove all
built-in rules, set flexspan-defaults: false:
flexspan-defaults: false # no built-in rules at all
flexspan:
- left: "(("
right: "))"
disable: true # or remove just this oneEvery entry of the flexspan list is a rule. A rule always has a left
delimiter; right defaults to the same string.
Give the rule one or more style keys. They work in every output format.
| Key | Value |
|---|---|
color |
text colour |
bg |
background colour |
bold |
true / false |
italic |
true / false |
underline |
true / false |
strike |
true / false |
code |
true / false: inline code, like backticks |
flexspan:
- left: "!!"
color: red
- left: "=="
bg: yellow
- left: "(("
right: "))"
color: "#1e90ff"
bold: true!!red!!, ==highlighted==, ((blue and bold)), !!red ==and highlighted== red!!A rule with no style at all takes its colour where it is used. Options are written in parentheses right after the closing delimiter:
flexspan:
- left: "-="
right: "=-"-=green=-(green) -=white on navy=-(white, bg=navy) -=loud=-(orange, bold) -=hex=-(#8a2be2)In the options of a styled rule a bare word is the text colour; color=,
bg=, bold, italic, underline, strike and code are also understood.
Options given in the text replace the rule's default opts; they are applied
on top of the rule's style keys.
code: true gives a placeholder that behaves like backticks. The closing
delimiter can be a single character:
flexspan:
- left: "%["
right: "]"
code: trueRun %[ls -la] and then %[git status].code combines with the other style keys and can be given as an option:
-=text=-(code, bg=gold).
Unlike real backticks, the text is read by Markdown first, so it is not fully
verbatim: %[a*b*c] loses its asterisks and %[x[1]] ends at the first ].
Typographic quotes, dashes and ellipses are turned back into ", -- and
.... Other placeholders are not applied inside. Use real backticks for code
that contains Markdown characters.
Use a CSS colour name
(red, DodgerBlue, darkgreen, …) or a hex value (#f00, #1e90ff). These
are converted for each format, so the colour is identical in HTML, PDF, Typst
and Word.
Anything else is passed on unchanged, which lets you use format specific
colours when you only target one format: red!30 or Cerulean (LaTeX
xcolor), luma(80) (Typst), rgb(0 0 0 / 50%) (CSS). Word accepts only CSS
names and hex values; other colours are ignored there, with a warning.
With command the text is handed to something you define yourself.
flexspan:
- left: "%%"
command: custombox
opts: orange # optional default options%%boxed%% and %%boxed%%(lime)| Output | Result | You provide |
|---|---|---|
| LaTeX, beamer | \custombox[lime]{boxed} |
the LaTeX command |
| Typst | #custombox("lime")[boxed]; |
the Typst function |
| HTML, revealjs | <span class="custombox" data-lime="">boxed</span> |
CSS for .custombox |
| Word | text with character style custombox |
the style, in the reference document |
Options of a named rule are passed to the command untouched:
- LaTeX: exactly as typed, as the optional argument:
(fg=red,scale=2)→\cmd[fg=red,scale=2]{…}. - Typst: bare words become positional strings and
key=valuenamed strings:(lime, scale=2)→#cmd("lime", scale: "2")[…]. - HTML:
key=valuebecomesdata-key="value", a bare word becomes an emptydata-wordattribute. Select them in CSS with.cmd[data-lime]or.cmd[data-fg="red"].
Example definitions for the rule above:
format:
html:
css: styles.css # .custombox { background: orange } .custombox[data-lime] { background: lime }
pdf:
include-in-header:
- text: |
\newcommand{\custombox}[2][orange]{\colorbox{#1}{#2}}
typst:
include-in-header:
- text: |
#let custombox(..args, body) = box(
fill: eval(args.pos().at(0, default: "orange")),
inset: (x: 3pt), outset: (y: 3pt), body)A LaTeX command used this way must take one optional and one mandatory
argument (\newcommand{\name}[2][default]{…}).
Important
A command must exist in every format you render to. An undefined command
stops LaTeX and Typst with an error. HTML and Word simply show plain text.
Use class instead of command when you only want a hook for CSS (or a Word
character style) and no LaTeX/Typst command. It combines with style keys:
- left: "(("
right: "))"
class: note # <span class="note" style="color: #1e90ff;">
color: "#1e90ff" # plain coloured text in LaTeX and TypstHand-written spans work too, for any class that is the command of a rule:
[text]{.hl fg=red} gives \hl[fg=red]{text} in LaTeX and
#hl(fg: "red")[text]; in Typst. (Pandoc's span syntax only accepts
key=value attributes, not bare words.)
| Key | Aliases | Meaning |
|---|---|---|
left |
pre, before, open |
opening delimiter (required) |
right |
pos, post, after, close |
closing delimiter (default: same as left) |
color |
fg |
text colour |
bg |
background |
background colour |
bold, italic, underline, strike |
true / false |
|
code |
true / false: inline code, like backticks |
|
command |
cmd |
LaTeX command / Typst function; also used as class |
class |
HTML class / Word character style | |
opts |
opt, options |
default options |
content |
contents, val, arg |
fixed content; the enclosed text is discarded |
exact |
single, one, join, contiguous |
the delimiters are written together, with no content |
disable |
disabled, off |
true: remove the rule with these delimiters (built-in rules) |
latex, html, typst, docx, beamer, revealjs |
map of the keys above, used for that output format only (format blocks) |
Unknown keys and missing delimiters are reported on the terminal
([flexspan] rule #3: unknown key 'comand' ignored). A repeated delimiter
pair is not an error: the later rule replaces the earlier one.
exact rules match the two delimiters written together. They are meant for
symbols and icons:
flexspan:
- left: "-"
right: "\\>"
command: iconarrow
exact: true-> next step → \iconarrow{} next step
->(fg=red) alert → \iconarrow[fg=red]{} alertcontent replaces whatever is enclosed with a fixed text.
A LaTeX command such as \iconbullet means nothing in HTML or Word. A rule
can therefore hold a block named after an output format; the keys inside it
replace those of the rule when rendering to that format:
flexspan:
- left: "::"
right: ":*"
exact: true
content: "●" # every format ...
color: navy
latex: # ... except LaTeX and beamer: \iconbullet{}
command: iconbullet
content: ""
color: ""
- left: "!!"
command: hlred # LaTeX command, Typst function, Word style
html: # HTML: no class, plain styling instead
command: ""
color: red
bold: true| Block | Applies to |
|---|---|
latex, typst, docx |
that output family (latex includes beamer / pdf) |
html |
every other format (html, revealjs, epub, ...) |
beamer, revealjs |
that writer only, on top of latex / html |
- A block accepts every key except the delimiters and
exact: what is matched is the same in all formats. - An empty value removes
command,class,opts,colororbg;content: ""means "no content"; booleans are switched off withfalse. - Blocks for other formats are ignored.
flexspan has no dependencies: it never needs another extension, and nothing
below is required to use it. It combines well, however, with
fontawesome-raw, a separate Quarto extension installed on its own: a
filter that turns raw FontAwesome glyph characters into real icons. Used
together, a short symbol such as ::v becomes an icon:
filters:
- flexspan # first: writes the glyph
- fontawesome-raw # second: turns the glyph into an icon
flexspan:
- left: "::"
right: "v"
exact: true
content: "\uf00c" # FontAwesome "check"
- left: "::"
right: "!"
exact: true
content: "\uf071" # FontAwesome "triangle-exclamation"
color: crimsonDone ::v Careful ::! A green check: ::v(green)The glyph is written as a YAML escape ("\uf00c", double quotes required) or
pasted as the character itself; the code of each icon is its "Unicode" value
on fontawesome.com.
What you get:
| Output | Result |
|---|---|
| HTML, revealjs | <i class="fa-solid fa-check">, FontAwesome CSS loaded |
| LaTeX, beamer (pdf) | \faIcon{check}, package fontawesome6 loaded |
| Typst, Word | not handled by fontawesome-raw: the raw glyph is left as is |
Things to know:
-
Order matters.
flexspanmust be listed beforefontawesome-raw. The other way round the icons disappear: fontawesome-raw converts the glyph inside the rule itself before flexspan reads it. -
Colours.
color,bgand inline options (::v(green)) are applied by flexspan around the icon. This needs fontawesome-raw 1.0.1 or later; version 1.0.0 drops the colour. -
Typst and Word. Give those formats something they can show with a format block:
- left: "::" right: "v" exact: true content: "\uf00c" typst: { content: "✔" } docx: { content: "✔" }
-
Without fontawesome-raw the same rules still match, but the glyph is a private-use character that shows as an empty box. Use ordinary characters (
content: "✔","→","⚠") when you do not want the second filter. -
Embedding. An extension that ships such rules must embed both filters (see Inside another extension) and list them in that order.
Placeholders are recognised anywhere inline text occurs: paragraphs, headings, lists, table cells, captions, footnotes, and inside bold, emphasis, links and other spans. They can be nested, and the enclosed text can contain any inline formatting.
Rules of the game:
- Same block. Both delimiters must be in the same paragraph (or heading, cell, …).
- Same level. A placeholder cannot start outside bold/emphasis and end
inside it:
!!red **bold!! text**is left alone; write!!red **bold**!! **text**. - Word boundaries. An opening delimiter must not follow a letter or digit;
a closing delimiter must not be followed by one.
Wow!! Great!!is therefore not a placeholder, while(!!this!!),is. - Nearest closing delimiter wins. Several rules may share the same
leftwith differentrightdelimiters (::…:o,::…:#). At the same position the longest delimiter wins, so---is tried before--. - Options must touch the closing delimiter:
!!text!!(blue), not!!text!! (blue). They may contain spaces. - Code and math are never touched. To protect ordinary text, put it in a
span or div with the class
skipspan:[!!literal!!]{.skipspan}. - The document title and other metadata are not processed.
Delimiters are read by pandoc's Markdown parser before the filter sees them, both in the metadata and in the text. Some characters therefore cannot work:
| Avoid | Because |
|---|---|
[[text]](opts), [-x-](opts) |
[…](…) is a Markdown link. Brackets are fine without options |
<<text>> |
<text> is read as an HTML tag |
@@text@@ |
@text is a citation |
**, __, ~~, ^, `, $ |
Markdown emphasis, strikeout, superscript, code, math |
" and ' |
turned into typographic quotes |
Good choices are pairs of punctuation such as !!, ==, %%, ++, ::,
-= … =-, +: … :+, (( … )).
A delimiter that is Markdown syntax on its own must be escaped in the YAML
with two backslashes: right: "\\>", left: "\\<". The filter warns when a
delimiter turns out empty.
-- and --- work as delimiters even though pandoc converts them to dashes,
because the metadata is converted the same way.
| Format | Colour / background | bold, italic, … | command |
class |
|---|---|---|---|---|
| HTML, revealjs, epub | style="color: …; background-color: …" |
native | span class | span class |
| LaTeX, beamer (PDF) | \textcolor, \colorbox (xcolor) |
native | \command[…]{…} |
span (no effect) |
| Typst | #text(fill: …), #highlight(fill: …) |
native | #command(…)[…] |
no effect |
| Word (docx) | run colour and shading | native | character style | character style |
| other (odt, pptx, …) | not supported | native | no effect | no effect |
Notes:
- LaTeX:
\colorboxdoes not break across lines; keep highlighted passages short. xcolor is loaded by the default pandoc and Quarto templates. - Word: colours are written directly into the text runs, so no reference document is needed. Named rules use a character style with the rule's name; pandoc creates it empty, and you can give it a look in your reference document.
- New built-in rule
++text++: sea green, bold. "C++" is not affected: an opening delimiter right after a letter is not matched.
- Built-in rules:
!!,==,%[ ],-= =-with the colour shortcuts=-r…=-o,+- -+,!- -!and(( ))work without metadata. Turn them off withflexspan-defaults: false. - A rule with the same delimiters as an earlier one now replaces it (it used to be ignored with a warning). The document has the last word.
disable: trueremoves a rule.
- Format blocks: a rule can have different keys for each
output format (
latex,html,typst,docx,beamer,revealjs).
- Placeholders are found inside bold, emphasis, links, headings and every other inline container, not only at the top level of paragraphs.
- New style keys
color,bg,bold,italic,underline,strike, with native output for HTML, LaTeX, Typst and Word. commandis no longer required.classis no longer an alias ofcommand: it sets the HTML class only and never produces a LaTeX command.commandnow also produces a function call in Typst.- Options keep the order in which they were typed and may contain spaces.
- Delimiters next to letters or digits are no longer matched.
exact: falseis honoured (any value used to mean true).- Nothing is printed on standard output any more; problems in the metadata are reported on standard error.
template.qmdis a short starting point.showcase.qmddemonstrates every feature and renders to HTML, revealjs, Word, Typst and LaTeX/PDF. README-render.md explains how to render each format and what each one needs../render-all.shrenders the showcase to all formats and checks the results.
quarto render showcase.qmdProf. Georgios Pappas Jr
Computational Genomics group
University of Brasilia (UnB) - Brazil