markdown.dtx

% \iffalse
%<*driver>
\documentclass{ltxdockit}
\usepackage[american]{babel}
\usepackage{amsmath,btxdockit,doc,fancyvrb,graphicx,hologo,microtype,minted}

% Set up the style.
\usepackage{xcolor}
\definecolor{spot}{rgb}{0,0.2,0.6}
\usepackage{fontspec}
\defaultfontfeatures[\rmfamily,\sffamily,\ttfamily]{}
\emergencystretch=1em
\fvset{gobble=0,frame=single}
\setcounter{secnumdepth}{4}
\addtokomafont{title}{\sffamily}
\addtokomafont{paragraph}{\spotcolor}
\addtokomafont{section}{\spotcolor}
\addtokomafont{subsection}{\spotcolor}
\addtokomafont{subsubsection}{\spotcolor}
\addtokomafont{descriptionlabel}{\spotcolor}
\setkomafont{caption}{\bfseries\sffamily\spotcolor}
\setkomafont{captionlabel}{\bfseries\sffamily\spotcolor}
\hypersetup{citecolor=spot}
\let\oldCodelineNo\theCodelineNo
\def\theCodelineNo{\textcolor[gray]{0.5}{\oldCodelineNo}}
\makeatletter\renewcommand\fps@figure{htbp}\makeatother
\setkeys{Gin}{
  width = \columnwidth,
  height = 0.65\paperheight,
  keepaspectratio,
}

% Define some markup.
\let\pkg\relax % A package name
\def\inline#1{% Inline code
  \textcolor{spot}{\text{\texttt{#1}}}}
\newcommand\acro[1]{% An acronym
  \textsc{\MakeLowercase{#1}}}

% Set up index.
\DisableCrossrefs
\usepackage{makeidx}
\usepackage[columns=1, totoc]{idxlayout}
\makeindex

\newcommand\mdef[1]{% A TeX macro definition
  \index{#1@\cs{#1}|textit}%
  \phantomsection\label{macro:#1}\textcolor{spot}{\cs{#1}}}
\newcommand\mref[1]{% A TeX macro reference
  \index{#1@\cs{#1}}%
  \hyperref[macro:#1]{\textcolor{spot}{\cs{#1}}}}

\newcommand\envmdef[1]{% A LaTeX environment definition
  \index{#1@\texttt{#1}|textit}%
  \phantomsection\label{environment:#1}\inline{#1}}
\newcommand\envmref[1]{% A LaTeX environment reference
  \index{#1@\texttt{#1}}%
  \hyperref[environment:#1]{\inline{#1}}}

\newcommand\luamdef[1]{% A Lua object / method definition
  \index{#1@\texttt{#1}|textit}%
  \phantomsection\label{lua:#1}\inline{#1}}
\newcommand\luamref[1]{% A Lua object / method reference
  \index{#1@\texttt{#1}}%
  \hyperref[lua:#1]{\inline{#1}}}

\newcommand\Optitem[2][]{\penalty -1000\relax % An option item definition
  \index{#2@\texttt{#2}|textit}%
  \phantomsection\label{opt:#2}\optitem[#1]{#2}}
\newcommand\Valitem[2][]{\penalty -1000\relax % A value item definition
  \index{#2@\texttt{#2}}%
  \phantomsection\label{opt:#2}\valitem[#1]{#2}}
\newcommand\Opt[1]{% An option / value item reference
  \index{#1@\texttt{#1}}%
  \hyperref[opt:#1]{\inline{#1}}}

% Set up markdown.
\usepackage[
  citations,
  definitionLists,
  fencedCode,
  notes,
  headerAttributes,
  html,
  hybrid,
  inlineNotes,
  jekyllData,
  relativeReferences,
  stripPercentSigns,
  underscores = false,
  theme = witiko/dot,
  theme = witiko/graphicx/http,
  theme = witiko/markdown/techdoc,
]{markdown}

% Set up Unicode characters.
\usepackage{newunicodechar}
\newunicodechar{☒}{\markdownRendererTickedBox}
\newunicodechar{⌛}{\markdownRendererHalfTickedBox}
\newunicodechar{☐}{\markdownRendererUntickedBox}
\usepackage{emoji}
\makeatletter
\@ifpackagelater{emoji}{2020/03/16}{
  \newunicodechar{😉}{\emoji{winking-face}}
}{
  \newunicodechar{😉}{;-)}
}
\makeatother

% Set up the catcodes.
\catcode`\_=12 % We won't be typesetting much math and Lua contains lots of `_`.
\catcode`\^^B=8 % When we occasionally need subscripts, we will use `^^B` (STX).

% Set up the title page.
\begin{markdown}
---
title:    A Markdown Interpreter for \TeX
url:      https://github.com/witiko/markdown
authors:  [Vít Novotný]
email:    witiko@mail.muni.cz
revision: \markdownVersion
date:     \markdownLastModified
---
\end{markdown}
\CodelineIndex

% Set up the figures.
\usepackage{tikz}
\usepackage{mathabx,pgf-umlsd,tikz}
\usetikzlibrary{automata,arrows.meta,positioning,shapes.geometric}

% Set up the bibliography.
\usepackage[
  backend=biber,
  style=numeric,
  sorting=none,
  autolang=other,
  sortlocale=auto]{biblatex}
\addbibresource{markdown.bib}

\begin{document}
\DocInput{markdown.dtx}
\printbibliography[heading=bibintoc]
\printindex
\end{document}
%</driver>
%<*manual-css>

html {
  font-size: 100%;
  overflow-y: scroll;
  -webkit-text-size-adjust: 100%;
  -ms-text-size-adjust: 100%;
}

body {
  color: #444;
  font-family: Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif;
  font-size: 12px;
  line-height: 1.7;
  padding: 1em;
  margin: auto;
  max-width: 42em;
  background: #fefefe;
}

a {
  color: #0645ad;
}

a:visited {
  color: #0b0080;
}

a:hover {
  color: #06e;
}

a:active {
  color: #faa700;
}

a:focus {
  outline: thin dotted;
}

*::-moz-selection {
  background: rgba(255, 255, 0, 0.3);
  color: #000;
}

*::selection {
  background: rgba(255, 255, 0, 0.3);
  color: #000;
}

a::-moz-selection {
  background: rgba(255, 255, 0, 0.3);
  color: #0645ad;
}

a::selection {
  background: rgba(255, 255, 0, 0.3);
  color: #0645ad;
}

p {
  margin: 1em 0;
}

img {
  max-width: 100%;
}

h1, h2, h3, h4, h5, h6 {
  color: #111;
  line-height: 125%;
  margin-top: 2em;
  font-weight: normal;
}

h4, h5, h6 {
  font-weight: bold;
}

h1 {
  font-size: 2.5em;
}

h2 {
  font-size: 2em;
}

h3 {
  font-size: 1.5em;
}

h4 {
  font-size: 1.2em;
}

h5 {
  font-size: 1em;
}

h6 {
  font-size: 0.9em;
}

blockquote {
  color: #666666;
  margin: 0;
  padding-left: 3em;
  border-left: 0.5em #EEE solid;
}

hr {
  display: block;
  height: 2px;
  border: 0;
  border-top: 1px solid #aaa;
  border-bottom: 1px solid #eee;
  margin: 1em 0;
  padding: 0;
}

pre, code, kbd, samp {
  color: #000;
  font-family: monospace, monospace;
  _font-family: 'courier new', monospace;
  font-size: 0.98em;
}

pre {
  white-space: pre;
  white-space: pre-wrap;
  word-wrap: break-word;
}

b, strong {
  font-weight: bold;
}

dfn {
  font-style: italic;
}

ins {
  background: #ff9;
  color: #000;
  text-decoration: none;
}

mark {
  background: #ff0;
  color: #000;
  font-style: italic;
  font-weight: bold;
}

sub, sup {
  font-size: 75%;
  line-height: 0;
  position: relative;
  vertical-align: baseline;
}

sup {
  top: -0.5em;
}

sub {
  bottom: -0.25em;
}

ul, ol {
  margin: 1em 0;
  padding: 0 0 0 2em;
}

li p:last-child {
  margin-bottom: 0;
}

ul ul, ol ol {
  margin: .3em 0;
}

dl {
  margin-bottom: 1em;
}

dt {
  font-weight: bold;
  margin-bottom: .8em;
}

dd {
  margin: 0 0 .8em 2em;
}

dd:last-child {
  margin-bottom: 0;
}

img {
  border: 0;
  -ms-interpolation-mode: bicubic;
  vertical-align: middle;
}

figure {
  display: block;
  text-align: center;
  margin: 1em 0;
}

figure img {
  border: none;
  margin: 0 auto;
}

figcaption {
  font-size: 0.8em;
  font-style: italic;
  margin: 0 0 .8em;
}

table {
  margin-bottom: 2em;
  border-bottom: 1px solid #ddd;
  border-right: 1px solid #ddd;
  border-spacing: 0;
  border-collapse: collapse;
}

table th {
  padding: .2em 1em;
  background-color: #eee;
  border-top: 1px solid #ddd;
  border-left: 1px solid #ddd;
}

table td {
  padding: .2em 1em;
  border-top: 1px solid #ddd;
  border-left: 1px solid #ddd;
  vertical-align: top;
}

.author {
  font-size: 1.2em;
  text-align: center;
}

@media only screen and (min-width: 480px) {
  body {
    font-size: 14px;
  }
}
@media only screen and (min-width: 768px) {
  body {
    font-size: 16px;
  }
}
@media print {
  * {
    background: transparent !important;
    color: black !important;
    filter: none !important;
    -ms-filter: none !important;
  }

  body {
    font-size: 12pt;
    max-width: 100%;
  }

  a, a:visited {
    text-decoration: underline;
  }

  hr {
    height: 1px;
    border: 0;
    border-bottom: 1px solid black;
  }

  a[href]:after {
    content: " (" attr(href) ")";
  }

  abbr[title]:after {
    content: " (" attr(title) ")";
  }

  .ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after {
    content: "";
  }

  pre, blockquote {
    border: 1px solid #999;
    padding-right: 1em;
    page-break-inside: avoid;
  }

  tr, img {
    page-break-inside: avoid;
  }

  img {
    max-width: 100% !important;
  }

  @page :left {
    margin: 15mm 20mm 15mm 10mm;
}

  @page :right {
    margin: 15mm 10mm 15mm 20mm;
}

  p, h2, h3 {
    orphans: 3;
    widows: 3;
  }

  h2, h3 {
    page-break-after: avoid;
  }
}

.tex sub, .latex sub, .latex sup {
  text-transform: uppercase;
}

.tex sub, .latex sub {
  vertical-align: -0.1ex;
  margin-left: -0.1667em;
  margin-right: -0.125em;
}

.tex, .latex, .tex sub, .latex sub {
  font-size: 1em;
}

.latex sup {
  font-size: 0.85em;
  vertical-align: -0.35em;
  margin-left: -0.36em;
  margin-right: -0.15em;
}

abbr {
  text-transform: lowercase;
  font-variant: small-caps;
}

%</manual-css>
%<*techdoc-block-diagram>
\begingroup
\ifx\du\undefined\newlength{\du}\fi
\setlength{\du}{15\unitlength}
\begin{tikzpicture}
\pgftransformxscale{1.000000}
\pgftransformyscale{-1.23800}
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000}
\pgfsetfillcolor{dialinecolor}
\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000}
\pgfsetfillcolor{dialinecolor}
\fill (4.282853\du,-3.750000\du)--(4.282853\du,-1.850000\du)--(11.971656\du,-1.850000\du)--(11.971656\du,-3.750000\du)--cycle;
\pgfsetlinewidth{0.040000\du}
\pgfsetdash{}{0pt}
\pgfsetdash{}{0pt}
\pgfsetmiterjoin
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\draw (4.282853\du,-3.750000\du)--(4.282853\du,-1.850000\du)--(11.971656\du,-1.850000\du)--(11.971656\du,-3.750000\du)--cycle;
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\node at (8.127254\du,-2.705000\du){\LaTeX{} layer};
\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000}
\pgfsetfillcolor{dialinecolor}
\fill (-5.055135\du,-3.788555\du)--(-5.055135\du,-1.888555\du)--(2.894865\du,-1.888555\du)--(2.894865\du,-3.788555\du)--cycle;
\pgfsetlinewidth{0.040000\du}
\pgfsetdash{}{0pt}
\pgfsetdash{}{0pt}
\pgfsetmiterjoin
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\draw (-5.055135\du,-3.788555\du)--(-5.055135\du,-1.888555\du)--(2.894865\du,-1.888555\du)--(2.894865\du,-3.788555\du)--cycle;
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\node at (-1.080135\du,-2.743555\du){\Hologo{ConTeXt} layer};
\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000}
\pgfsetfillcolor{dialinecolor}
\fill (-8.200000\du,-0.224996\du)--(-8.200000\du,1.675004\du)--(11.870000\du,1.675004\du)--(11.870000\du,-0.224996\du)--cycle;
\pgfsetlinewidth{0.040000\du}
\pgfsetdash{}{0pt}
\pgfsetdash{}{0pt}
\pgfsetmiterjoin
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\draw (-8.200000\du,-0.224996\du)--(-8.200000\du,1.675004\du)--(11.870000\du,1.675004\du)--(11.870000\du,-0.224996\du)--cycle;
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\node at (1.835000\du,0.820004\du){Plain \TeX{} layer};
\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000}
\pgfsetfillcolor{dialinecolor}
\fill (-11.150000\du,3.325006\du)--(-11.150000\du,5.225006\du)--(11.800000\du,5.225006\du)--(11.800000\du,3.325006\du)--cycle;
\pgfsetlinewidth{0.040000\du}
\pgfsetdash{}{0pt}
\pgfsetdash{}{0pt}
\pgfsetmiterjoin
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\draw (-11.150000\du,3.325006\du)--(-11.150000\du,5.225006\du)--(11.800000\du,5.225006\du)--(11.800000\du,3.325006\du)--cycle;
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\node at (0.325000\du,4.370006\du){Lua layer};
\pgfsetlinewidth{0.040000\du}
\pgfsetdash{}{0pt}
\pgfsetdash{}{0pt}
\pgfsetbuttcap
{
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetfillcolor{dialinecolor}
\pgfsetarrowsstart{stealth}
\pgfsetarrowsend{stealth}
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\draw (-9.906400\du,-5.181570\du)--(-9.937836\du,3.024193\du);
}
\pgfsetlinewidth{0.040000\du}
\pgfsetdash{}{0pt}
\pgfsetdash{}{0pt}
\pgfsetbuttcap
{
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetfillcolor{dialinecolor}
\pgfsetarrowsstart{stealth}
\pgfsetarrowsend{stealth}
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\draw (-6.919693\du,-5.181570\du)--(-6.938734\du,-0.450800\du);
}
\pgfsetlinewidth{0.040000\du}
\pgfsetdash{}{0pt}
\pgfsetdash{}{0pt}
\pgfsetbuttcap
{
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetfillcolor{dialinecolor}
\pgfsetarrowsstart{stealth}
\pgfsetarrowsend{stealth}
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\draw (-1.063746\du,-5.175791\du)--(-1.063746\du,-3.975793\du);
}
\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000}
\pgfsetfillcolor{dialinecolor}
\fill (-10.972500\du,-7.267480\du)--(-10.972500\du,-5.367480\du)--(11.977500\du,-5.367480\du)--(11.977500\du,-7.267480\du)--cycle;
\pgfsetlinewidth{0.040000\du}
\pgfsetdash{}{0pt}
\pgfsetdash{}{0pt}
\pgfsetmiterjoin
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\draw (-10.972500\du,-7.267480\du)--(-10.972500\du,-5.367480\du)--(11.977500\du,-5.367480\du)--(11.977500\du,-7.267480\du)--cycle;
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\node at (0.502500\du,-6.322480\du){User code};
\pgfsetlinewidth{0.040000\du}
\pgfsetdash{}{0pt}
\pgfsetdash{}{0pt}
\pgfsetbuttcap
{
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetfillcolor{dialinecolor}
\pgfsetarrowsstart{stealth}
\pgfsetarrowsend{stealth}
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\draw (8.149986\du,-5.159541\du)--(8.149986\du,-3.959543\du);
}
\pgfsetlinewidth{0.040000\du}
\pgfsetdash{}{0pt}
\pgfsetdash{}{0pt}
\pgfsetbuttcap
{
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetfillcolor{dialinecolor}
\pgfsetarrowsstart{stealth}
\pgfsetarrowsend{stealth}
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\draw (-1.074995\du,-1.634548\du)--(-1.074995\du,-0.434550\du);
}
\pgfsetlinewidth{0.040000\du}
\pgfsetdash{}{0pt}
\pgfsetdash{}{0pt}
\pgfsetbuttcap
{
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetfillcolor{dialinecolor}
\pgfsetarrowsstart{stealth}
\pgfsetarrowsend{stealth}
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\draw (8.138736\du,-1.618298\du)--(8.138736\du,-0.418300\du);
}
\pgfsetlinewidth{0.040000\du}
\pgfsetdash{}{0pt}
\pgfsetdash{}{0pt}
\pgfsetbuttcap
{
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetfillcolor{dialinecolor}
\pgfsetarrowsstart{stealth}
\pgfsetarrowsend{stealth}
\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000}
\pgfsetstrokecolor{dialinecolor}
\draw (1.689638\du,1.881695\du)--(1.689638\du,3.081693\du);
}
\end{tikzpicture}
\endgroup
%</techdoc-block-diagram>
%<*techdoc-bibliography>
@book{tantau21,
  author    = {Till Tantau and Joseph Wright and Vedran Miletić},
  title     = {The Beamer class},
  date      = {2021-02-10},
  url       = {https://mirrors.ctan.org/macros/latex/contrib/beamer/doc/beameruserguide.pdf},
  urldate   = {2021-02-11}}
@online{sotkov17,
  author    = {Sotkov, Anton},
  title     = {File transclusion syntax for Markdown},
  date      = {2017-01-19},
  url       = {https://github.com/iainc/Markdown-Content-Blocks},
  urldate   = {2018-01-08}}
@book{luatex21,
  author    = {{Lua\TeX{} development team}},
  title     = {Lua\TeX{} reference manual},
  date      = {2021-07-23},
  note      = {Version 1.10 (stable)},
  url       = {https://www.pragma-ade.com/general/manuals/luatex.pdf},
  urldate   = {2022-09-30}}
@book{latex17,
  author    = {Braams, Johannes and Carlisle, David and Jeffrey, Alan and
               Lamport, Leslie and Mittelbach, Frank and Rowley, Chris and
               Schöpf, Rainer},
  title     = {The \Hologo{LaTeX2e} Sources},
  date      = {2017-04-15},
  url       = {https://mirrors.ctan.org/macros/latex/base/source2e.pdf},
  urldate   = {2018-01-08}}
@book{mittelbach17,
  author    = {Mittelbach, Frank},
  title     = {The \texttt{doc} and \texttt{shortvrb} Packages},
  date      = {2017-04-15},
  url       = {https://mirrors.ctan.org/macros/latex/base/doc.pdf},
  urldate   = {2018-02-19}}
@book{poore17,
  author    = {Poore, Geoffrey M.},
  title     = {The \texttt{minted} Package},
  subtitle  = {Highlighted source code in \LaTeX},
  date      = {2017-07-19},
  version   = {v2.5},
  url       = {https://mirrors.ctan.org/macros/latex/contrib/minted/minted.pdf},
  urldate   = {2020-09-01}}
@online{macfarlane22,
  title     = {Pandoc},
  subtitle  = {a universal document converter},
  author    = {John MacFarlane},
  year      = {2022},
  url       = {https://pandoc.org/},
  urldate   = {2022-10-05}}
@online{novotny15,
  author    = {Novotný, Vít},
  year      = {2015},
  title     = {TeXový interpret jazyka Markdown (markdown.sty)},
  location  = {Brno, Czech Republic},
  publisher = {Masaryk University},
  url       = {https://www.muni.cz/en/research/projects/32984},
  urldate   = {2018-02-19}}
@book{ierusalimschy13,
  author    = {Ierusalimschy, Roberto},
  year      = {2013},
  title     = {Programming in Lua},
  edition   = {3},
  isbn      = {978-85-903798-5-0},
  pagetotal = {xviii, 347},
  location  = {Rio de Janeiro},
  publisher = {PUC-Rio}}
@book{knuth86a,
  author    = {Knuth, Donald Ervin},
  year      = {1986},
  title     = {The \TeX{}book},
  edition   = {3},
  isbn      = {0-201-13447-0},
  pagetotal = {ix, 479},
  series    = {Computers \& Typesetting},
  volume    = {A},
  location  = {Reading, MA},
  publisher = {Addison-Wesley}}
@book{knuth86b,
  author    = {Knuth, Donald Ervin},
  year      = {1986},
  title     = {\TeX: The Program},
  isbn      = {0-201-13437-7},
  pagetotal = {xvi, 594},
  series    = {Computers \& Typesetting},
  volume    = {B},
  location  = {Reading, MA},
  publisher = {Addison-Wesley}}
@online{novotny21,
  author    = {Novotný, Vít},
  title     = {\Hologo{LaTeX2e} no longer keys packages by pathnames},
  date      = {2021-02-20},
  url       = {https://github.com/latex3/latex2e/issues/510},
  urldate   = {2021-02-21}}
@book{eijkhout92,
  author    = {Victor Eijkhout},
  title     = {\TeX{} by Topic},
  subtitle  = {A \TeX nician's Reference},
  isbn      = {0-201-56882-0},
  pagetotal = {307},
  date      = {1992-02-01},
  location  = {Wokingham, England},
  publisher = {Addison-Wesley}}
@inproceedings{sharif10,
  author    = {Sharif, Bonita and Maletic, Jonathan I.},
  booktitle = {2010 IEEE 18th International Conference on Program Comprehension},
  title     = {An Eye Tracking Study on camelCase and under\_score Identifier Styles},
  year      = {2010},
  pages     = {196-205},
  doi       = {10.1109/ICPC.2010.41}}
%</techdoc-bibliography>
%<*latex-themes-witiko-markdown-techdoc>
\ProvidesPackage{markdownthemewitiko_markdown_techdoc}[2022/02/23]
\RequirePackage{etoolbox}
\markdownSetup{
  rendererPrototypes = {
    codeSpan = {\inline{#1}},
    headingFour = {%
      \paragraph{#1}\leavevmode
      \def\markdownRendererInterblockSeparator{%
        \let\markdownRendererInterblockSeparator\par
      }%
      \noindent
    },
    jekyllDataEnd = {%
      \AfterEndPreamble{%
        \printtitlepage
        \tableofcontents
        {\def\addcontentsline##1##2##3{}\listoffigures}%
      }%
    },
    headerAttributeContextBegin = {
      \markdownSetup{
        rendererPrototypes = {
          attributeIdentifier = {%
            \begingroup
            \def\next####1{%
              \def####1########1{%
                \endgroup
                ####1{########1}%
                \label{sec:##1}%
              }%
            }%
            \next\markdownRendererHeadingOne
            \next\markdownRendererHeadingTwo
            \next\markdownRendererHeadingThree
            \next\markdownRendererHeadingFour
            \next\markdownRendererHeadingFive
            \next\markdownRendererHeadingSix
          },
        },
      }%
    },
  },
  jekyllDataRenderers = {
    /authors/* = {%
      \gdef\ltd@title@author{#1}%
      \hypersetup{pdfauthor={#1}}%
    },
    title = {%
      \gdef\ltd@title@title{#1}%
      \gdef\ltd@title@subtitle{}%
      \hypersetup{pdftitle={#1}}%
    },
    date = {\gdef\ltd@title@date{#1}},
    email = {\gdef\ltd@title@email{#1}},
    revision = {\gdef\ltd@title@revision{#1}},
    url = {\gdef\ltd@title@url{#1}},
  }
}
\renewcommand\markdownLaTeXRendererDirectOrIndirectLink[4]{%
  #1\footnote{See \url{#3}.}}
\RequirePackage{varioref}
\vrefwarning
\markdownSetupSnippet{options}{
  rendererPrototypes = {
    dlBegin = {\begin{optionlist}},
    dlItem = {
      #1
      \begingroup
      \markdownSetup{
        renderers = {
          dlBegin = {
            \begingroup
            \markdownSetup{
              renderers = {
                dlItem = {\item[####1]},
                dlItemEnd = {}}}
            \begin{valuelist}
          },
          dlEnd = {
            \end{valuelist}
            \endgroup
          },
        },
      }%
    },
    dlItemEnd = {\endgroup},
    dlEnd = {\end{optionlist}},
  }
}
%</latex-themes-witiko-markdown-techdoc>
%<*manual>

---
title:  Markdown Package User Manual
author: Vít Novotný
date:   \markdownVersion{} \markdownLastModified{}
---

<link href="https://afeld.github.io/emoji-css/emoji.css" rel="stylesheet" />

% \fi
% \par
% \begin{markdown}

Introduction
============
The [Markdown package][pkg] converts [markdown][] markup to \TeX{} commands. The
functionality is provided both as a Lua module and as plain \TeX{}, \LaTeX{}, and
\Hologo{ConTeXt} macro packages that can be used to directly typeset \TeX{} documents
containing markdown markup. Unlike other convertors, the Markdown package
does not require any external programs, and makes it easy to redefine how each
and every markdown element is rendered.  Creative abuse of the markdown
syntax is encouraged. 😉

 [markdown]: https://daringfireball.net/projects/markdown/basics
             (Daring Fireball: Markdown Basics)
 [pkg]:      https://ctan.org/pkg/markdown
             (CTAN: Package markdown)

% This document is a technical documentation for the \pkg{Markdown} package. It
% consists of three sections. This section introduces the package and outlines
% its prerequisites. Section <#sec:interfaces> describes the interfaces
% exposed by the package. Section <#sec:implementation> describes the
% implementation of the package. The technical documentation contains only a
% limited number of tutorials and code examples. You can find more of these in
% the [user manual.][manual]
%
%  [manual]: http://mirrors.ctan.org/macros/generic/markdown/markdown.html
%
% \end{markdown}
% \iffalse

This document is a user manual for the [Markdown package][pkg]. It provides
tutorials and code examples. For an in-depth description of the package
requirements, interfaces, and implementation, please refer to the [technical
documentation][techdoc].

 [techdoc]: http://mirrors.ctan.org/macros/generic/markdown/markdown.pdf
            (A Markdown Interpreter for TeX)

%</manual>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
local metadata = {
    version   = "(((VERSION)))",
    comment   = "A module for the conversion from markdown to plain TeX",
    author    = "John MacFarlane, Hans Hagen, Vít Novotný",
    copyright = {"2009-2016 John MacFarlane, Hans Hagen",
                 "2016-2022 Vít Novotný"},
    license   = "LPPL 1.3c"
}

%    \end{macrocode}
% \iffalse
%</lua,lua-cli>
%<*lua>
% \fi
%  \begin{macrocode}
if not modules then modules = { } end
modules['markdown'] = metadata
%    \end{macrocode}
% \iffalse
%</lua>
%<*manual>

Requirements
------------

The package requires either [our official Docker image][docker], which contains
the latest development version of the Markdown package, or a \TeX{}
distribution: [\TeX{} Live][tl] ≥ 2020 is known to work with the current
version of the Markdown package and so are recent versions of [Mik\TeX{}][mik].
If you are using an older, incomplete, or atypical \TeX{} distribution, please
consult the [technical documentation][techdoc] for a detailed list of
requirements.

 [docker]: https://hub.docker.com/r/witiko/markdown/tags (witiko/markdown - Docker Image)
 [tl]: https://www.tug.org/texlive/ (TeX Live - TeX Users Group)
 [mik]: https://miktex.org/ (Home - MiKTeXorg)

Installation
------------

If Markdown is not included in your \TeX{} distribution, you will need to
install it.

First, download the package from the repository using Git:
``` sh
git clone https://github.com/witiko/markdown
``````
Next, enter the directory named `markdown` and run the `make base` command using
GNU Make:
``` sh
cd markdown
make base
``````
This should produce the following files:

* `markdown.lua`, the Lua module,
* `libraries/markdown-tinyyaml.lua`, an external library for reading \acro{yaml},
* `markdown-cli.lua`, the Lua command-line interface,
* `markdown.tex`, the plain \TeX{} macro package,
* `markdown.sty`, the \LaTeX{} package,
* `markdownthemewitiko_dot.sty`, the `witiko/dot` \LaTeX{} theme,
* `markdownthemewitiko_graphicx_http.sty`, the `witiko/graphicx/http` \LaTeX{} theme,
* `markdownthemewitiko_tilde.sty`, the `witiko/tilde` \LaTeX{} theme, and
* `t-markdown.tex`, the \Hologo{ConTeXt} module.

### Local Installation

To perform a local installation, place the above files into your \TeX{}
directory structure. This is generally where the individual files should be
placed:

* `⟨TEXMF⟩/tex/luatex/markdown/markdown.lua`
* `⟨TEXMF⟩/tex/luatex/markdown/markdown-tinyyaml.lua`
* `⟨TEXMF⟩/scripts/markdown/markdown-cli.lua`
* `⟨TEXMF⟩/tex/generic/markdown/markdown.tex`
* `⟨TEXMF⟩/tex/latex/markdown/markdown.sty`
* `⟨TEXMF⟩/tex/latex/markdown/markdownthemewitiko_dot.sty`
* `⟨TEXMF⟩/tex/latex/markdown/markdownthemewitiko_graphicx_http.sty`
* `⟨TEXMF⟩/tex/latex/markdown/markdownthemewitiko_tilde.sty`
* `⟨TEXMF⟩/tex/context/third/markdown/t-markdown.tex`

where `⟨TEXMF⟩` corresponds to a root of your \TeX{} distribution, such as
`/usr/share/texmf` and `~/texmf` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf` on Windows systems. When in doubt,
consult the manual of your \TeX{} distribution.

### Portable Installation

Alternatively, you can also store the above files in the same folder as your
\TeX{} document and distribute them together. This way your document can be
portably typeset on legacy \TeX{} distributions.

Since Markdown version 2.10.0, the file `markdown.tex` must be placed in
a directory named `markdown` due to [issue #74][issue-74].

 [issue-74]: https://github.com/witiko/markdown/issues/74 (Does not compile if user names own document markdown.tex)

%</manual>
%<*lua>
% \fi
% \par
% \begin{markdown}
%
% Requirements
%-------------
%
% This section gives an overview of all resources required by the package.
%
%### Lua Requirements {#luaprerequisites}
%
% The Lua part of the package requires that the following Lua modules are
% available from within the Lua\TeX{} engine:
%
% \pkg{LPeg${}\geq{}$0.10}
%
%:    A pattern-matching library for the writing of recursive descent parsers
%     via the Parsing Expression Grammars (\acro{peg}s). It is used by the
%     \pkg{Lunamark} library to parse the markdown input.
%     \pkg{LPeg${}\geq{}$0.10} is included in Lua\TeX${}\geq{}$0.72.0 (\TeX
%     Live${}\geq{}2013$).
%
% \end{markdown}
%  \begin{macrocode}
local lpeg = require("lpeg")
%    \end{macrocode}
% \par
% \begin{markdown}
%
% \pkg{Selene Unicode}
%
%:    A library that provides support for the processing of wide strings. It is
%     used by the \pkg{Lunamark} library to cast image, link, and note tags
%     to the lower case. \pkg{Selene Unicode} is included in all releases of
%     Lua\TeX{} (\TeX Live${}\geq{}2008$).
%
% \end{markdown}
%  \begin{macrocode}
local unicode
(function()
  local ran_ok
  ran_ok, unicode = pcall(require, "unicode")
%    \end{macrocode}
% \begin{markdown}
%
% If the Selene Unicode library is unavailable and we are using
% Lua${}\geq{}$5.3, we will use the built-in support for Unicode.
%
% \end{markdown}
%  \begin{macrocode}
  if not ran_ok then
    unicode = {["utf8"]={char=utf8.char}}
  end
end)()
%    \end{macrocode}
% \par
% \begin{markdown}
%
% \pkg{MD5}
%
%:    A library that provides \acro{md5} crypto functions. It is used by the
%     \pkg{Lunamark} library to compute the digest of the input for caching
%     purposes. \pkg{MD5} is included in all releases of Lua\TeX{} (\TeX
%     Live${}\geq{}2008$).
%
% \end{markdown}
%  \begin{macrocode}
local md5 = require("md5")
%    \end{macrocode}
% \par
% \begin{markdown}
%
% All the abovelisted modules are statically linked into the current version of
% the Lua\TeX{} engine~[@luatex21, Section 4.3]. Beside these, we also carry
% the following third-party Lua libraries:
%
% \pkg{api7/lua-tinyyaml}
%
%:    A library that provides a regex-based recursive descent \acro{yaml}
%     (subset) parser that is used to read \acro{yaml} metadata when the
%     \Opt{jekyllData} option is enabled.
%
% \end{markdown}
% \iffalse
%</lua>
%<*tex>
% \fi
% \par
% \begin{markdown}
%
%### Plain \TeX{} Requirements {#texprerequisites}
%
% The plain \TeX{} part of the package requires that the plain \TeX{}
% format (or its superset) is loaded, all the Lua prerequisites (see
% Section <#sec:luaprerequisites>), and the following packages:
%
% \pkg{expl3}
%
%:    A package that enables the expl3 language from the \LaTeX3 kernel in
%     \TeX{} Live${}\leq{}2019$. It is used to implement reflection
%     capabilities that allow us to enumerate and inspect high-level concepts
%     such as options, renderers, and renderer prototypes.
%
% \end{markdown}
%  \begin{macrocode}
%<@@=markdown>
\ifx\ExplSyntaxOn\undefined
  \input expl3-generic\relax
\fi
%    \end{macrocode}
% \begin{markdown}
%
% \pkg{lt3luabridge}
%
%:    A package that allows us to execute Lua code with LuaTeX as well as
%     with other TeX engines that provide the *shell escape* capability,
%     which allows them to execute code with the system's shell.
%
% The plain \TeX{} part of the package also requires the following Lua module:
%
% \pkg{Lua File System}
%
%:    A library that provides access to the filesystem via \acro{os}-specific
%     syscalls. It is used by the plain \TeX{} code to create the cache
%     directory specified by the \Opt{cacheDir} option before interfacing with
%     the \pkg{Lunamark} library. \pkg{Lua File System} is included in all
%     releases of Lua\TeX{} (\TeX Live${}\geq{}2008$).
%
%     The plain \TeX{} code makes use of the `isdir` method that was added
%     to the \pkg{Lua File System} library by the Lua\TeX{} engine
%     developers~[@luatex21, Section 4.2.4].
%
% The \pkg{Lua File System} module is statically linked into the Lua\TeX{}
% engine~[@luatex21, Section 4.3].
%
% Unless you convert markdown documents to \TeX{} manually using the Lua
% command-line interface (see Section <#sec:lua-cli-interface>), the plain
% \TeX{} part of the package will require that either the Lua\TeX{}
% `\directlua` primitive or the shell access file stream 18 is available in
% your \TeX{} engine. If only the shell access file stream is available in your
% \TeX{} engine (as is the case with \hologo{pdfTeX} and \Hologo{XeTeX}) or if
% you enforce the use of shell using the \mref{markdownMode} macro, then unless
% your \TeX{} engine is globally configured to enable shell access, you will
% need to provide the `-shell-escape` parameter to your engine when typesetting
% a document.
%
% \end{markdown}
% \iffalse
%</tex>
%<*latex>
% \fi
% \par
% \begin{markdown}
%
%### \LaTeX{} Requirements {#latexprerequisites}
%
% The \LaTeX{} part of the package requires that the \Hologo{LaTeX2e} format is
% loaded,
% \end{markdown}
% \iffalse
%<*latex-themes-witiko-dot,latex-themes-witiko-graphicx-http,latex-themes-witiko-tilde>
% \fi
%  \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}%
%    \end{macrocode}
% \iffalse
%</latex-themes-witiko-dot,latex-themes-witiko-graphicx-http,latex-themes-witiko-tilde>
% \fi
% \begin{markdown}
% a \TeX{} engine that extends \Hologo{eTeX}, and all the plain \TeX{}
% prerequisites (see Section <#sec:texprerequisites>):
%
% The following packages are soft prerequisites. They are only used to provide
% default token renderer prototypes (see sections
% <#sec:texrendererprototypes> and
% <#sec:latexdefaultrendererprototypes>) or \LaTeX{} themes (see Section
% <#sec:latexthemes>) and will not be loaded if the `plain` package option
% has been enabled (see Section <#sec:latexplain>):
%
% \pkg{url}
%
%:    A package that provides the `\url` macro for the typesetting of links.
%
% \pkg{graphicx}
%
%:    A package that provides the `\includegraphics` macro for the typesetting
%     of images.
%
% \pkg{paralist}
%
%:    A package that provides the `compactitem`, `compactenum`, and
%     `compactdesc` macros for the typesetting of tight bulleted lists,
%     ordered lists, and definition lists.
%
% \pkg{ifthen}
%
%:    A package that provides a concise syntax for the inspection of macro
%     values. It is used in the `witiko/dot` \LaTeX{} theme (see Section
%     <#sec:latexthemes>).
%
% \pkg{fancyvrb}
%
%:    A package that provides the `\VerbatimInput` macros for the verbatim
%     inclusion of files containing code.
%
% \pkg{csvsimple}
%
%:    A package that provides the `\csvautotabular` macro for typesetting
%     \acro{csv} files in the default renderer prototypes for iA\,Writer
%     content blocks.
%
% \pkg{gobble}
%
%:    A package that provides the `\@gobblethree` \TeX{} command that
%     is used in the default renderer prototype for citations. The package
%     is included in \TeX Live${}\geq{}2016$.
%
% \pkg{amsmath} and \pkg{amssymb}
%
%:    Packages that provide symbols used for drawing ticked and unticked
%     boxes.
%
% \pkg{catchfile}
%
%:    A package that catches the contents of a file and puts it in a macro. It
%     is used in the `witiko/graphicx/http` \LaTeX{} theme, see Section
%     <#sec:latexthemes>.
%
% \pkg{grffile}
%
%:    A package that extends the name processing of package graphics to support
%     a larger range of file names in $2006\leq{}$\TeX{} Live${}\leq{}2019$.
%     Since \TeX{} Live${}\geq{}2020$, the functionality of the package has
%     been integrated in the \LaTeXe{} kernel. It is used in the `witiko/dot`
%     and `witiko/graphicx/http` \LaTeX{} themes, see Section
%     <#sec:latexthemes>.
%
% \pkg{etoolbox}
%
%:    A package that is used to polyfill the general hook management system in
%     the default renderer prototypes for \acro{yaml} metadata, see Section
%     <#sec:latexyamlmetadata>, and also in the default renderer prototype
%     for attribute identifiers.
%
% \pkg{soulutf8}
%
%:    A package that is used in the default renderer prototype for
%     strike-throughs.
%
% \end{markdown}
%  \begin{macrocode}
\RequirePackage{expl3}
%    \end{macrocode}
% \iffalse
%</latex>
%<*context>
% \fi
% \par
% \begin{markdown}
%
%### \Hologo{ConTeXt} Prerequisites
% The \Hologo{ConTeXt} part of the package requires that either the Mark II or
% the Mark IV format is loaded, all the plain \TeX{} prerequisites (see
% Section <#sec:texprerequisites>), and the following \Hologo{ConTeXt}
% modules:
%
% \pkg{m-database}
%
%:    A module that provides the default token renderer prototype for
%     iA\,Writer content blocks with the \acro{csv} filename extension (see
%     Section <#sec:texrendererprototypes>).
%
% Feedback
%---------
% Please use the \pkg{Markdown} project page on
% [GitHub](https://github.com/witiko/markdown/issues) to report bugs and submit
% feature requests. If you do not want to report a bug or request a feature but
% are simply in need of assistance, you might want to consider posting your
% question to the [\TeX-\LaTeX{} Stack Exchange.](https://tex.stackexchange.com)
% community question answering web site under the `markdown` tag.
%
% Acknowledgements
%-----------------
% The Lunamark Lua module provides speedy markdown parsing for the package. I
% would like to thank John Macfarlane, the creator of Lunamark, for releasing
% Lunamark under a permissive license, which enabled its use in the Markdown
% package.
%
% Extensive user documentation for the Markdown package was kindly written by
% Lian Tze Lim and published by Overleaf.
%
% Funding by the the Faculty of Informatics at the Masaryk~University
% in~Brno~[@novotny15] is gratefully acknowledged.
%
% Support for content slicing (Lua options \Opt{shiftHeadings} and \Opt{slice})
% and pipe tables (Lua options \Opt{pipeTables} and \Opt{tableCaptions}) was
% graciously sponsored by David Vins and Omedym.
%
% The \TeX{} implementation of the package draws inspiration from several
% sources including the source code of \Hologo{LaTeX2e}, the \pkg{minted}
% package by Geoffrey M. Poore, which likewise tackles the issue of
% interfacing with an external interpreter from \TeX{}, the \pkg{filecontents}
% package by Scott Pakin and others.
%
% Interfaces {#interfaces}
%============
%
% This part of the documentation describes the interfaces exposed by the package
% along with usage notes and examples. It is aimed at the user of the package.
%
% Since neither \TeX{} nor Lua provide interfaces as a language construct, the
% separation to interfaces and implementations is a *gentlemen's agreement*. It
% serves as a means of structuring this documentation and as a promise to the
% user that if they only access the package through the interface, the future
% minor versions of the package should remain backwards compatible.
%
% Figure <#fig:block-diagram> shows the high-level structure of the Markdown
% package: The translation from markdown to \TeX{} *token renderers* is exposed
% by the Lua layer. The plain \TeX{} layer exposes the conversion capabilities
% of Lua as \TeX{} macros. The \LaTeX{} and \Hologo{ConTeXt} layers provide
% syntactic sugar on top of plain \TeX{} macros. The user can interface with
% any and all layers.
%
% \end{markdown}
% \begin{figure}
% \centering
% \input markdown-figure-block-diagram
% \caption{A block diagram of the \pkg{Markdown} package}
% \label{fig:block-diagram}
% \end{figure}
% \iffalse
%</context>
%<*manual>

First Document
--------------

In this section, we will take the necessary steps to typeset our first markdown
document in \TeX{}. This will serve as our first hands-on experience with the
package and also as a reassurance that the package has been correctly installed.

If you are using [our official Docker image][docker], you need to prefix all
commands in this section with `docker run --rm -v "$PWD"/workdir:/workdir -w
/workdir witiko/markdown`. For example, instead of `luatex document.tex`, you
would execute the following command:
``` sh
docker run --rm -v "$PWD"/workdir:/workdir -w /workdir witiko/markdown \
  luatex document.tex
``````

### Using Lua

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input hello
\bye
```````

#### Using the Lua Module

Using a text editor, create a text document named `hello.lua` with the
following content:
``` lua
#!/usr/bin/env texlua
local ran_ok, kpse = pcall(require, "kpse")
if ran_ok then kpse.set_program_name("luatex") end
local markdown = require("markdown")
local convert = markdown.new()
print(convert("Hello *world*!"))
```````
Next, invoke LuaTeX from the terminal:
``` sh
texlua hello.lua > hello.tex
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” Invoking pdfTeX should have the same effect:
``` sh
texlua hello.lua > hello.tex
pdftex document.tex
``````

#### Using the Lua Command-Line Interface

Using a text editor, create a text document named `hello.md` with the
following content:
``` md
Hello *world*!
``````
Next, invoke LuaTeX from the terminal:
``` sh
texlua ⟨CLI pathname⟩ -- hello.md hello.tex
luatex document.tex
``````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

 [Kpathsea]: https://tug.org/kpathsea/ (Kpathsea - TeX Users Group)

A PDF document named `document.pdf` should be produced and contain the text “Hello
*world*!” Invoking pdfTeX should have the same effect:
``` sh
texlua ⟨CLI pathname⟩ -- hello.md hello.tex
pdftex document.tex
``````

### Using Plain \TeX{}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\markdownBegin
Hello *world*!
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” Invoking pdfTeX should have the same effect:
``` sh
pdftex --shell-escape document.tex
```````

### Using \LaTeX{}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{document}
\begin{markdown}
Hello *world*!
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text “Hello
*world*!” Invoking pdfTeX should have the same effect:
``` sh
pdflatex --shell-escape document.tex
``````

***

As the next step, try typesetting the example documents distributed along with
the Markdown package:
``` sh
git clone https://github.com/witiko/markdown
cd markdown/examples
lualatex latex.tex
``````
A PDF document named `latex.pdf` should be produced. Open the text documents
`latex.tex` and `example.md` in a text editor to see how the example documents
are structured. Try changing the documents and typesetting them as follows:
``` sh
lualatex latex.tex
``````
to see the effect of your changes.

### Using \Hologo{ConTeXt}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\starttext
\startmarkdown
Hello *world*!
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text “Hello
*world*!” Invoking pdfTeX should have the same effect:
``` sh
texexec --passon=--shell-escape document.tex
``````

***

As the next step, try typesetting the example documents distributed along with
the Markdown package:
``` sh
git clone https://github.com/witiko/markdown
cd markdown/examples
context context.tex
``````
A PDF document named `context.pdf` should be produced. Open the text documents
`context.tex` and `example.md` in a text editor to see how the example documents
are structured. Try changing the documents and typesetting them as follows:
``` sh
context context.tex
``````
to see the effect of your changes.

Examples
========

In this section, I will describe the individual parts of the Markdown package.
Each part will be shown by example, leaving the implementation details to the
[technical documentation][techdoc].

 [techdoc]: https://mirrors.ctan.org/macros/generic/markdown/markdown.pdf
            (A Markdown Interpreter for \TeX{})

/markdown-interfaces.md
/markdown-options.md
/markdown-tokens.md

%</manual>
%<*lua>
% \fi
% \par
% \begin{markdown}
%
% Lua Interface {#luainterface}
%---------------
%
% \iffalse
%</lua>
%<*manual-interfaces>

Interfaces
----------

In this section, I will describe the individual interfaces exposed by the
Markdown package starting with the low-level Lua interfaces and all the way up
to the \LaTeX{} and \Hologo{ConTeXt} interfaces intended for the ordinary
user.

### Lua

The Lua programming language is what drives the conversion from markdown to
\TeX{} in the Markdown package. Based on the [Lunamark][] Lua library by John
MacFarlane, the Lua implementation is largely independent on \TeX{}, and can be
used separately from typesetting a document. Lua provides two interfaces: a Lua
module and a command-line interface (CLI).

 [Lunamark]: https://github.com/jgm/lunamark
             (Lua library for conversion between markup formats)

%</manual-interfaces>
%<*lua>
% \fi
%
% The Lua interface provides the conversion from \acro{utf}-\oldstylenums8
% encoded markdown to plain \TeX{}. This interface is used by the plain \TeX{}
% implementation (see Section <#sec:teximplementation>) and will be of
% interest to the developers of other packages and Lua modules.
%
% The Lua interface is implemented by the `markdown` Lua module.
%
% \end{markdown}
%  \begin{macrocode}
local M = {metadata = metadata}
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Conversion from Markdown to Plain \TeX{} {#luaconversion}
%
% The Lua interface exposes the \luamdef{new}`(options)` function.  This
% function returns a conversion function from markdown to plain \TeX{} according
% to the table `options` that contains options recognized by the Lua interface
% (see Section <#sec:luaoptions>). The `options` parameter is optional; when
% unspecified, the behaviour will be the same as if `options` were an empty
% table.
%
% The following example Lua code converts the markdown string `Hello
% *world*!` to a \TeX{} output using the default options and prints the \TeX{}
% output:
% ``` lua
% local md = require("markdown")
% local convert = md.new()
% print(convert("Hello *world*!"))
% ```````
%
%### User-Defined Syntax Extensions {#luauserextensions}
%
% For the purpose of user-defined syntax extensions, the Lua interface also
% exposes the \luamdef{reader} object, which performs the lexical and
% syntactic analysis of markdown text and which exposes the
% \luamdef{reader->insert_pattern} and \luamdef{reader->add_special_character}
% methods for extending the \acro{peg} grammar of markdown.
%
% The read-only \luamdef{walkable_syntax} hash table stores those rules of the
% \acro{peg} grammar of markdown that can be represented as an ordered choice
% of terminal symbols. These rules can be modified by user-defined syntax
% extensions.
%
% \end{markdown}
%  \begin{macrocode}
local walkable_syntax = {
  Block = {
    "Blockquote",
    "Verbatim",
    "ThematicBreak",
    "BulletList",
    "OrderedList",
    "Heading",
    "DisplayHtml",
    "Paragraph",
    "Plain",
  },
  Inline = {
    "Str",
    "Space",
    "Endline",
    "UlOrStarLine",
    "Strong",
    "Emph",
    "Link",
    "Image",
    "Code",
    "AutoLinkUrl",
    "AutoLinkEmail",
    "AutoLinkRelativeReference",
    "InlineHtml",
    "HtmlEntity",
    "EscapedChar",
    "Smart",
    "Symbol",
  },
}
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamref{reader->insert_pattern} method inserts a \acro{peg} pattern into
% the grammar of markdown. The method receives two mandatory arguments: a
% selector string in the form `"`\meta{left-hand side terminal symbol}
% \meta{`before`, `after`, or `instead of`} \meta{right-hand side terminal
% symbol}`"` and a \acro{peg} pattern to insert, and an optional third argument
% with a name of the \acro{peg} pattern for debugging purposes (see the
% \Opt{debugExtensions} option). The name does not need to be unique and shall
% not be interpreted by the Markdown package; you can treat it as a comment.
%
% For example. if we'd like to insert `pattern` into the grammar between the
% `Inline -> Emph` and `Inline -> Link` rules, we would call
% \luamref{reader->insert_pattern} with `"Inline after Emph"` (or `"Inline
% before Link"`) and `pattern` as the arguments.
%
% The \luamref{reader->add_special_character} method adds a new character with
% special meaning to the grammar of markdown. The method receives the character
% as its only argument.
%
% \end{markdown}
% \iffalse
%</lua>
%<*manual-interfaces>

#### Lua Module

A Lua module is a software library that can be used from in other programs.
The `markdown` Lua module makes it possible to convert markdown to \TeX{} from
within Lua\TeX{} documents and Lua scripts.

The `markdown` Lua module exposes the `new(`\meta{options}`)` method, which
creates a converter function from markdown to \TeX{}. The properties of the
converter function are specified by the Lua table `options`. The parameter is
optional; when unspecified, the behaviour will be the same as if \meta{options}
were an empty table.

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\input example
\bye
```````
Using a text editor, create a text document named `example.lua` with the
following content:
``` lua
#!/usr/bin/env texlua
local ran_ok, kpse = pcall(require, "kpse")
if ran_ok then kpse.set_program_name("luatex") end
local markdown = require("markdown")
local input, convert_safe, convert_unsafe, paragraph

input = [[$\sqrt{-1}$ *equals* $i$.]]
convert_safe = markdown.new()
convert_unsafe = markdown.new({hybrid = true})
paragraph = [[\par]]

print(
  convert_safe(input) .. paragraph ..
  convert_unsafe(input)
)
```````
Next, invoke LuaTeX from the terminal:
``` sh
texlua example.lua > example.tex
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt{-1}\$ *equals* \$i\$.
> 
> √-̅1̅ *equals* $i$.

Invoking pdfTeX should have the same effect:
``` sh
texlua example.lua > example.tex
pdftex document.tex
``````

***

Rather than use the `texlua` interpreter, we can also access the `markdown` Lua
module directly from our document. Using a text editor, create a text document
named `document.tex` with the following content:
``` tex
\input markdown
\input lmfonts
\directlua{
  local markdown = require("markdown")
  local input, convert_safe, convert_unsafe, paragraph

  input = [[$\string\sqrt{-1}$ *equals* $i$.]]
  convert_safe = markdown.new()
  convert_unsafe = markdown.new({hybrid = true})
  paragraph = [[\par]]

  tex.sprint(
    convert_safe(input) .. paragraph ..
    convert_unsafe(input)
  )
}
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
```````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt{-1}\$ *equals* \$i\$.
> 
> √-̅1̅ *equals* $i$.

In this case, we cannot use pdfTeX, because pdfTeX does not define the
`\directlua` \TeX{} command.

#### Lua Command-Line Interface

The Lua command-line interface (CLI) of the Markdown package makes the
functionality of the Lua module accessible from the command line.  This makes
it possible to convert documents from markdown to \TeX{} manually without any
knowledge of the Lua programming language.

The Lua command-line interface accepts the same options as the `markdown` Lua
module, but now the options are specified as command-line parameters.

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\input safe

\begingroup
\catcode`\%=12
\input unsafe
\endgroup
\bye
```````
Using a text editor, create a text document named `example.md` with the
following content:
``` md
$\sqrt{-1}$ *equals* $i$.
``````
Next, invoke LuaTeX from the terminal:
``` sh
texlua ⟨CLI pathname⟩ -- example.md safe.tex
texlua ⟨CLI pathname⟩ hybrid=true -- example.md unsafe.tex
luatex document.tex
``````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt{-1}\$ *equals* \$i\$.
> 
> √-̅1̅ *equals* $i$.

Invoking pdfTeX should have the same effect:
``` sh
texlua ⟨CLI pathname⟩ -- example.md safe.tex
texlua ⟨CLI pathname⟩ hybrid=true -- example.md unsafe.tex
pdftex document.tex
``````

%</manual-interfaces>
%<*lua>
% \fi
% \begin{markdown}
%
%### Options {#luaoptions}
%
% The Lua interface recognizes the following options. When unspecified, the
% value of a key is taken from the \luamdef{defaultOptions} table.
%
% \end{markdown}
% \iffalse
%</lua>
%<*manual-options>

## Options

In this section, I will describe all the options recognized by the Markdown
package.

%</manual-options>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
local defaultOptions = {}
%    \end{macrocode}
% \begingroup
% \markdownSetup{snippet=witiko/markdown/techdoc/options}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

### Lua

Lua options control the conversion from markdown to \TeX{}. They are supported
by all interfaces of the Markdown package starting with the low-level Lua
interfaces and all the way up to the \LaTeX{} and \Hologo{ConTeXt} interfaces.

%</manual-options>
%<*tex>
% \fi
% \begin{markdown}
%
% To enable the enumeration of Lua options, we will maintain the
% \mdef{g_\@\@_lua_options_seq} sequence.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\seq_new:N \g_@@_lua_options_seq
%    \end{macrocode}
% \begin{markdown}
%
% To enable the reflection of default Lua options and their types, we will
% maintain the \mdef{g_\@\@_default_lua_options_prop} and
% \mdef{g_\@\@_lua_option_types_prop} property lists, respectively.
%
% \end{markdown}
%  \begin{macrocode}
\prop_new:N \g_@@_lua_option_types_prop
\prop_new:N \g_@@_default_lua_options_prop
\seq_new:N \g_@@_option_layers_seq
\tl_const:Nn \c_@@_option_layer_lua_tl { lua }
\seq_gput_right:NV \g_@@_option_layers_seq \c_@@_option_layer_lua_tl
\cs_new:Nn
  \@@_add_lua_option:nnn
  {
    \@@_add_option:Vnnn
      \c_@@_option_layer_lua_tl
      { #1 }
      { #2 }
      { #3 }
  }
\cs_new:Nn
  \@@_add_option:nnnn
  {
    \seq_gput_right:cn
      { g_@@_ #1 _options_seq }
      { #2 }
    \prop_gput:cnn
      { g_@@_ #1 _option_types_prop }
      { #2 }
      { #3 }
    \prop_gput:cnn
      { g_@@_default_ #1 _options_prop }
      { #2 }
      { #4 }
    \@@_typecheck_option:n
      { #2 }
  }
\cs_generate_variant:Nn
  \@@_add_option:nnnn
  { Vnnn }
\tl_const:Nn \c_@@_option_value_true_tl  { true  }
\tl_const:Nn \c_@@_option_value_false_tl { false }
\cs_new:Nn \@@_typecheck_option:n
  {
    \@@_get_option_type:nN
      { #1 }
      \l_tmpa_tl
    \str_case_e:Vn
      \l_tmpa_tl
      {
        { \c_@@_option_type_boolean_tl }
          {
            \@@_get_option_value:nN
              { #1 }
              \l_tmpa_tl
            \bool_if:nF
              {
                \str_if_eq_p:VV
                  \l_tmpa_tl
                  \c_@@_option_value_true_tl ||
                \str_if_eq_p:VV
                  \l_tmpa_tl
                  \c_@@_option_value_false_tl
              }
              {
                \msg_error:nnnV
                  { @@ }
                  { failed-typecheck-for-boolean-option }
                  { #1 }
                  \l_tmpa_tl
              }
          }
      }
  }
\msg_new:nnn
  { @@ }
  { failed-typecheck-for-boolean-option }
  {
    Option~#1~has~value~#2,~
    but~a~boolean~(true~or~false)~was~expected.
  }
\cs_generate_variant:Nn
  \str_case_e:nn
  { Vn }
\cs_generate_variant:Nn
  \msg_error:nnnn
  { nnnV }
\seq_new:N \g_@@_option_types_seq
\tl_const:Nn \c_@@_option_type_clist_tl { clist }
\seq_gput_right:NV \g_@@_option_types_seq \c_@@_option_type_clist_tl
\tl_const:Nn \c_@@_option_type_counter_tl { counter }
\seq_gput_right:NV \g_@@_option_types_seq \c_@@_option_type_counter_tl
\tl_const:Nn \c_@@_option_type_boolean_tl { boolean }
\seq_gput_right:NV \g_@@_option_types_seq \c_@@_option_type_boolean_tl
\tl_const:Nn \c_@@_option_type_number_tl  { number  }
\seq_gput_right:NV \g_@@_option_types_seq \c_@@_option_type_number_tl
\tl_const:Nn \c_@@_option_type_path_tl    { path    }
\seq_gput_right:NV \g_@@_option_types_seq \c_@@_option_type_path_tl
\tl_const:Nn \c_@@_option_type_slice_tl   { slice   }
\seq_gput_right:NV \g_@@_option_types_seq \c_@@_option_type_slice_tl
\tl_const:Nn \c_@@_option_type_string_tl  { string  }
\seq_gput_right:NV \g_@@_option_types_seq \c_@@_option_type_string_tl
\cs_new:Nn
  \@@_get_option_type:nN
  {
    \bool_set_false:N
      \l_tmpa_bool
    \seq_map_inline:Nn
      \g_@@_option_layers_seq
      {
        \prop_get:cnNT
          { g_@@_ ##1 _option_types_prop }
          { #1 }
          \l_tmpa_tl
          {
            \bool_set_true:N
              \l_tmpa_bool
            \seq_map_break:
          }
      }
    \bool_if:nF
      \l_tmpa_bool
      {
        \msg_error:nnn
          { @@ }
          { undefined-option }
          { #1 }
      }
    \seq_if_in:NVF
      \g_@@_option_types_seq
      \l_tmpa_tl
      {
        \msg_error:nnnV
          { @@ }
          { unknown-option-type }
          { #1 }
          \l_tmpa_tl
      }
    \tl_set_eq:NN
      #2
      \l_tmpa_tl
  }
\msg_new:nnn
  { @@ }
  { unknown-option-type }
  {
    Option~#1~has~unknown~type~#2.
  }
\msg_new:nnn
  { @@ }
  { undefined-option }
  {
    Option~#1~is~undefined.
  }
\cs_new:Nn
  \@@_get_default_option_value:nN
  {
    \bool_set_false:N
      \l_tmpa_bool
    \seq_map_inline:Nn
      \g_@@_option_layers_seq
      {
        \prop_get:cnNT
          { g_@@_default_ ##1 _options_prop }
          { #1 }
          #2
          {
            \bool_set_true:N
              \l_tmpa_bool
            \seq_map_break:
          }
      }
    \bool_if:nF
      \l_tmpa_bool
      {
        \msg_error:nnn
          { @@ }
          { undefined-option }
          { #1 }
      }
  }
\cs_new:Nn
  \@@_get_option_value:nN
  {
    \@@_option_tl_to_csname:nN
      { #1 }
      \l_tmpa_tl
    \cs_if_free:cTF
      { \l_tmpa_tl }
      {
        \@@_get_default_option_value:nN
          { #1 }
          #2
      }
      {
        \@@_get_option_type:nN
          { #1 }
          \l_tmpa_tl
        \str_if_eq:NNTF
          \c_@@_option_type_counter_tl
          \l_tmpa_tl
          {
            \@@_option_tl_to_csname:nN
              { #1 }
              \l_tmpa_tl
            \tl_set:Nx
              #2
              { \the \cs:w \l_tmpa_tl \cs_end: }
          }
          {
            \@@_option_tl_to_csname:nN
              { #1 }
              \l_tmpa_tl
            \tl_set:Nv
              #2
              { \l_tmpa_tl }
          }
      }
  }
\cs_new:Nn \@@_option_tl_to_csname:nN
  {
    \tl_set:Nn
      \l_tmpa_tl
      { \str_uppercase:n { #1 } }
    \tl_set:Nx
      #2
      {
        markdownOption
        \tl_head:f { \l_tmpa_tl }
        \tl_tail:n { #1 }
      }
  }
\seq_new:N \g_@@_cases_seq
\cs_new:Nn \@@_with_various_cases:nn
  {
    \seq_clear:N
      \l_tmpa_seq
    \seq_map_inline:Nn
      \g_@@_cases_seq
      {
        \tl_set:Nn
          \l_tmpa_tl
          { #1 }
        \use:c { ##1 }
          \l_tmpa_tl
        \seq_put_right:NV
          \l_tmpa_seq
          \l_tmpa_tl
      }
    \seq_map_inline:Nn
      \l_tmpa_seq
      { #2 }
  }
\cs_new:Nn \@@_camel_case:N
  {
    \regex_replace_all:nnN
      { _ ([a-z]) }
      { \c { str_uppercase:n } \cB\{ \1 \cE\} }
      #1
    \tl_set:Nx
      #1
      { #1 }
  }
\seq_gput_right:Nn \g_@@_cases_seq { @@_camel_case:N }
\cs_new:Nn \@@_snake_case:N
  {
    \regex_replace_all:nnN
      { ([a-z])([A-Z]) }
      { \1 _ \c { str_lowercase:n } \cB\{ \2 \cE\} }
      #1
    \tl_set:Nx
      #1
      { #1 }
  }
\seq_gput_right:Nn \g_@@_cases_seq { @@_snake_case:N }
%    \end{macrocode}
% \iffalse
%</tex>
%<*manual-options>
% \fi
% \begin{markdown}
%
%### File and Directory Names
%
% \end{markdown}
% \par
% \iffalse

#### Option `cacheDir`

`cacheDir` (default value: `"."`)

% \fi
% \begin{markdown}
%
% \Valitem[.]{cacheDir}{path}
%
:    A path to the directory containing auxiliary cache files. If the last
     segment of the path does not exist, it will be created by the Lua
     command-line and plain \TeX{} implementations. The Lua implementation
     expects that the entire path already exists.

     When iteratively writing and typesetting a markdown document, the cache
     files are going to accumulate over time. You are advised to clean the
     cache directory every now and then, or to set it to a temporary filesystem
     (such as `/tmp` on UN*X systems), which gets periodically emptied.

% \end{markdown}
% \iffalse

##### Lua Module Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new({cacheDir = "cache"})
  local input = "Hello *world*!"
  tex.sprint(convert(input)) }
\bye
```````
Create an empty directory named `cache` next to our text document. Then, invoke
LuaTeX from the terminal:
``` sh
luatex document.tex
```````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” Several cache files of the Markdown package will also be
produced in the `cache` directory as we requested using the `cacheDir` option.

##### Lua CLI Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input hello
\bye
```````
Using a text editor, create a text document named `hello.md` with the
following content:
``` md
Hello *world*!
``````
Next, invoke LuaTeX from the terminal:
``` sh
texlua ⟨CLI pathname⟩ cacheDir=cache -- hello.md hello.tex
luatex document.tex
```````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” A directory named `cache` containing several cache files of
the Markdown package will also be produced as we requested using the `cacheDir`
option.

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionCacheDir{cache}
\markdownBegin
Hello *world*!
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text “Hello
*world*!” A directory named `cache` containing several cache files of the
Markdown package will also be produced as we requested using the `cacheDir`
option.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[cacheDir=cache]{markdown}
\begin{document}
\begin{markdown}
Hello *world*!
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text “Hello
*world*!” A directory named `cache` containing several cache files of the
Markdown package will also be produced as we requested using the `cacheDir`
option.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[cacheDir = cache]
\starttext
\startmarkdown
Hello *world*!
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text “Hello
*world*!” A directory named `cache` containing several cache files of the
Markdown package will also be produced as we requested using the `cacheDir`
option.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { cacheDir }
  { path }
  { \markdownOptionOutputDir / _markdown_\jobname }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.cacheDir = "."
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `contentBlocksLanguageMap`

`contentBlocksLanguageMap` (default value: `"markdown-languages.json"`)

% \fi
% \begin{markdown}
%
% \Valitem[markdown-languages.json]{contentBlocksLanguageMap}{filename}
%
:    The filename of the \acro{JSON} file that maps filename extensions to
     programming language names in the iA\,Writer content blocks when the
     \Opt{contentBlocks} option is enabled.
%    See Section <#sec:texcontentblockrenderers> for more information.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `table.csv` with the
following content:
``` csv
Name,Surname,Born
Albert,Einstein,1879
Marie,Curie,1867
Thomas,Edison,1847
```````
Create also a text document named `language-map.json` with the following
content:
``` js
{
  "tex": "LaTeX"
}
``````
Create also a text document named `code.tex` with the following content:
``` tex
This is an example code listing in \LaTeX.
```````
Create also a text document named `part.md` with the following content:
``` md
This is a *transcluded markdown document*.
``````
Create also a text document named `document.tex` with the following content:
``` tex
\documentclass{article}
\usepackage{minted}
\usepackage[contentBlocks]{markdown}
\markdownSetup{
  contentBlocksLanguageMap = {language-map.json},
}
\begin{document}
\begin{markdown}
/table.csv  (An example table)
/code.tex   (An example code listing)
/part.md    (A file transclusion example)
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex --shell-escape document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> | Name   | Surname  | Born |
> | ------ | ---------| ---- |
> | Albert | Einstein | 1879 |
> | Marie  | Curie    | 1867 |
> | Thomas | Edison   | 1847 |
>
> Table 1: An example table
>
> ``` tex
> This is an example code listing in \LaTeX.
> ```````
>
> This is a *transcluded markdown document*.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `table.csv` with the
following content:
``` csv
Name,Surname,Born
Albert,Einstein,1879
Marie,Curie,1867
Thomas,Edison,1847
```````
Create also a text document named `language-map.json` with the following
content:
``` js
{
  "tex": "ConTeXt"
}
``````
Create also a text document named `code.tex` with the following content:
``` tex
This is an example code listing in \ConTeXt.
```````
Create also a text document named `part.md` with the following content:
``` md
This is a *transcluded markdown document*.
``````
Create also a text document named `document.tex` with the following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown
  [
    contentBlocks = yes,
    contentBlocksLanguageMap = language-map.json,
  ]
\definetyping [ConTeXt]
\setuptyping  [ConTeXt] [option=TEX]
\starttext
\startmarkdown
/table.csv  (An example table)
/code.tex   (An example code listing)
/part.md    (A file transclusion example)
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> | Name   | Surname  | Born |
> | ------ | ---------| ---- |
> | Albert | Einstein | 1879 |
> | Marie  | Curie    | 1867 |
> | Thomas | Edison   | 1847 |
>
> Table 1: An example table
>
> ``` tex
> This is an example code listing in \ConTeXt.
> ```````
>
> This is a *transcluded markdown document*.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { contentBlocksLanguageMap }
  { path }
  { markdown-languages.json }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.contentBlocksLanguageMap = "markdown-languages.json"
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `debugExtensionsFileName`

`debugExtensionsFileName` (default value: `"debug-extensions.json"`)

% \fi
% \begin{markdown}
%
% \Valitem[debug-extensions.json]{debugExtensionsFileName}{filename}
%
:    The filename of the \acro{JSON} file that will be produced when the
     \Opt{debugExtensions} option is enabled. This file will contain the
     extensible subset of the \acro{peg} grammar of markdown
%    (see the \luamref{walkable_syntax} hash table)
     after built-in syntax extensions
%    (see Section <#sec:luabuiltinextensions>)
%    \iffalse
     (see options \Opt{citations}, \Opt{contentBlocks}, \Opt{definitionLists},
     etc.)
%    \fi
     and user-defined syntax extensions
%    (see Section <#sec:luauserextensions>)
%    \iffalse
     (see option \Opt{extensions})
%    \fi
     have been applied.

% \end{markdown}
% \iffalse
%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { debugExtensionsFileName }
  { path }
  { \markdownOptionOutputDir / \jobname .debug-extensions.json }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.debugExtensionsFileName = "debug-extensions.json"
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `frozenCacheFileName`

`frozenCacheFileName` (default value: `"frozenCache.tex"`)

% \fi
% \begin{markdown}
%
% \Valitem[frozenCache.tex]{frozenCacheFileName}{path}
%
:    A path to an output file (frozen cache) that will be created when
     the \Opt{finalizeCache} option is enabled and will contain a mapping
     between an enumeration of markdown documents and their auxiliary cache
     files.

     The frozen cache makes it possible to later typeset a plain \TeX{}
     document that contains markdown documents without invoking Lua using
     the \Opt{frozenCache} plain \TeX{} option. As a result, the
     plain \TeX{} document becomes more portable, but further changes in the
     order and the content of markdown documents will not be reflected.

% \end{markdown}
% \iffalse

##### Lua Module Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new({finalizeCache = true, frozenCacheFileName = "cache.tex"})
  local input = "Hello *world*!"
  tex.sprint(convert(input)) }
\bye
```````
Then, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
```````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” A frozen cache will also be produced in the `cache.tex`
output file as we requested using the `finalizeCache` and `frozenCacheFileName`
options.

##### Lua CLI Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input hello
\bye
```````
Using a text editor, create a text document named `hello.md` with the
following content:
``` md
Hello *world*!
``````
Next, invoke LuaTeX from the terminal:
``` sh
texlua ⟨CLI pathname⟩ finalizeCache=true frozenCacheFileName=cache.tex -- hello.md hello.tex
luatex document.tex
```````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” A frozen cache will also be produced in the `cache.tex`
output file as we requested using the `finalizeCache` and `frozenCacheFileName`
options.

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionFinalizeCache{true}
\def\markdownOptionFrozenCacheFileName{cache.tex}
\markdownBegin
Hello *world*!
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” A frozen cache will also be produced in the `cache.tex`
output file as we requested using the `finalizeCache` and `frozenCacheFileName`
options.

Next, create a new text document `frozen-document.tex` with the following
content:
``` tex
\input markdown
\def\markdownOptionFrozenCache{true}
\def\markdownOptionFrozenCacheFileName{cache.tex}
\markdownBegin
Hi *world*!
\markdownEnd
\bye
```````
Last, invoke pdfTeX without shell access from the terminal:
``` sh
pdftex -no-shell-escape frozen-document.tex
``````
A PDF document named `frozen-document.pdf` should be produced and contain the
text “Hello *world*!” Since we used the contents of the frozen cache using
the `\markdownOptionFrozenCache` option, we were able to typeset the
document without accessing the shell or invoking Lua, but the change in the
content of the markdown document from “Hello *world*!” to “Hi *world*!” was
not reflected.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass[finalizecache]{article}
\usepackage[frozenCacheFileName=cache.tex]{markdown}
\begin{document}
\begin{markdown}
Hello *world*!
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” A frozen cache will also be produced in the `cache.tex`
output file as we requested using the `finalizecache` and `frozenCacheFileName`
options.

Next, create a new text document `frozen-document.tex` with the following
content:
``` tex
\documentclass[frozencache]{article}
\usepackage[frozenCacheFileName=cache.tex]{markdown}
\begin{document}
\begin{markdown}
Hi *world*!
\end{markdown}
\end{document}
```````
Last, invoke pdfTeX without shell access from the terminal:
``` sh
pdflatex -no-shell-escape frozen-document.tex
``````
A PDF document named `frozen-document.pdf` should be produced and contain the
text “Hello *world*!” Since we used the contents of the frozen cache using
the `frozencache` option, we were able to typeset the document without
accessing the shell or invoking Lua, but the change in the content of the
markdown document from “Hello *world*!” to “Hi *world*!” was not reflected.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown
  [
    finalizeCache = yes,
    frozenCacheFileName = cache.tex,
  ]
\starttext
\startmarkdown
Hello *world*!
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” A frozen cache will also be produced in the `cache.tex`
output file as we requested using the `finalizeCache` and `frozenCacheFileName`
options.

Next, create a new text document `frozen-document.tex` with the following
content:
``` tex
\usemodule[t][markdown]
\setupmarkdown
  [
    frozenCache = yes,
    frozenCacheFileName = cache.tex,
  ]
\starttext
\startmarkdown
Hi *world*!
\stopmarkdown
\stoptext
```````
Last, invoke pdfTeX without shell access from the terminal:
``` sh
texexec --passon=--no-shell-escape frozen-document.tex
``````
A PDF document named `frozen-document.pdf` should be produced and contain the
text “Hello *world*!” Since we used the contents of the frozen cache using
the `\markdownOptionFrozenCache` option, we were able to typeset the document
without accessing the shell or invoking Lua, but the change in the content of
the markdown document from “Hello *world*!” to “Hi *world*!” was not reflected.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { frozenCacheFileName }
  { path }
  { \markdownOptionCacheDir / frozenCache.tex }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.frozenCacheFileName = "frozenCache.tex"
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>
% \fi
% \begin{markdown}
%
%### Parser Options
%
% \end{markdown}
% \par
% \iffalse

#### Option `blankBeforeBlockquote`

`blankBeforeBlockquote` (default value: `false`)

% \fi
% \begin{markdown}
% \Optitem[false]{blankBeforeBlockquote}{\opt{true}, \opt{false}}
%
:    true

     :  Require a blank line between a paragraph and the following blockquote.

     false

     :  Do not require a blank line between a paragraph and the following
        blockquote.

% \end{markdown}
% \iffalse

##### Lua Module Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\directlua{
  local markdown = require("markdown")
  local newline = [[^^J^^J]]
  local convert, input

  convert = markdown.new()
  input = "A paragraph." .. newline ..
          "> A quote."   .. newline
  tex.sprint(convert(input))

  convert = markdown.new({blankBeforeBlockquote = true})
  input = "A paragraph."   .. newline ..
          "> Not a quote." .. newline
  tex.sprint(convert(input)) }
\bye
```````
Then, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
```````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> > A quote.
>
> A paragraph > Not a quote.

##### Lua CLI Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\input optionfalse
\input optiontrue
\bye
```````
Using a text editor, create a text document named `content.md` with the
following content:
``` md
A paragraph.
> A quote?
``````
Next, invoke LuaTeX from the terminal:
``` sh
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
texlua ⟨CLI pathname⟩ blankBeforeBlockquote=true -- content.md optiontrue.tex
luatex document.tex
```````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> > A quote?
>
> A paragraph. > A quote?

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown

\markdownBegin
A paragraph.
> A quote.
\markdownEnd

\def\markdownOptionBlankBeforeBlockquote{true}
\markdownBegin
A paragraph.
> Not a quote.
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> > A quote.
>
> A paragraph > Not a quote.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{document}

\begin{markdown}
A paragraph.
> A quote.
\end{markdown}

\begin{markdown*}{blankBeforeBlockquote}
A paragraph.
> Not a quote.
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> > A quote.
>
> A paragraph > Not a quote.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\starttext

\startmarkdown
A paragraph.
> A quote.
\stopmarkdown

\setupmarkdown[blankBeforeBlockquote = yes]
\startmarkdown
A paragraph.
> Not a quote.
\stopmarkdown

\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> > A quote.
>
> A paragraph > Not a quote.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { blankBeforeBlockquote }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.blankBeforeBlockquote = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `blankBeforeCodeFence`

`blankBeforeCodeFence` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{blankBeforeCodeFence}{\opt{true}, \opt{false}}
%
:    true

     :  Require a blank line between a paragraph and the following fenced code
        block.

     false

     :  Do not require a blank line between a paragraph and the following
        fenced code block.

% \end{markdown}
% \iffalse

##### Lua Module Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\directlua{
  local markdown = require("markdown")
  local newline = [[^^J^^J]]
  local convert, input

  convert = markdown.new({fencedCode = true})
  input = "A paragraph."   .. newline ..
          "```"            .. newline ..
          "A fenced code." .. newline ..
          "```"            .. newline
  tex.sprint(convert(input))

  convert = markdown.new({
    fencedCode = true, blankBeforeCodeFence = true})
  input = "A paragraph."       .. newline ..
          "```"                .. newline ..
          "Not a fenced code." .. newline ..
          "```"                .. newline
  tex.sprint(convert(input)) }
\bye
```````
Then, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
```````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> ```
> A fenced code.
> ```
>
> A paragraph. ``` Not a fenced code. ```

##### Lua CLI Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\input optionfalse
\input optiontrue
\bye
```````
Using a text editor, create a text document named `content.md` with the
following content:
```` md
A paragraph.
```
A code fence?
```
```````
Next, invoke LuaTeX from the terminal:
``` sh
texlua ⟨CLI pathname⟩ fencedCode=true -- content.md optionfalse.tex
texlua ⟨CLI pathname⟩ fencedCode=true blankBeforeCodeFence=true  -- content.md optiontrue.tex
luatex document.tex
```````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> ```
> A code fence?
> ```
>
> A paragraph. ``` A code fence? ```

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
```` tex
\input markdown
\def\markdownOptionFencedCode{true}

\markdownBegin
A paragraph.
```
A fenced code.
```
\markdownEnd

\def\markdownOptionBlankBeforeCodeFence{true}
\markdownBegin
A paragraph.
```
Not a fenced code.
```
\markdownEnd

\bye
````````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> ```
> A fenced code.
> ```
>
> A paragraph. ``` Not a fenced code. ```

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
```` tex
\documentclass{article}
\usepackage[fencedCode]{markdown}
\begin{document}

\begin{markdown}
A paragraph.
```
A fenced code.
```
\end{markdown}

\begin{markdown*}{blankBeforeCodeFence}
A paragraph.
```
Not a fenced code.
```
\end{markdown*}

\end{document}
````````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> ```
> A fenced code.
> ```
>
> A paragraph. ``` Not a fenced code. ```

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
```` tex
\usemodule[t][markdown]
\setupmarkdown[fencedCode = yes]
\starttext

\startmarkdown
A paragraph.
```
A fenced code.
```
\stopmarkdown

\setupmarkdown[blankBeforeCodeFence = yes]
\startmarkdown
A paragraph.
```
Not a fenced code.
```
\stopmarkdown

\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> ```
> A fenced code.
> ```
>
> A paragraph. ``` Not a fenced code. ```

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { blankBeforeCodeFence }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.blankBeforeCodeFence = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `blankBeforeDivFence`

`blankBeforeDivFence` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{blankBeforeDivFence}{\opt{true}, \opt{false}}
%
:    true

     :  Require a blank line before the closing fence of a fenced div.

     false

     :  Do not require a blank line before the closing fence of a fenced div.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
```` tex
\documentclass{article}
\usepackage[fencedDivs]{markdown}
\begin{document}

\begin{markdown}
A paragraph.

::: {.identifier}
A fenced div.
:::
\end{markdown}

\begin{markdown*}{blankBeforeDivFence}
A paragraph.

::: {.identifier}
Not a fenced div.
:::
\end{markdown*}

\end{document}
````````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> A fenced div.
>
> A paragraph.
>
> ::: {.identifier} Not a fenced div. :::

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { blankBeforeDivFence }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.blankBeforeDivFence = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `blankBeforeHeading`

`blankBeforeHeading` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{blankBeforeHeading}{\opt{true}, \opt{false}}
%
:    true

     :  Require a blank line between a paragraph and the following header.

     false

     :  Do not require a blank line between a paragraph and the following
        header.

% \end{markdown}
% \iffalse

##### Lua Module Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\def\markdownRendererHeadingOne#1{{\bf #1}\par}
\directlua{
  local markdown = require("markdown")
  local newline = [[^^J^^J]]
  local convert, input

  convert = markdown.new()
  input = "A paragraph." .. newline ..
          "A heading."   .. newline ..
          "=========="   .. newline
  tex.sprint(convert(input))

  convert = markdown.new({blankBeforeHeading = true})
  input = "A paragraph."    .. newline ..
          "Not a heading."  .. newline ..
          "=============="  .. newline
  tex.sprint(convert(input)) }
\bye
```````
Then, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
```````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> A heading.
> ==========
>
> A paragraph. Not a heading. ==============

##### Lua CLI Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\input optionfalse
\input optiontrue
\bye
```````
Using a text editor, create a text document named `content.md` with the
following content:
``` md
A paragraph.
A heading?
==========
``````
Next, invoke LuaTeX from the terminal:
``` sh
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
texlua ⟨CLI pathname⟩ blankBeforeHeading=true  -- content.md optiontrue.tex
luatex document.tex
```````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> A heading?
> ==========
>
> A paragraph. A heading? ==========

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown

\markdownBegin
A paragraph.
A heading.
==========
\markdownEnd

\def\markdownOptionBlankBeforeHeading{true}
\markdownBegin
A paragraph.
Not a heading.
==============
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> A heading.
> ==========
>
> A paragraph. Not a heading. ==============

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{document}

\begin{markdown}
A paragraph.
A heading.
==========
\end{markdown}

\begin{markdown*}{blankBeforeHeading}
A paragraph.
Not a heading.
==============
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> A heading.
> ==========
>
> A paragraph. Not a heading. ==============

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\starttext

\startmarkdown
A paragraph.
A heading.
==========
\stopmarkdown

\setupmarkdown[blankBeforeHeading = yes]
\startmarkdown
A paragraph.
Not a heading.
==============
\stopmarkdown

\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A paragraph.
>
> A heading.
> ==========
>
> A paragraph. Not a heading. ==============

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { blankBeforeHeading }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.blankBeforeHeading = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `bracketedSpans`

`bracketedSpans` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{bracketedSpans}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the Pandoc bracketed spans extension:

        ``` md
        [This is *some text*]{.class key="val"}
        ``````

:    false

     :  Disable the Pandoc bracketed spans extension:

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
```` tex
\documentclass{article}
\usepackage[bracketedSpans]{markdown}
\usepackage{expl3}
\ExplSyntaxOn
\markdownSetup{
  renderers = {
    bracketedSpanAttributeContextBegin = {
      \group_begin:
      \color_group_begin:
      \markdownSetup{
        renderers = {
          attributeKeyValue = {
            \str_if_eq:nnT
              { ##1 }
              { color }
              {
                 \color_select:n { ##2 }
              }
          },
        },
      }
    },
    bracketedSpanAttributeContextEnd = {
      \color_group_end:
      \group_end:
    },
  },
}
\ExplSyntaxOff
\begin{document}
\begin{markdown}
Here is some [colored text]{color=red}.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Here is some <span style="color: red">colored text</span>.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { bracketedSpans }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.bracketedSpans = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `breakableBlockquotes`

`breakableBlockquotes` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{breakableBlockquotes}{\opt{true}, \opt{false}}
%
:    true

     :  A blank line separates block quotes.

     false

     :  Blank lines in the middle of a block quote are ignored.

% \end{markdown}
% \iffalse

##### Lua Module Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\def\markdownRendererHeadingOne#1{{\bf #1}\par}
\directlua{
  local markdown = require("markdown")
  local newline = [[^^J^^J]]
  local convert, input

  convert = markdown.new()
  input = "> A single"     .. newline .. newline ..
          "> block quote." .. newline
  tex.sprint(convert(input))

  convert = markdown.new({breakableBlockquotes = true})
  input = "> A block quote."       .. newline .. newline ..
          "> Another block quote." .. newline
  tex.sprint(convert(input)) }
\bye
```````
Then, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
```````
A PDF document named `document.pdf` should be produced and contain the
following text:

> > A single block quote.
>
> > A block quote.
>
> > Another block quote.

##### Lua CLI Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\input optionfalse
\input optiontrue
\bye
```````
Using a text editor, create a text document named `content.md` with the
following content:
``` md
> A single block quote

> or two block quotes?
``````
Next, invoke LuaTeX from the terminal:
``` sh
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
texlua ⟨CLI pathname⟩ breakableBlockquotes=true  -- content.md optiontrue.tex
luatex document.tex
```````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

A PDF document named `document.pdf` should be produced and contain the
following text:

> > A single block quote or two block quotes?
>
> > A single block quote
>
> > or two block quotes?

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown

\markdownBegin
> A single

> block quote.
\markdownEnd

\def\markdownOptionBreakableBlockquotes{true}
\markdownBegin
> A block quote.

> Another block quote.
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> > A single block quote.
>
> > A block quote.
>
> > Another block quote.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{document}

\begin{markdown}
> A single

> block quote.
\end{markdown}

\begin{markdown*}{breakableBlockquotes}
> A block quote.

> Another block quote.
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> > A single block quote.
>
> > A block quote.
>
> > Another block quote.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\starttext

\startmarkdown
> A single

> block quote.
\stopmarkdown

\setupmarkdown[breakableBlockquotes = yes]
\startmarkdown
> A block quote.

> Another block quote.
\stopmarkdown

\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> > A single block quote.
>
> > A block quote.
>
> > Another block quote.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { breakableBlockquotes }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.breakableBlockquotes = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `citationNbsps`

`citationNbsps` (default value: `true`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{citationNbsps}{\opt{true}, \opt{false}}
%
:    true

     :  Replace regular spaces with non-breaking spaces inside the prenotes
        and postnotes of citations produced via the pandoc citation syntax
        extension.

     false

     :  Do not replace regular spaces with non-breaking spaces inside the
        prenotes and postnotes of citations produced via the pandoc citation
        syntax extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.bib` with the
following content:
``` bib
@book{knuth:tex,
  author    = "Knuth, Donald Ervin",
  title     = "The \TeX book, volume A of Computers and typesetting",
  publisher = "Addison-Wesley",
  year      = "1984"
}
```````
Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[citations]{markdown}
\begin{document}

\begin{markdown}
The TeXbook [@knuth:tex, p. 123 and 130] is good.
\end{markdown}

\begin{markdown*}{citationNbsps = false}
The TeXbook [@knuth:tex, p. 123 and 130] is good.
\end{markdown*}

\bibliographystyle{plain}
\bibliography{document.bib}
\end{document}
```````
Next, invoke LuaTeX and BibTeX from the terminal:
``` sh
lualatex document.tex
bibtex document.aux
lualatex document.tex
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text, where the middot (`·`) denotes a non-breaking space:

> The TeXbook [1, p.·123·and·130] is good.
>
> The TeXbook [1, p. 123 and 130] is good.
>
> ### References
> [1] Donald·Ervin Knuth. _The TeXbook, volume A of Computers and typesetting._
> Addison-Wesley, 1984.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { citationNbsps }
  { boolean }
  { true }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.citationNbsps = true
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `citations`

`citations` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{citations}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the Pandoc citation syntax extension:

        ``` md
        Here is a simple parenthetical citation [@doe99] and here
        is a string of several [see @doe99, pp. 33-35; also
        @smith04, chap. 1].

        A parenthetical citation can have a [prenote @doe99] and
        a [@smith04 postnote]. The name of the author can be
        suppressed by inserting a dash before the name of an
        author as follows [-@smith04].

        Here is a simple text citation @doe99 and here is
        a string of several @doe99 [pp. 33-35; also @smith04,
        chap. 1]. Here is one with the name of the author
        suppressed -@doe99.
        ``````

:    false

     :  Disable the Pandoc citation syntax extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.bib` with the
following content:
``` bib
@book{knuth:tex,
  author    = "Knuth, Donald Ervin",
  title     = "The \TeX book, volume A of Computers and typesetting",
  publisher = "Addison-Wesley",
  year      = "1984"
}
```````
Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[backend=biber]{biblatex}
\addbibresource{document.bib}
\usepackage[citations]{markdown}
\begin{document}

\begin{markdown}
The TeXbook [@knuth:tex, p. 123 and 130] was written by @knuth:tex.
\end{markdown}

\printbibliography
\end{document}
```````
Next, invoke LuaTeX and Biber from the terminal:
``` sh
lualatex document.tex
biber document.bcf
lualatex document.tex
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> The TeXbook [1, p.·123 and 130] was written by Knuth [1].
>
> ### References
> [1] Donald Ervin Knuth. _The \TeX{}book, volume A of Computers and typesetting._
> Addison-Wesley, 1984.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { citations }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.citations = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `codeSpans`

`codeSpans` (default value: `true`)

% \fi
% \begin{markdown}
%
% \Optitem[true]{codeSpans}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the code span syntax:

        ~~~ md
        Use the `printf()` function.
        ``There is a literal backtick (`) here.``
        ~~~

:    false

     :  Disable the code span syntax. This allows you to easily
        use the quotation mark ligatures in texts that do not contain code
        spans:

        ~~~
        ``This is a quote.''
        ~~~~~~

% \end{markdown}
% \iffalse

##### Lua Module Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new()
  local input =
    "``This is a code span.'' " ..
    "``This is no longer a code span.''"
  tex.sprint(convert(input)) }
\par
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new({codeSpans = false})
  local input =
    "``This is a quote.'' " ..
    "``This is another quote.''"
  tex.sprint(convert(input)) }
\bye
```````
Then, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
```````
A PDF document named `document.pdf` should be produced and contain the
following text:

> ``This is a code span.'' ``This is no longer a code span.''
>
> “This is a quote.” “This is another quote.”

##### Lua CLI Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\input optionfalse
\par
\input optiontrue
\bye
```````
Using a text editor, create a text document named `content.md` with the
following content:
``` md
``Is this a code span?'' ``Or a quote?''
``````
Next, invoke LuaTeX from the terminal:
``` sh
texlua ⟨CLI pathname⟩ codeSpans=false -- content.md optionfalse.tex
texlua ⟨CLI pathname⟩ -- content.md optiontrue.tex
luatex document.tex
```````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

A PDF document named `document.pdf` should be produced and contain the
following text:

> “Is this a code span?” “Or a quote?”
>
> ``Is this a code span?'' ``Or a quote?''

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown

\markdownBegin
``This is a code span.''
``This is no longer a code span.''
\markdownEnd

\def\markdownOptionCodeSpans{false}
\markdownBegin
``This is a quote.''
``This is another quote.''
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> ``This is a code span.'' ``This is no longer a code span.''
>
> “This is a quote.” “This is another quote.”

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{document}

\begin{markdown}
``This is a code span.''
``This is no longer a code span.''
\end{markdown}

\begin{markdown*}{codeSpans=false}
``This is a quote.''
``This is another quote.''
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> ``This is a code span.'' ``This is no longer a code span.''
>
> “This is a quote.” “This is another quote.”

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\starttext

\startmarkdown
``This is a code span.''
``This is no longer a code span.''
\stopmarkdown

\setupmarkdown[codeSpans = no]
\startmarkdown
``This is a quote.''
``This is another quote.''
\stopmarkdown

\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> ``This is a code span.'' ``This is no longer a code span.''
>
> “This is a quote.” “This is another quote.”

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { codeSpans }
  { boolean }
  { true }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.codeSpans = true
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `contentBlocks`

`contentBlocks` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{contentBlocks}{\opt{true}, \opt{false}}
%
:    true

     :   Enable the
%        iA\,Writer content blocks syntax extension~[@sotkov17]:
%        \iffalse
         iA\,Writer content blocks syntax extension:
%        \fi

        ``` md
        http://example.com/minard.jpg (Napoleon's
          disastrous Russian campaign of 1812)
        /Flowchart.png "Engineering Flowchart"
        /Savings Account.csv 'Recent Transactions'
        /Example.swift
        /Lorem Ipsum.txt
        ``````

:    false

     :   Disable the
         iA\,Writer content blocks syntax extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `table.csv` with the
following content:
``` csv
Name,Surname,Born
Albert,Einstein,1879
Marie,Curie,1867
Thomas,Edison,1847
```````
Create also a text document named `markdown-languages.json` with the following
content:
``` js
{
  "tex": "LaTeX"
}
``````
Create also a text document named `code.tex` with the following content:
``` tex
This is an example code listing in \LaTeX.
```````
Create also a text document named `part.md` with the following content:
``` md
This is a *transcluded markdown document*.
``````
Create also a text document named `document.tex` with the following content:
``` tex
\documentclass{article}
\usepackage{minted}
\usepackage[contentBlocks]{markdown}
\begin{document}
\begin{markdown}
/table.csv  (An example table)
/code.tex   (An example code listing)
/part.md    (A file transclusion example)
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex --shell-escape document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> | Name   | Surname  | Born |
> | ------ | ---------| ---- |
> | Albert | Einstein | 1879 |
> | Marie  | Curie    | 1867 |
> | Thomas | Edison   | 1847 |
>
> Table 1: An example table
>
> ``` tex
> This is an example code listing in \LaTeX.
> ```````
>
> This is a *transcluded markdown document*.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `table.csv` with the
following content:
``` csv
Name,Surname,Born
Albert,Einstein,1879
Marie,Curie,1867
Thomas,Edison,1847
```````
Create also a text document named `markdown-languages.json` with the following
content:
``` js
{
  "tex": "ConTeXt"
}
``````
Create also a text document named `code.tex` with the following content:
``` tex
This is an example code listing in \ConTeXt.
```````
Create also a text document named `part.md` with the following content:
``` md
This is a *transcluded markdown document*.
``````
Create also a text document named `document.tex` with the following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[contentBlocks = yes]
\definetyping [ConTeXt]
\setuptyping  [ConTeXt] [option=TEX]
\starttext
\startmarkdown
/table.csv  (An example table)
/code.tex   (An example code listing)
/part.md    (A file transclusion example)
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> | Name   | Surname  | Born |
> | ------ | ---------| ---- |
> | Albert | Einstein | 1879 |
> | Marie  | Curie    | 1867 |
> | Thomas | Edison   | 1847 |
>
> Table 1: An example table
>
> ``` tex
> This is an example code listing in \ConTeXt.
> ```````
>
> This is a *transcluded markdown document*.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { contentBlocks }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.contentBlocks = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `debugExtensions`

`debugExtensions` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{debugExtensions}{\opt{true}, \opt{false}}
%
:    true

     :   Produce a \acro{JSON} file that will contain the
         extensible subset of the \acro{peg} grammar of markdown
%        (see the \luamref{walkable_syntax} hash table)
         after built-in syntax extensions
%        (see Section <#sec:luabuiltinextensions>)
%        \iffalse
         (see options \Opt{citations}, \Opt{contentBlocks},
         \Opt{definitionLists}, etc.)
%        \fi
         and user-defined syntax extensions
%        (see Section <#sec:luauserextensions>)
%        \iffalse
         (see option \Opt{extensions})
%        \fi
         have been applied. This helps you to see how the different
         extensions interact. The name of the produced \acro{JSON} file is
         controlled by the \Opt{debugExtensionsFileName} option.

:    false

     :  Do not produce a \acro{JSON} file with the \acro{peg} grammar of
        markdown.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `strike-through.lua` with the
following content:
``` lua
local strike_through = {
  api_version = 2,
  grammar_version = 2,
  finalize_grammar = function(reader)
    local nonspacechar = lpeg.P(1) - lpeg.S("\t ")
    local doubleslashes = lpeg.P("//")
    local function between(p, starter, ender)
      ender = lpeg.B(nonspacechar) * ender
      return (starter * #nonspacechar
             * lpeg.Ct(p * (p - ender)^0) * ender)
    end

    local read_strike_through = between(
      lpeg.V("Inline"), doubleslashes, doubleslashes
    ) / function(s) return {"\\st{", s, "}"} end

    reader.insert_pattern("Inline after Emph", read_strike_through,
                          "StrikeThrough")
    reader.add_special_character("/")
  end
}

return strike_through
```````
Using a text editor, create also a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{soul}
\usepackage[extension = strike-through.lua,
            debugExtensions]{markdown}
\begin{document}
\begin{markdown}
This is //a lunar roving vehicle// strike-through text.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is ~~a lunar roving vehicle~~ strike-through text.

Furthermore, a JSON document named `document.debug-extensions.json` should also
be produced and contain the following text:

``` json
{
    "Block": [
        "Blockquote",
        "Verbatim",
        "ThematicBreak",
        "BulletList",
        "OrderedList",
        "Heading",
        "DisplayHtml",
        "Paragraph",
        "Plain"
    ],
    "Inline": [
        "Str",
        "Space",
        "Endline",
        "UlOrStarLine",
        "Strong",
        "Emph",
        "StrikeThrough (user-defined \"./strike-through.lua\" syntax extension)",
        "Link",
        "Image",
        "Code",
        "AutoLinkUrl",
        "AutoLinkEmail",
        "AutoLinkRelativeReference",
        "InlineHtml",
        "HtmlEntity",
        "EscapedChar",
        "Smart",
        "Symbol"
    ]
}
````````

This output shows us that our user-defined syntax extension has been correctly
inserted to the grammar of markdown.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { debugExtensions }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.debugExtensions = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `definitionLists`

`definitionLists` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{definitionLists}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the pandoc definition list syntax extension:

        ``` md
        Term 1

        :   Definition 1

        Term 2 with *inline markup*

        :   Definition 2

                { some code, part of Definition 2 }

            Third paragraph of definition 2.
        `````

:    false

     :  Disable the pandoc definition list syntax extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[definitionLists]{markdown}
\begin{document}
\begin{markdown}
Term 1

:   Definition 1

Term 2 with *inline markup*

:   Definition 2

        { some code, part of Definition 2 }

    Third paragraph of definition 2.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Term 1
> 
> :   Definition 1
> 
> Term 2 with *inline markup*
> 
> :   Definition 2
> 
>         { some code, part of Definition 2 }
> 
>     Third paragraph of definition 2.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[definitionLists = yes]
\starttext
\startmarkdown
Term 1

:   Definition 1

Term 2 with *inline markup*

:   Definition 2

        { some code, part of Definition 2 }

    Third paragraph of definition 2.
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Term 1
> 
> :   Definition 1
> 
> Term 2 with *inline markup*
> 
> :   Definition 2
> 
>         { some code, part of Definition 2 }
> 
>     Third paragraph of definition 2.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { definitionLists }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.definitionLists = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `eagerCache`

`eagerCache` (default value: `true`)

% \fi
% \begin{markdown}
%
% \Optitem[true]{eagerCache}{\opt{true}, \opt{false}}
%
:    true

     :  Converted markdown documents will be cached in \Opt{cacheDir}. This can be
        useful for post-processing the converted documents and for recovering
        historical versions of the documents from the cache.  However, it also
        produces a large number of auxiliary files on the disk and obscures the
        output of the Lua command-line interface when it is used for plumbing.

        This behavior will always be used if the \Opt{finalizeCache} option is
        enabled.

:    false

     :  Converted markdown documents will not be cached. This decreases the number
        of auxiliary files that we produce and makes it easier to use the Lua
        command-line interface for plumbing.

        This behavior will only be used when the \Opt{finalizeCache} option is
        disabled. Recursive nesting of markdown document fragments is undefined
        behavior when \Opt{eagerCache} is disabled.

% \end{markdown}
% \iffalse

##### Lua Module Example {.unnumbered}

Using a text editor, create a text document named `hello.md` with the
following content:
``` md
Hello *world*!
``````
Next, invoke LuaTeX from the terminal with the \Opt{eagerCache} option
disabled:
``` sh
texlua ⟨CLI pathname⟩ eagerCache=false -- hello.md hello.tex
```````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

A \TeX{} document named `hello.tex` should be produced and contain the
following code:
``` tex
Hello \markdownRendererEmphasis{world}!\relax
```

***

Invoke LuaTeX from the terminal again, this time with the \Opt{eagerCache}
option enabled:

``` tex
texlua ⟨CLI pathname⟩ eagerCache=true -- hello.md hello.tex
```

A \TeX{} document named `hello.tex` should be produced and contain the
following code:

``` tex
\input ./⟨hash⟩.md.tex\relax
```

Additionally, a \TeX{} document named `⟨hash⟩.md.tex` should be produced and
contain the following code:

``` tex
Hello \markdownRendererEmphasis{world}!\relax
```

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { eagerCache }
  { boolean }
  { true }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.eagerCache = true
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `expectJekyllData`

`expectJekyllData` (default value: `false`)

% \fi
% \markdownBegin
%
% \Optitem[false]{expectJekyllData}{\opt{true}, \opt{false}}
%
:    false

     :  When the \Opt{jekyllData} option is enabled, then a markdown document
        may begin with \acro{yaml} metadata if and only if the metadata begin
        with the end-of-directives marker (`---`) and they end with either the
        end-of-directives or the end-of-document marker (`...`):

        ~~~~~ latex
        \documentclass{article}
        \usepackage[jekyllData]{markdown}
        \begin{document}
        \begin{markdown}
        ---
        - this
        - is
        - YAML
        ...
        - followed
        - by
        - Markdown
        \end{markdown}
        \begin{markdown}
        - this
        - is
        - Markdown
        \end{markdown}
        \end{document}
        ~~~~~~~~~~~

:    true

     :  When the \Opt{jekyllData} option is enabled, then a markdown document may
        begin directly with \acro{yaml} metadata and may contain nothing but
        \acro{yaml} metadata.

        ~~~~~ latex
        \documentclass{article}
        \usepackage[jekyllData, expectJekyllData]{markdown}
        \begin{document}
        \begin{markdown}
        - this
        - is
        - YAML
        ...
        - followed
        - by
        - Markdown
        \end{markdown}
        \begin{markdown}
        - this
        - is
        - YAML
        \end{markdown}
        \end{document}
        ~~~~~~~~~~~

% \markdownEnd
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `jane-doe.yml` with the
following content:
``` yaml
name: Jane Doe
age:  99
```
Using a text editor, create also a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[jekyllData]{markdown}
\markdownSetup{
  jekyllDataRenderers = {
    name = {\gdef\name{#1}},
    code = {\gdef\age{#1}},
  },
  renderers = {
    jekyllDataEnd = {\name{} is \age{} years old.},
  }
}
\begin{document}
\markdownInput[expectJekyllData]{jane-doe.yml}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Jane Doe is 99 years old.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { expectJekyllData }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.expectJekyllData = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `extensions`

`extensions` (default value: `{}`)

% \fi
% \begin{markdown}
%
% \Valitem[\{\}]{extensions}{filenames}
%
:    The filenames of user-defined syntax extensions that will be applied to the
     markdown reader. If the \pkg{kpathsea} library is available, files will be
     searched for not only in the current working directory but also in the
     \TeX{} directory structure.

%    A user-defined syntax extension is a Lua file in the following format:
%
%    ``` lua
%    local strike_through = {
%      api_version = 2,
%      grammar_version = 2,
%      finalize_grammar = function(reader)
%        local nonspacechar = lpeg.P(1) - lpeg.S("\t ")
%        local doubleslashes = lpeg.P("//")
%        local function between(p, starter, ender)
%          ender = lpeg.B(nonspacechar) * ender
%          return (starter * #nonspacechar
%                 * lpeg.Ct(p * (p - ender)^0) * ender)
%        end
%
%        local read_strike_through = between(
%          lpeg.V("Inline"), doubleslashes, doubleslashes
%        ) / function(s) return {"\\st{", s, "}"} end
%
%        reader.insert_pattern("Inline after Emph", read_strike_through,
%                              "StrikeThrough")
%        reader.add_special_character("/")
%      end
%    }
%
%    return strike_through
%    ```````
%
%    The `api_version` and `grammar_version` fields specify the version of the
%    user-defined syntax extension API and the markdown grammar for which
%    the extension was written. See the current API and grammar versions
%    below:
%
% \end{markdown}
% \iffalse
%</manual-options>
%<*lua>
% \fi
%  \begin{macrocode}
metadata.user_extension_api_version = 2
metadata.grammar_version = 2
%    \end{macrocode}
% \iffalse
%</lua>
%<*manual-options>
% \fi
% \begin{markdown}
%
%    Any changes to the syntax extension API or grammar will cause the
%    corresponding current version to be incremented.  After Markdown 3.0.0,
%    any changes to the API and the grammar will be either backwards-compatible
%    or constitute a breaking change that will cause the major version of the
%    Markdown package to increment (to 4.0.0).
%
%    The `finalize_grammar` field is a function that finalizes the grammar of
%    markdown using the interface of a Lua \luamref{reader} object, such as
%    the \luamref{reader->insert_pattern} and
%    \luamref{reader->add_special_character} methods,
%    see Section <#luauserextensions>.
%
% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `strike-through.lua` with the
following content:
``` lua
local strike_through = {
  api_version = 2,
  grammar_version = 2,
  finalize_grammar = function(reader)
    local nonspacechar = lpeg.P(1) - lpeg.S("\t ")
    local doubleslashes = lpeg.P("//")
    local function between(p, starter, ender)
      ender = lpeg.B(nonspacechar) * ender
      return (starter * #nonspacechar
             * lpeg.Ct(p * (p - ender)^0) * ender)
    end

    local read_strike_through = between(
      lpeg.V("Inline"), doubleslashes, doubleslashes
    ) / function(s) return {"\\st{", s, "}"} end

    reader.insert_pattern("Inline after Emph", read_strike_through,
                          "StrikeThrough")
    reader.add_special_character("/")
  end
}

return strike_through
```````
Using a text editor, create also a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{soul}
\usepackage[extension = strike-through.lua]{markdown}
\begin{document}
\begin{markdown}
This is //a lunar roving vehicle// strike-through text.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is ~~a lunar roving vehicle~~ strike-through text.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\cs_generate_variant:Nn
  \@@_add_lua_option:nnn
  { nnV }
\@@_add_lua_option:nnV
  { extensions }
  { clist }
  \c_empty_clist
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.extensions = {}
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `fancyLists`

`fancyLists` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{fancyLists}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the Pandoc fancy list extension:

        ``` md
        a) first item
        b) second item
        c) third item
        ``````

:    false

     :  Disable the Pandoc fancy list extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
```` tex
\documentclass{article}
\usepackage{minted}
\usepackage[fancyLists]{markdown}
\begin{document}
\begin{markdown}
a) first item
b) second item
c) third item
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex --shell-escape document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> a) first item
> b) second item
> c) third item

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
```` tex
\usemodule[t][markdown]
\setupmarkdown[fancyLists = yes]
\starttext
\startmarkdown
a) first item
b) second item
c) third item
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> a) first item
> b) second item
> c) third item

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { fancyLists }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.fancyLists = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `fencedCode`

`fencedCode` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{fencedCode}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the commonmark fenced code block extension:

        ~~~~~~~~ md
        ~~~ js
        if (a > 3) {
            moveShip(5 * gravity, DOWN);
        }
        ~~~~~~

          ``` html
          <pre>
            <code>
              // Some comments
              line 1 of code
              line 2 of code
              line 3 of code
            </code>
          </pre>
          ```
        ~~~~~~~~~~~

:    false

     :  Disable the commonmark fenced code block extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
```` tex
\documentclass{article}
\usepackage{minted}
\usepackage[fencedCode]{markdown}
\begin{document}
\begin{markdown}
~~~ js
if (a > 3) {
    moveShip(5 * gravity, DOWN);
}
~~~~~~

  ``` html
  <pre>
    <code>
      // Some comments
      line 1 of code
      line 2 of code
      line 3 of code
    </code>
  </pre>
  ```
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex --shell-escape document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> ``` js
> if (a > 3) {
>     moveShip(5 * gravity, DOWN);
> }
> ```
> 
> ``` html
> <pre>
>   <code>
>     // Some comments
>     line 1 of code
>     line 2 of code
>     line 3 of code
>   </code>
> </pre>
> ```

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
```` tex
\usemodule[t][markdown]
\setupmarkdown[fencedCode = yes]
\definetyping [js]
\definetyping [html]
\setuptyping  [html] [option=XML]
\starttext
\startmarkdown
~~~ js
if (a > 3) {
    moveShip(5 * gravity, DOWN);
}
~~~~~~

  ``` html
  <pre>
    <code>
      // Some comments
      line 1 of code
      line 2 of code
      line 3 of code
    </code>
  </pre>
  ```
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> ``` js
> if (a > 3) {
>     moveShip(5 * gravity, DOWN);
> }
> ```
> 
> ``` html
> <pre>
>   <code>
>     // Some comments
>     line 1 of code
>     line 2 of code
>     line 3 of code
>   </code>
> </pre>
> ```

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { fencedCode }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.fencedCode = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `fencedDivs`

`fencedDivs` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{fencedDivs}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the Pandoc fenced divs extension:

        ``` md
        ::::: {#special .sidebar}
        Here is a paragraph.

        And another.
        :::::
        ``````

:    false

     :  Disable the Pandoc fenced divs extension:

% \end{markdown}
% \iffalse
%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { fencedDivs }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.fencedDivs = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `finalizeCache`

`finalizeCache` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{finalizeCache}{\opt{true}, \opt{false}}
%
:    Whether an output file specified with the \Opt{frozenCacheFileName} option
     (frozen cache) that contains a mapping between an enumeration of markdown
     documents and their auxiliary cache files will be created.

     The frozen cache makes it possible to later typeset a plain \TeX{}
     document that contains markdown documents without invoking Lua using
     the \Opt{frozenCache} plain \TeX{} option. As a result, the
     plain \TeX{} document becomes more portable, but further changes in the
     order and the content of markdown documents will not be reflected.

% \end{markdown}
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionFinalizeCache{true}
\markdownBegin
Hello *world*!
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” A frozen cache will also be produced as we requested using the
`finalizeCache` option.

Next, change the content of `document.tex` as follows:
``` tex
\input markdown
\def\markdownOptionFrozenCache{true}
\markdownBegin
Hi *world*!
\markdownEnd
\bye
```````
Last, invoke pdfTeX without shell access from the terminal:
``` sh
pdftex -no-shell-escape document.tex
``````
A new PDF document named `document.pdf` should be produced and contain the
same text “Hello *world*!” Since we used the contents of the frozen cache using
the `\markdownOptionFrozenCache` option, we were able to typeset the document
without accessing the shell or invoking Lua, but the change in the content of
the markdown document from “Hello *world*!” to “Hi *world*!” was not reflected.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass[finalizecache]{article}
\usepackage{markdown}
\begin{document}
\begin{markdown}
Hello *world*!
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” A frozen cache will also be produced as we requested using the
`finalizecache` option.

Next, change the content of `document.tex` as follows:
``` tex
\documentclass[frozencache]{article}
\usepackage{markdown}
\begin{document}
\begin{markdown}
Hi *world*!
\end{markdown}
\end{document}
```````
Last, invoke pdfTeX without shell access from the terminal:
``` sh
pdflatex -no-shell-escape document.tex
``````
A new PDF document named `document.pdf` should be produced and contain the
same text “Hello *world*!” Since we used the contents of the frozen cache using
the `\markdownOptionFrozenCache` option, we were able to typeset the document
without accessing the shell or invoking Lua, but the change in the content of
the markdown document from “Hello *world*!” to “Hi *world*!” was not reflected.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[finalizeCache = yes]
\starttext
\startmarkdown
Hello *world*!
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” A frozen cache will also be produced in the `cache.tex`
output file as we requested using the `finalizeCache` option.

Next, change the content of `document.tex` as follows:
``` tex
\usemodule[t][markdown]
\setupmarkdown[frozenCache = yes]
\starttext
\startmarkdown
Hi *world*!
\stopmarkdown
\stoptext
```````
Last, invoke pdfTeX without shell access from the terminal:
``` sh
texexec --passon=--no-shell-escape document.tex
``````
A new PDF document named `document.pdf` should be produced and contain the
same text “Hello *world*!” Since we used the contents of the frozen cache using
the `\markdownOptionFrozenCache` option, we were able to typeset the document
without accessing the shell or invoking Lua, but the change in the content of
the markdown document from “Hello *world*!” to “Hi *world*!” was not reflected.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { finalizeCache }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.finalizeCache = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `frozenCacheCounter`

`frozenCacheCounter` (default value: `0`)

% \fi
% \begin{markdown}
%
% \Valitem[0]{frozenCacheCounter}{number}
%
:    The number of the current markdown document that will be stored in
     an output file (frozen cache) when the \Opt{finalizeCache} is enabled.
     When the document number is 0, then a new frozen cache will be created.
     Otherwise, the frozen cache will be appended.

     Each frozen cache entry will define a \TeX{} macro
     `\markdownFrozenCache`\meta{number} that will typeset markdown document
     number \meta{number}.

% \end{markdown}
% \iffalse

##### Lua Module Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\directlua{
  local markdown = require("markdown")
  local firstConvert = markdown.new({finalizeCache = true, frozenCacheCounter = 0})
  local firstInput = "Hello"
  local secondConvert = markdown.new({finalizeCache = true, frozenCacheCounter = 1})
  local secondInput = "*world*!"
  tex.sprint(firstConvert(firstInput) .. [[ ]] .. secondConvert(secondInput)) }
\bye
```````
Then, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
```````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!” A frozen cache with two entries will also be produced as we
requested using the `frozenCacheCounter` option.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { frozenCacheCounter }
  { counter }
  { 0 }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.frozenCacheCounter = 0
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `hardLineBreaks`

`hardLineBreaks` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{hardLineBreaks}{\opt{true}, \opt{false}}
%
:    true

     :  Interpret all newlines within a paragraph as hard line breaks instead
        of spaces.

:    false

     :  Interpret all newlines within a paragraph as spaces.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{document}

\begin{markdown}
'Twas brillig, and the slithy toves
Did gyre and gimble in the wabe;
All mimsy were the borogoves,
And the mome raths outgrabe.
\end{markdown}

\begin{markdown*}{hardLineBreaks}
'Twas brillig, and the slithy toves
Did gyre and gimble in the wabe;
All mimsy were the borogoves,
And the mome raths outgrabe.
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> 'Twas brillig, and the slithy toves
> Did gyre and gimble in the wabe;
> All mimsy were the borogoves,
> And the mome raths outgrabe.
>
> 'Twas brillig, and the slithy toves  
> Did gyre and gimble in the wabe;  
> All mimsy were the borogoves,  
> And the mome raths outgrabe.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { hardLineBreaks }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.hardLineBreaks = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `hashEnumerators`

`hashEnumerators` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{hashEnumerators}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the use of hash symbols (`#`) as ordered item list
        markers:

        ``` md
        #. Bird
        #. McHale
        #. Parish
        ``````

:    false

     :  Disable the use of hash symbols (`#`) as ordered item list
        markers.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{document}

\begin{markdown}
#. Bird
#. McHale
#. Parish
\end{markdown}

\begin{markdown*}{hashEnumerators}
#. Bird
#. McHale
#. Parish
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> . Bird
> ========
> . McHale
> ========
> . Parish
> ========
>
> #. Bird
> #. McHale
> #. Parish

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\starttext

\startmarkdown
#. Bird
#. McHale
#. Parish
\stopmarkdown

\setupmarkdown[hashEnumerators = yes]
\startmarkdown
#. Bird
#. McHale
#. Parish
\stopmarkdown

\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> . Bird
> ========
> . McHale
> ========
> . Parish
> ========
>
> #. Bird
> #. McHale
> #. Parish

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { hashEnumerators }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.hashEnumerators = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `headerAttributes` {#header-attributes}

`headerAttributes` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{headerAttributes}{\opt{true}, \opt{false}}
%
:    true

     :   Enable the assignment of HTML attributes to headings:

         ``` md
         # My first heading {#foo}

         ## My second heading ##    {#bar .baz}

         Yet another heading   {key=value}
         ===================
         ``````

:    false

     :   Disable the assignment of HTML attributes to headings.

% \end{markdown}
% \iffalse
%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { headerAttributes }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.headerAttributes = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `html`

`html` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{html}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the recognition of inline HTML tags, block HTML elements,
        HTML comments, HTML instructions, and entities in the input. Inline
        HTML tags, block HTML elements and HTML comments will be rendered, HTML
        instructions will be ignored, and HTML entities will be replaced with
        the corresponding Unicode codepoints.

:    false

     :  Disable the recognition of HTML markup. Any HTML markup in the input
        will be rendered as plain text.

% \end{markdown}
% \iffalse

##### Lua Module Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new()
  local newline = [[^^J^^J]]
  local input =
    "<div>*There is no block tag support.*</div>"        .. newline ..
    "*There is no <inline tag="tag"></inline> support.*" .. newline ..
    "_There is no <!-- comment --> support._"            .. newline ..
    "_There is no <? HTML instruction ?> support._"
  tex.sprint(convert(input)) }
\par
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new({html = true})
  local input =
    "<div>*There is block tag support.*</div>"        .. newline ..
    "*There is <inline tag="tag"></inline> support.*" .. newline ..
    "_There is <!-- comment --> support._"            .. newline ..
    "_There is <? HTML instruction ?> support._"
  tex.sprint(convert(input)) }
\bye
```````
Then, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
```````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \<div>There is no block tag support.\</div>
> There is no \<inline tag=”tag”>\</inline> support.
> There is no \<!-- comment --> support.
> There is no <? HTML instruction ?> support.
>
> There is support. There is support. There is support.

##### Lua CLI Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\input optionfalse
\par
\input optiontrue
\bye
```````
Using a text editor, create a text document named `content.md` with the
following content:
``` html
<div>
*Is there block tag support?*
</div>
*Is there <inline tag="tag"></inline> support?*
_Is there <!-- comment --> support?_
_Is there <? HTML instruction ?> support?_
````````
Next, invoke LuaTeX from the terminal:
``` sh
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
texlua ⟨CLI pathname⟩ html=true -- content.md optiontrue.tex
luatex document.tex
```````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

A PDF document named `document.pdf` should be produced and contain the
following text:

> \<div>Is there block tag support?\</div>
> Is there \<inline tag=”tag”>\</inline> support?
> Is there \<!-- comment --> support?
> Is there <? HTML instruction ?> support?
>
> Is there support? Is there support? Is there support?

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts

\markdownBegin
<div>
*There is no block tag support.*
</div>
*There is no <inline tag="tag"></inline> support.*
_There is no <!-- comment --> support._
_There is no <? HTML instruction ?> support._
\markdownEnd

\def\markdownOptionHtml{true}
\markdownBegin
<div>
*There is block tag support.*
</div>
*There is <inline tag="tag"></inline> support.*
_There is <!-- comment --> support._
_There is <? HTML instruction ?> support._
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \<div>There is no block tag support.\</div>
> There is no \<inline tag=”tag”>\</inline> support.
> There is no \<!-- comment --> support.
> There is no <? HTML instruction ?> support.
>
> There is support. There is support. There is support.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{document}

\begin{markdown}
<div>
*There is no block tag support.*
</div>
*There is no <inline tag="tag"></inline> support.*
_There is no <!-- comment --> support._
_There is no <? HTML instruction ?> support._
\end{markdown}

\begin{markdown*}{html}
<div>
*There is block tag support.*
</div>
*There is <inline tag="tag"></inline> support.*
_There is <!-- comment --> support._
_There is <? HTML instruction ?> support._
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \<div>There is no block tag support.\</div>
> There is no \<inline tag=”tag”>\</inline> support.
> There is no \<!-- comment --> support.
> There is no <? HTML instruction ?> support.
>
> There is support. There is support. There is support.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\starttext

\startmarkdown
<div>
*There is no block tag support.*
</div>
*There is no <inline tag="tag"></inline> support.*
_There is no <!-- comment --> support._
_There is no <? HTML instruction ?> support._
\stopmarkdown

\setupmarkdown[html = yes]
\startmarkdown
<div>
*There is block tag support.*
</div>
*There is <inline tag="tag"></inline> support.*
_There is <!-- comment --> support._
_There is <? HTML instruction ?> support._
\stopmarkdown

\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \<div>There is no block tag support.\</div>
> There is no \<inline tag=”tag”>\</inline> support.
> There is no \<!-- comment --> support.
> There is no <? HTML instruction ?> support.
>
> There is support. There is support. There is support.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { html }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.html = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `hybrid`

`hybrid` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{hybrid}{\opt{true}, \opt{false}}
%
:    true

     :  Disable the escaping of special plain \TeX{} characters, which makes it
        possible to intersperse your markdown markup with \TeX{} code.  The
        intended usage is in documents prepared manually by a human author.
        In such documents, it can often be desirable to mix \TeX{} and markdown
        markup freely.

:    false

     :  Enable the escaping of special plain \TeX{} characters outside verbatim
        environments, so that they are not interpretted by \TeX{}. This is
        encouraged when typesetting automatically generated content or
        markdown documents that were not prepared with this package in mind.

% \end{markdown}
% \iffalse

##### Lua Module Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\directlua{
  local markdown = require("markdown")
  local input, convert_safe, convert_unsafe, paragraph

  input = [[$\string\sqrt{-1}$ *equals* $i$.]]
  convert_safe = markdown.new()
  convert_unsafe = markdown.new({hybrid = true})
  paragraph = [[\par]]

  tex.sprint(
    convert_safe(input) .. paragraph ..
    convert_unsafe(input)
  )
}
\bye
```````
Then, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
```````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt {-1}\$ *equals* \$i\$.
>
> √-̅1̅ *equals* $i$.

##### Lua CLI Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts
\input optionfalse

\begingroup
\catcode`\%=12
\input optiontrue
\endgroup
\bye
```````
Using a text editor, create a text document named `content.md` with the
following content:
``` md
$\sqrt{-1}$ *equals* $i$.
``````
Next, invoke LuaTeX from the terminal:
``` sh
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
texlua ⟨CLI pathname⟩ hybrid=true -- content.md optiontrue.tex
luatex document.tex
```````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt {-1}\$ *equals* \$i\$.
>
> √-̅1̅ *equals* $i$.

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts

\markdownBegin
$\sqrt{-1}$ *equals* $i$.
\markdownEnd

\def\markdownOptionHybrid{true}
\markdownBegin
$\sqrt{-1}$ *equals* $i$.
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt {-1}\$ *equals* \$i\$.
>
> √-̅1̅ *equals* $i$.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{document}

\begin{markdown}
$\sqrt{-1}$ *equals* $i$.
\end{markdown}

\begin{markdown*}{hybrid}
$\sqrt{-1}$ *equals* $i$.
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt {-1}\$ *equals* \$i\$.
>
> √-̅1̅ *equals* $i$.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\starttext

\startmarkdown
$\sqrt{-1}$ *equals* $i$.
\stopmarkdown

\setupmarkdown[hybrid = yes]
\startmarkdown
$\sqrt{-1}$ *equals* $i$.
\stopmarkdown

\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt {-1}\$ *equals* \$i\$.
>
> √-̅1̅ *equals* $i$.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { hybrid }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.hybrid = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `inlineNotes`

`inlineNotes` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{inlineNotes}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the Pandoc inline note syntax extension:

        ``` md
        Here is an inline note.^[Inlines notes are easier to
        write, since you don't have to pick an identifier and
        move down to type the note.]
        ``````

:    false

     :  Disable the Pandoc inline note syntax extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[inlineNotes]{markdown}
\begin{document}
\begin{markdown}
Here is an inline note.^[Inlines notes are easier to
write, since you don't have to pick an identifier and
move down to type the note.]
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Here is an inline note.^[Inlines notes are easier to
> write, since you don't have to pick an identifier and
> move down to type the note.]

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[inlineNotes = yes]
\starttext
\startmarkdown
Here is an inline note.^[Inlines notes are easier to
write, since you don't have to pick an identifier and
move down to type the note.]
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Here is an inline note.^[Inlines notes are easier to
> write, since you don't have to pick an identifier and
> move down to type the note.]

%</manual-options>
%<*tex>
% \fi
% \begin{markdown}
%
% The inlineFootnotes option has been deprecated and will be removed in
% Markdown 3.0.0.
%
% \end{markdown}
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { inlineFootnotes }
  { boolean }
  { false }
\@@_add_lua_option:nnn
  { inlineNotes }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.inlineFootnotes = false
defaultOptions.inlineNotes = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `jekyllData`

`jekyllData` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{jekyllData}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the Pandoc `yaml_metadata_block` syntax extension for entering
        metadata in \acro{yaml}:

        ~~~~~~ yaml
        ---
        title:  'This is the title: it contains a colon'
        author:
        - Author One
        - Author Two
        keywords: [nothing, nothingness]
        abstract: |
          This is the abstract.

          It consists of two paragraphs.
        ---
        ~~~~~~~~~~~

:    false

     :  Disable the Pandoc `yaml_metadata_block` syntax extension for entering
        metadata in \acro{yaml}.

% \end{markdown}
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionJekyllData{true}
\ExplSyntaxOn
\keys_define:nn
  { markdown/jekyllData }
  {
    name .code:n = { \gdef\name{#1} },
    age  .code:n = { \gdef\age{#1}  },
  }
\ExplSyntaxOff
\def\markdownRendererJekyllDataEnd{%
  \name{} is \age{} years old.}
\markdownBegin
---
name: Jane Doe
age:  99
---
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Jane Doe is 99 years old.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[jekyllData]{markdown}
\markdownSetup{
  jekyllDataRenderers = {
    name = {\gdef\name{#1}},
    code = {\gdef\age{#1}},
  },
  renderers = {
    jekyllDataEnd = {\name{} is \age{} years old.},
  }
}
\begin{document}

\begin{markdown}
---
name: Jane Doe
age:  99
---
\end{markdown}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Jane Doe is 99 years old.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[jekyllData = yes]
\ExplSyntaxOn
\keys_define:nn
  { markdown/jekyllData }
  {
    name .code:n = { \gdef\name{#1} },
    age  .code:n = { \gdef\age{#1}  },
  }
\ExplSyntaxOff
\def\markdownRendererJekyllDataEnd{%
  \name{} is \age{} years old.}
\starttext

\startmarkdown
---
name: Jane Doe
age:  99
---
\stopmarkdown

\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Jane Doe is 99 years old.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { jekyllData }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.jekyllData = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `notes`

`notes` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{notes}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the Pandoc note syntax extension:

        ``` md
        Here is a note reference,[^1] and another.[^longnote]

        [^1]: Here is the note.

        [^longnote]: Here's one with multiple blocks.

            Subsequent paragraphs are indented to show that they
        belong to the previous note.

                { some.code }

            The whole paragraph can be indented, or just the
            first line.  In this way, multi-paragraph notes
            work like multi-paragraph list items.

        This paragraph won't be part of the note, because it
        isn't indented.
        ``````

:    false

     :    Disable the Pandoc note syntax extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[notes]{markdown}
\begin{document}
\begin{markdown}
Here is a note reference,[^1] and another.[^longnote]

[^1]: Here is the note.

[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous note.

        { some.code }

    The whole paragraph can be indented, or just the
    first line.  In this way, multi-paragraph notes
    work like multi-paragraph list items.

This paragraph won't be part of the note, because it
isn't indented.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Here is a note reference,[^1] and another.[^longnote]
> 
> [^1]: Here is the note.
> 
> [^longnote]: Here's one with multiple blocks.
> 
>     Subsequent paragraphs are indented to show that they
> belong to the previous note.
> 
>         { some.code }
> 
>     The whole paragraph can be indented, or just the
>     first line.  In this way, multi-paragraph notes
>     work like multi-paragraph list items.
> 
> This paragraph won't be part of the note, because it
> isn't indented.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[notes = yes]
\starttext
\startmarkdown
Here is a note reference,[^1] and another.[^longnote]

[^1]: Here is the note.

[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous note.

        { some.code }

    The whole paragraph can be indented, or just the
    first line.  In this way, multi-paragraph notes
    work like multi-paragraph list items.

This paragraph won't be part of the note, because it
isn't indented.
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Here is a note reference,[^1] and another.[^longnote]
> 
> [^1]: Here is the note.
> 
> [^longnote]: Here's one with multiple blocks.
> 
>     Subsequent paragraphs are indented to show that they
> belong to the previous note.
> 
>         { some.code }
> 
>     The whole paragraph can be indented, or just the
>     first line.  In this way, multi-paragraph notes
>     work like multi-paragraph list items.
> 
> This paragraph won't be part of the note, because it
> isn't indented.

%</manual-options>
%<*tex>
% \fi
% \begin{markdown}
%
% The footnotes option has been deprecated and will be removed in
% Markdown 3.0.0.
%
% \end{markdown}
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { footnotes }
  { boolean }
  { false }
\@@_add_lua_option:nnn
  { notes }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.footnotes = false
defaultOptions.notes = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `pipeTables` {#pipe-tables}

`pipeTables` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{pipeTables}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the \acro{PHP} Markdown pipe table syntax extension:

        ``` md
        | Right | Left | Default | Center |
        |------:|:-----|---------|:------:|
        |   12  |  12  |    12   |    12  |
        |  123  |  123 |   123   |   123  |
        |    1  |    1 |     1   |     1  |
        ``````

:    false

     :  Disable the \acro{PHP} Markdown pipe table syntax extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[pipeTables]{markdown}
\begin{document}
\begin{markdown}
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> | Right | Left | Default | Center |
> |------:|:-----|---------|:------:|
> |   12  |  12  |    12   |    12  |
> |  123  |  123 |   123   |   123  |
> |    1  |    1 |     1   |     1  |

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[pipeTables = yes]
\starttext
\startmarkdown
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> | Right | Left | Default | Center |
> |------:|:-----|---------|:------:|
> |   12  |  12  |    12   |    12  |
> |  123  |  123 |   123   |   123  |
> |    1  |    1 |     1   |     1  |

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { pipeTables }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.pipeTables = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `preserveTabs`

`preserveTabs` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{preserveTabs}{\opt{true}, \opt{false}}
%
:    true

     :  Preserve tabs in code block and fenced code blocks.

:    false

     :  Convert any tabs in the input to spaces.

% \end{markdown}
% \iffalse
%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { preserveTabs }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.preserveTabs = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `rawAttribute`

`rawAttribute` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{rawAttribute}{\opt{true}, \opt{false}}
%
:    true

     :  Enable the Pandoc raw attribute syntax extension:

        ``` md
        `$H_2 O$`{=tex} is a liquid.
        ```

        To enable raw blocks, the \Opt{fencedCode} option must also be enabled:

        ~~~~~~~~ md
        Here is a mathematical formula:
        ``` {=tex}
        \[distance[i] =
            \begin{dcases}
                a & b \\
                c & d
            \end{dcases}
        \]
        ```
        ~~~~~~~~~~~

        The \Opt{rawAttribute} option is a good alternative to the \Opt{hybrid}
        option. Unlike the \Opt{hybrid} option, which affects the entire
        document, the \Opt{rawAttribute} option allows you to isolate the parts
        of your documents that use TeX:

:    false

     :  Disable the Pandoc raw attribute syntax extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
```` tex
\documentclass{article}
\usepackage[rawAttribute, fencedCode]{markdown}
\usepackage{expl3}
\begin{document}
\begin{markdown}
`$H_2 O$`{=tex} is a liquid.

``` {=html}
<p>Here is some HTML content that will be ignored.</p>
```
\end{markdown}
\end{document}
````````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> H~2~O is a liquid.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { rawAttribute }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.rawAttribute = true
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `relativeReferences`

`relativeReferences` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{relativeReferences}{\opt{true}, \opt{false}}
%
:    true

     :  Enable [relative references][1] in autolinks:

        ``` md
        I conclude in Section <#conclusion>.

        Conclusion {#conclusion}
        ==========
        In this paper, we have discovered that most
        grandmas would rather eat dinner with their
        grandchildren than get eaten. Begone, wolf!
        ```

:    false

    :   Disable relative references in autolinks.

 [1]: https://datatracker.ietf.org/doc/html/rfc3986#section-4.2

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[headerAttributes, relativeReferences]{markdown}
\begin{document}
\begin{markdown}

I conclude in Section <#conclusion>.

Conclusion {#conclusion}
==========
In this paper, we have discovered that most
grandmas would rather eat dinner with their
grandchildren than get eaten. Begone, wolf!

\end{markdown}
\end{document}
```````
Next, invoke LuaTeX twice from the terminal:
``` sh
lualatex document.tex
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> I conclude in Section 1.
>
> # 1. Conclusion
>
> In this paper, we have discovered that most grandmas would rather eat dinner
> with their grandchildren than get eaten. Begone, wolf!

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { relativeReferences }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.relativeReferences = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `shiftHeadings`

`shiftHeadings` (default value: `0`)

% \fi
% \begin{markdown}
%
% \Valitem[0]{shiftHeadings}{shift amount}
%
:    All headings will be shifted by \meta{shift amount}, which can be both
     positive and negative. Headings will not be shifted beyond level 6 or
     below level 1. Instead, those headings will be shifted to level 6, when
     \meta{shift amount} is positive, and to level 1, when \meta{shift amount}
     is negative.

% \end{markdown}
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `example.md` with the
following content:

``` md
## A section
```

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown

\font\normal=cmr10\normal
\font\big=cmr10 at 12pt
\def\markdownRendererHeadingTwo#1{{\big #1\par}}
\font\bigger=cmr10 scaled 1440
\def\markdownRendererHeadingOne#1{{\bigger #1\par}}

\def\markdownOptionShiftHeadings{-1}
\markdownInput{example.md}

\def\markdownOptionShiftHeadings{0}
\markdownInput{example.md}

\def\markdownOptionShiftHeadings{+1}
\markdownInput{example.md}

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> # A section
> ## A section
> ### A section

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{filecontents}[overwrite,nosearch,noheader]{example.md}
## A section
\end{filecontents}
\begin{document}
\markdownInput[shiftHeadings=-1]{example.md}
\markdownInput{example.md}
\markdownInput[shiftHeadings=+1]{example.md}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> # A section
> ## A section
> ### A section

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `example.md` with the
following content:

``` md
## A section
```

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\starttext

\inputmarkdown[shiftHeadings = -1]{example.md}
\inputmarkdown[shiftHeadings =  0]{example.md}
\inputmarkdown[shiftHeadings = +1]{example.md}

\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> # A section
> ## A section
> ### A section

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { shiftHeadings }
  { number }
  { 0 }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.shiftHeadings = 0
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `slice`

`slice` (default value: `^ $`)

% \fi
% \begin{markdown}
%
% \Valitem[\textasciicircum{} \\$]{slice}{the beginning and the end of a slice}
%
:    Two space-separated selectors that specify the slice of a document that
     will be processed, whereas the remainder of the document will be ignored.
     The following selectors are recognized:

     - The circumflex (`^`) selects the beginning of a document.
     - The dollar sign (`$`) selects the end of a document.
     - `^`\meta{identifier} selects the beginning of a section with the
%      \acro{HTML} attribute `#`\meta{identifier} (see the
%      \Opt{headerAttributes} option).
%      \iffalse
       [\acro{HTML} attribute](#header-attributes) `#`\meta{identifier}.
%      \fi
     - `$`\meta{identifier} selects the end of a section with the \acro{HTML}
       attribute `#`\meta{identifier}.
     - \meta{identifier} corresponds to `^`\meta{identifier} for the first
       selector and to `$`\meta{identifier} for the second selector.

     Specifying only a single selector, \meta{identifier}, is equivalent
     to specifying the two selectors \meta{identifier} \meta{identifier},
     which is equivalent to `^`\meta{identifier} `$`\meta{identifier}, i.e.
     the entire section with the \acro{HTML} attribute `#`\meta{identifier} will be
     selected.

% \end{markdown}
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `hamlet.md` with the
following content:

``` md
# The Tragedy of Hamlet
Shakespeare's longest play.

## Act III {#act-3}
Hamlet kills Polonius.

## Act V   {#act-5}
Hamlet dies.

## Act I   {#act-1}
Hamlet talks to ghost.
```

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionHeaderAttributes{true}

\font\normal=cmr10\normal
\font\big=cmr10 at 12pt
\def\markdownRendererHeadingTwo#1{{\big #1\par}}
\font\bigger=cmr10 scaled 1440
\def\markdownRendererHeadingOne#1{{\bigger #1\par}}

\def\markdownOptionSlice{^ ^act-3}
\markdownInput{hamlet.md}

\def\markdownOptionSlice{act-1}
\markdownInput{hamlet.md}

\def\markdownOptionSlice{act-3 act-5}
\markdownInput{hamlet.md}

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> # The Tragedy of Hamlet
> Shakespeare's longest play.
>
> ## Act I
> Hamlet talks to ghost.
>
> ## Act III
> Hamlet kills Polonius.
>
> ## Act V
> Hamlet dies.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[headerAttributes]{markdown}
\begin{filecontents}[overwrite,nosearch,noheader]{hamlet.md}
# The Tragedy of Hamlet
Shakespeare's longest play.

## Act III {#act-3}
Hamlet kills Polonius.

## Act V   {#act-5}
Hamlet dies.

## Act I   {#act-1}
Hamlet talks to ghost.
\end{filecontents}
\begin{document}
\markdownInput[slice=^ ^act-3]{hamlet.md}
\markdownInput[slice=act-1]{hamlet.md}
\markdownInput[slice=act-3 act-5]{hamlet.md}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> # The Tragedy of Hamlet
> Shakespeare's longest play.
>
> ## Act I
> Hamlet talks to ghost.
>
> ## Act III
> Hamlet kills Polonius.
>
> ## Act V
> Hamlet dies.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `hamlet.md` with the
following content:

``` md
# The Tragedy of Hamlet
Shakespeare's longest play.

## Act III {#act-3}
Hamlet kills Polonius.

## Act V   {#act-5}
Hamlet dies.

## Act I   {#act-1}
Hamlet talks to ghost.
```

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[headerAttributes = yes]
\starttext

\inputmarkdown[slice = ^ ^act-3]{example.md}
\inputmarkdown[slice = act-1]{example.md}
\inputmarkdown[slice = act-3 act-5]{example.md}

\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> # The Tragedy of Hamlet
> Shakespeare's longest play.
>
> ## Act I
> Hamlet talks to ghost.
>
> ## Act III
> Hamlet kills Polonius.
>
> ## Act V
> Hamlet dies.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { slice }
  { slice }
  { ^~$ }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.slice = "^ $"
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `smartEllipses`

`smartEllipses` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{smartEllipses}{\opt{true}, \opt{false}}
%
:    true

     :   Convert any ellipses in the input to the
         \mref{markdownRendererEllipsis} \TeX{} macro.

:    false

     :  Preserve all ellipses in the input.

% \end{markdown}
% \iffalse

##### Lua Module Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownRendererEllipsis{. . .}
\input lmfonts
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new()
  local input = "These are just three regular dots ..."
  tex.sprint(convert(input)) }
\par
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new({smartEllipses = true})
  local input = "... and this is a victorian ellipsis."
  tex.sprint(convert(input)) }
\bye
```````
Then, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
```````
A PDF document named `document.pdf` should be produced and contain the
following text:

> These are just three regular dots ...
>
> . . . and this is a victorian ellipsis.

##### Lua CLI Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownRendererEllipsis{. . .}
\input lmfonts
\input optionfalse
\par
\input optiontrue
\bye
```````
Using a text editor, create a text document named `content.md` with the
following content:
``` md
Are these just three regular dots, a victorian ellipsis, or ... ?
``````
Next, invoke LuaTeX from the terminal:
``` sh
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
texlua ⟨CLI pathname⟩ smartEllipses=true -- content.md optiontrue.tex
luatex document.tex
```````
where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or
`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows
systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI
script file using [Kpathsea][].

A PDF document named `document.pdf` should be produced and contain the
following text:

> Are these just three regular dots, a victorian ellipsis, or ... ?
>
> Are these just three regular dots, a victorian ellipsis, or . . . ?

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownRendererEllipsis{. . .}

\markdownBegin
These are just three regular dots ...
\markdownEnd

\def\markdownOptionSmartEllipses{true}
\markdownBegin
... and this is a victorian ellipsis.
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> These are just three regular dots ...
>
> . . . and this is a victorian ellipsis.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\markdownSetup{
  renderers = {
    ellipsis = {. . .}
  }
}
\begin{document}

\begin{markdown}
These are just three regular dots ...
\end{markdown}

\begin{markdown*}{smartEllipses}
... and this is a victorian ellipsis.
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> These are just three regular dots ...
>
> . . . and this is a victorian ellipsis.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\def\markdownRendererEllipsis{. . .}
\starttext

\startmarkdown
These are just three regular dots ...
\stopmarkdown

\setupmarkdown[smartEllipses = yes]
\startmarkdown
... and this is a victorian ellipsis.
\stopmarkdown

\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> These are just three regular dots ...
>
> . . . and this is a victorian ellipsis.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { smartEllipses }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.smartEllipses = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `startNumber`

`startNumber` (default value: `true`)

% \fi
% \begin{markdown}
%
% \Optitem[true]{startNumber}{\opt{true}, \opt{false}}
%
:    true

     :   Make the number in the first item of an ordered lists significant. The
         item numbers will be passed to the
         \mref{markdownRendererOlItemWithNumber} \TeX{} macro.

:    false

     :   Ignore the numbers in the ordered list items. Each item will only
         produce a \mref{markdownRendererOlItem} \TeX{} macro.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{document}

\begin{markdown}
The following list respects the numbers specified in the markup:

3. third item
4. fourth item
5. fifth item
\end{markdown}

\begin{markdown*}{startNumber=false}
The following list does not respect the numbers specified in the
markup:

3. third item
4. fourth item
5. fifth item
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> The following list respects the numbers specified in the markup:
> 
> 3. third item
> 4. fourth item
> 5. fifth item
>
> The following list does not respect the numbers specified in the markup:
> 
> 1. third item
> 2. fourth item
> 3. fifth item

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\starttext

\startmarkdown
The following list respects the numbers specified in the markup:

3. third item
4. fourth item
5. fifth item
\stopmarkdown

\setupmarkdown[startNumber = no]
\startmarkdown
The following list respects the numbers specified in the markup:

3. third item
4. fourth item
5. fifth item
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> The following list respects the numbers specified in the markup:
> 
> 3. third item
> 4. fourth item
> 5. fifth item
>
> The following list does not respect the numbers specified in the markup:
> 
> 1. third item
> 2. fourth item
> 3. fifth item

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { startNumber }
  { boolean }
  { true }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.startNumber = true
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `strikeThrough`

`strikeThrough` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{strikeThrough}{\opt{true}, \opt{false}}
%
:    true

     :   Enable the Pandoc strike-through syntax extension:

         ``` md
         This ~~is deleted text.~~
         ``````

:    false

     :   Disable the Pandoc strike-through syntax extension.

% \end{markdown}
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionStrikeThrough{true}
\input soulutf8.sty
\def\markdownRendererStrikeThrough#1{\st{#1}}
\markdownBegin
This is ~~a lunar roving vehicle~~ strike-through text.
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is ~~a lunar roving vehicle~~ strike-through text.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[strikeThrough]{markdown}
\usepackage{soulutf8}
\markdownSetup{
  renderers = {
    strikeThrough = {\st{#1}},
  },
}
\begin{document}
\begin{markdown}
This is ~~a lunar roving vehicle~~ strike-through text.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is ~~a lunar roving vehicle~~ strike-through text.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[strikeThrough = yes]
\def\markdownRendererStrikeThrough#1{\overstrikes{#1}}
\starttext
\startmarkdown
This is ~~a lunar roving vehicle~~ strike-through text.
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is ~~a lunar roving vehicle~~ strike-through text.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { strikeThrough }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.strikeThrough = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `stripIndent`

`stripIndent` (default value: `false`)

% \fi
% \markdownBegin
%
% \Optitem[false]{stripIndent}{\opt{true}, \opt{false}}
%
:    true

     :   Strip the minimal indentation of non-blank lines from all
         lines in a markdown document. Requires that the
         \Opt{preserveTabs} Lua option is disabled:

         ``` tex
         \documentclass{article}
         \usepackage[stripIndent]{markdown}
         \begin{document}
             \begin{markdown}
                 Hello *world*!
             \end{markdown}
         \end{document}
         ```````

:    false

     :   Do not strip any indentation from the lines in a markdown
         document.

% \markdownEnd
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionStripIndent{true}
\markdownBegin
    Hello *world*!
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!”

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[stripIndent]{markdown}
\begin{document}
    \begin{markdown}
        Hello *world*!
    \end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
text “Hello *world*!”

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[stripIndent = yes]
\starttext
    \startmarkdown
        Hello *world*!
    \stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
text “Hello *world*!”

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { stripIndent }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.stripIndent = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `subscripts`

`subscripts` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{subscripts}{\opt{true}, \opt{false}}
%
:    true

     :   Enable the Pandoc subscript syntax extension:

         ``` md
         H~2~O is a liquid.
         ``````

:    false

     :   Disable the Pandoc subscript syntax extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[subscripts]{markdown}
\begin{document}
\begin{markdown}
H~2~O is a liquid.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> H~2~O is a liquid.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[subscripts = yes]
\starttext
\startmarkdown
H~2~O is a liquid.
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> H~2~O is a liquid.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { subscripts }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.subscripts = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `superscripts`

`superscripts` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{superscripts}{\opt{true}, \opt{false}}
%
:    true

     :   Enable the Pandoc superscript syntax extension:

         ``` md
         2^10^ is 1024.
         ``````

:    false

     :   Disable the Pandoc superscript syntax extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[superscripts]{markdown}
\begin{document}
\begin{markdown}
2^10^ is 1024.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> 2^10^ is 1024.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[superscripts = yes]
\starttext
\startmarkdown
2^10^ is 1024.
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> 2^10^ is 1024.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { superscripts }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.superscripts = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `tableCaptions`

`tableCaptions` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{tableCaptions}{\opt{true}, \opt{false}}
%
:    true

     :   Enable the Pandoc `table_captions` syntax extension for
%        pipe tables (see the \Opt{pipeTables} option).
%        \iffalse
         [pipe tables](#pipe-tables).
%        \fi

        ``` md
        | Right | Left | Default | Center |
        |------:|:-----|---------|:------:|
        |   12  |  12  |    12   |    12  |
        |  123  |  123 |   123   |   123  |
        |    1  |    1 |     1   |     1  |

          : Demonstration of pipe table syntax.
        ``````

:    false

     :  Disable the Pandoc `table_captions` syntax extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[pipeTables, tableCaptions]{markdown}
\begin{document}
\begin{markdown}
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

: Demonstration of pipe table syntax.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> | Right | Left | Default | Center |
> |------:|:-----|---------|:------:|
> |   12  |  12  |    12   |    12  |
> |  123  |  123 |   123   |   123  |
> |    1  |    1 |     1   |     1  |
> 
> : Demonstration of pipe table syntax.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown
  [
    pipeTables = yes,
    tableCaptions = yes,
  ]
\starttext
\startmarkdown
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

: Demonstration of pipe table syntax.
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> | Right | Left | Default | Center |
> |------:|:-----|---------|:------:|
> |   12  |  12  |    12   |    12  |
> |  123  |  123 |   123   |   123  |
> |    1  |    1 |     1   |     1  |
> 
> : Demonstration of pipe table syntax.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { tableCaptions }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.tableCaptions = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `taskLists`

`taskLists` (default value: `false`)

% \fi
% \begin{markdown}
%
% \Optitem[false]{taskLists}{\opt{true}, \opt{false}}
%
:    true

     :   Enable the Pandoc `task_lists` syntax extension.
       

        ``` md
        - [ ] an unticked task list item
        - [/] a half-checked task list item
        - [X] a ticked task list item
        ``````

:    false

     :  Disable the Pandoc `task_lists` syntax extension.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[taskLists]{markdown}
\markdownSetup{
  renderers = {
    untickedBox = No,
    halfTickedBox = Maybe,
    tickedBox = Yes,
  },
}
\begin{document}
\begin{markdown}
- [ ] you can't.
- [/] I can?
- [X] I can!
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> - No you can't.
> - Maybe I can?
> - Yes I can!

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[taskLists = yes]
\def\markdownRendererUntickedBox{No}
\def\markdownRendererHalftickedBox{Maybe}
\def\markdownRendererTickedBox{Yes}
\starttext
\startmarkdown
- [ ] you can't.
- [/] I can?
- [X] I can!
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> - No you can't.
> - Maybe I can?
> - Yes I can!

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { taskLists }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.taskLists = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `texComments`

`texComments` (default value: `false`)

% \fi
% \markdownBegin
%
% \Optitem[false]{texComments}{\opt{true}, \opt{false}}
%
:    true

     :   Strip \TeX{}-style comments.

         ``` tex
         \documentclass{article}
         \usepackage[texComments]{markdown}
         \begin{document}
         \begin{markdown}
         Hel%  this is a comment
            lo *world*!
         \end{markdown}
         \end{document}
         ```````

         Always enabled when \Opt{hybrid} is enabled.

:    false

     :   Do not strip \TeX{}-style comments.

% \markdownEnd
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionTexComments{true}
\markdownBegin
Hel%  this is a comment
   lo *world*!
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!”

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[texComments]{markdown}
\begin{document}
\begin{markdown}
Hel%  this is a comment
   lo *world*!
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
text “Hello *world*!”

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[texComments = yes]
\starttext
\startmarkdown
Hel%  this is a comment
   lo *world*!
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
text “Hello *world*!”

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { texComments }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.texComments = false
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>


#### Option `tightLists`

`tightLists` (default value: `true`)

% \fi
% \begin{markdown}
%
% \Optitem[true]{tightLists}{\opt{true}, \opt{false}}
%
:    true

     :   Unordered and ordered lists whose items do not consist of multiple
         paragraphs will be considered *tight*. Tight lists will produce tight
         renderers that may produce different output than lists that are not
         tight:

         ``` md
         - This is
         - a tight
         - unordered list.

         - This is

           not a tight

         - unordered list.
         ```

:    false

     :   Unordered and ordered lists whose items consist of multiple paragraphs
         will be treated the same way as lists that consist of multiple paragraphs.

% \end{markdown}
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{document}

\begin{markdown}
The following list is tight:

- first item
- second item
- third item

The following list is loose:

- first item
- second item that spans

  multiple paragraphs
- third item
\end{markdown}

\begin{markdown*}{tightLists=false}
The following list is now also loose:

- first item
- second item
- third item
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> The following list is tight:
> 
> - first item
> - second item
> - third item
> 
> The following list is loose:
> 
> - first item
> - second item that spans
> 
>   multiple paragraphs
> - third item
> 
> The following list is now also loose:
> 
> - first item
>
> - second item
>
> - third item

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { tightLists }
  { boolean }
  { true }
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.tightLists = true
%    \end{macrocode}
% \par
% \iffalse
%</lua,lua-cli>
%<*manual-options>

#### Option `underscores`

`underscores` (default value: `true`)

% \fi
% \begin{markdown}
%
% \Optitem[true]{underscores}{\opt{true}, \opt{false}}
%
:    true

     :  Both underscores and asterisks can be used to denote emphasis and
        strong emphasis:

        ``` md
        *single asterisks*
        _single underscores_
        **double asterisks**
        __double underscores__
        ``````

:    false

     :  Only asterisks can be used to denote emphasis and strong emphasis.
        This makes it easy to write math with the \Opt{hybrid} option
        without the need to constantly escape subscripts.

% \end{markdown}
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionHybrid{true}

\markdownBegin
This is _emphasized text_ and this is a math subscript: $m\_n$.
\markdownEnd

\def\markdownOptionUnderscores{false}
\markdownBegin
This is *emphasized text* and this is a math subscript: $m_n$.
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is _emphasized text_ and this is a math subscript: *mₙ*.
>
> This is _emphasized text_ and this is a math subscript: *mₙ*.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[hybrid]{markdown}
\begin{document}

\begin{markdown}
This is _emphasized text_ and this is a math subscript: $m\_n$.
\end{markdown}

\begin{markdown*}{underscores=false}
This is *emphasized text* and this is a math subscript: $m_n$.
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is _emphasized text_ and this is a math subscript: *mₙ*.
>
> This is _emphasized text_ and this is a math subscript: *mₙ*.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[hybrid = yes]
\starttext

\startmarkdown
This is _emphasized text_ and this is a math subscript: $m\_n$.
\stopmarkdown

\setupmarkdown[underscores = yes]
\startmarkdown
This is *emphasized text* and this is a math subscript: $m_n$.
\stopmarkdown

\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is _emphasized text_ and this is a math subscript: *mₙ*.
>
> This is _emphasized text_ and this is a math subscript: *mₙ*.

%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_lua_option:nnn
  { underscores }
  { boolean }
  { true }
\ExplSyntaxOff
%    \end{macrocode}
% \iffalse
%</tex>
%<*lua,lua-cli>
% \fi
%  \begin{macrocode}
defaultOptions.underscores = true
%    \end{macrocode}
% \endgroup
% \iffalse
%</lua,lua-cli>
%<*lua-cli>
% \fi
% \par
% \begin{markdown}
%
%### Command-Line Interface {#lua-cli-interface}
%
% The high-level operation of the Markdown package involves the communication
% between several programming layers: the plain \TeX{} layer hands markdown
% documents to the Lua layer. Lua converts the documents to \TeX{}, and hands
% the converted documents back to plain \TeX{} layer for typesetting, see
% Figure <#fig:sequence-diagram-tex-interface>.
%
% This procedure has the advantage of being fully automated. However, it also
% has several important disadvantages: The converted \TeX{} documents are
% cached on the file system, taking up increasing amount of space. Unless the
% \TeX{} engine includes a Lua interpreter, the package also requires shell
% access, which opens the door for a malicious actor to access the system.
% Last, but not least, the complexity of the procedure impedes debugging.
%
% A solution to the above problems is to decouple the conversion from the
% typesetting. For this reason, a command-line Lua interface for converting a
% markdown document to \TeX{} is also provided, see
% Figure <#fig:sequence-diagram-lua-cli>.
%
% \end{markdown}
% \begin{figure}
% \centering
% \begin{sequencediagram}
%   \newthread{user}{User}{}
%   \newinst[4]{tex}{\TeX{}}{}
%   \newinst[4]{lua}{Lua}{}
%   \begin{call}{user}{\footnotesize\cs{jobname.tex}}{tex}{\footnotesize\cs{jobname.pdf}}
%   \begin{call}{tex}{\footnotesize\cs{jobname.markdown.in}}{lua}{\footnotesize\cs{jobname.markdown.out}}
%   \end{call}
%   \begin{call}{tex}{\footnotesize\cs{input}\cs{jobname.markdown.out}}{tex}{}
%   \end{call}
%   \end{call}
% \end{sequencediagram}
% \caption[A sequence diagram of typesetting a document using the \TeX{}
%   interface]{A sequence diagram of the Markdown package typesetting a
%   markdown document using the \TeX{} interface}
% \label{fig:sequence-diagram-tex-interface}
% \end{figure}
% \begin{figure}
% \centering
% \begin{sequencediagram}
%   \newthread{user}{User}{}
%   \newinst[4]{tex}{\TeX{}}{}
%   \newinst[4]{lua}{Lua}{}
%   \begin{call}{user}{\footnotesize$\langle$\textit{document}$\rangle$\texttt{.md}}{lua}{\footnotesize$\langle$\textit{document}$\rangle$\texttt{.tex}}
%   \end{call}
%   \begin{call}{user}{\footnotesize\cs{jobname.tex}}{tex}{\footnotesize\cs{jobname.pdf}}
%   \begin{call}{tex}{\footnotesize\cs{input} $\langle$\textit{document}$\rangle$}{tex}{}
%   \end{call}
%   \end{call}
% \end{sequencediagram}
% \caption[A sequence diagram of typesetting a document using the Lua CLI]%
%   {A sequence diagram of the Markdown package typesetting a markdown document
%   using the Lua command-line interface}
% \label{fig:sequence-diagram-lua-cli}
% \end{figure}
%  \begin{macrocode}

local HELP_STRING = [[
Usage: texlua ]] .. arg[0] .. [[ [OPTIONS] -- [INPUT_FILE] [OUTPUT_FILE]
where OPTIONS are documented in the Lua interface section of the
technical Markdown package documentation.

When OUTPUT_FILE is unspecified, the result of the conversion will be
written to the standard output. When INPUT_FILE is also unspecified, the
result of the conversion will be read from the standard input.

Report bugs to: witiko@mail.muni.cz
Markdown package home page: <https://github.com/witiko/markdown>]]

local VERSION_STRING = [[
markdown-cli.lua (Markdown) ]] .. metadata.version .. [[

Copyright (C) ]] .. table.concat(metadata.copyright,
                                 "\nCopyright (C) ") .. [[

License: ]] .. metadata.license

local function warn(s)
  io.stderr:write("Warning: " .. s .. "\n") end

local function error(s)
  io.stderr:write("Error: " .. s .. "\n")
  os.exit(1)
end
%    \end{macrocode}
% \begin{markdown}
%
% To make it easier to copy-and-paste options from Pandoc [@macfarlane22] such
% as `fancy_lists`, `header_attributes`, and `pipe_tables`, we accept
% snake\\\_case in addition to camelCase variants of options. As a bonus,
% studies [@sharif10] also show that snake\\\_case is faster to read than
% camelCase.
%
% \end{markdown}
%  \begin{macrocode}
local function camel_case(option_name)
  local cased_option_name = option_name:gsub("_(%l)", function(match)
    return match:sub(2, 2):upper()
  end)
  return cased_option_name
end

local function snake_case(option_name)
  local cased_option_name = option_name:gsub("%l%u", function(match)
    return match:sub(1, 1) .. "_" .. match:sub(2, 2):lower()
  end)
  return cased_option_name
end

local cases = {camel_case, snake_case}
local various_case_options = {}
for option_name, _ in pairs(defaultOptions) do
  for _, case in ipairs(cases) do
    various_case_options[case(option_name)] = option_name
  end
end

local process_options = true
local options = {}
local input_filename
local output_filename
for i = 1, #arg do
  if process_options then
%    \end{macrocode}
% \begin{markdown}
% After the optional `-`{}`-` argument has been specified, the remaining
% arguments are assumed to be input and output filenames. This argument is
% optional, but encouraged, because it helps resolve ambiguities when
% deciding whether an option or a filename has been specified.
% \end{markdown}
%  \begin{macrocode}
    if arg[i] == "--" then
      process_options = false
      goto continue
%    \end{macrocode}
% \begin{markdown}
% Unless the `-`{}`-` argument has been specified before, an argument
% containing the equals sign (`=`) is assumed to be an option specification in
% a \meta{key}`=`\meta{value} format. The available options are listed in
% Section <#sec:luaoptions>.
% \end{markdown}
%  \begin{macrocode}
    elseif arg[i]:match("=") then
      local key, value = arg[i]:match("(.-)=(.*)")
      if defaultOptions[key] == nil then
        key = various_case_options[key]
      end
%    \end{macrocode}
% \begin{markdown}
% The \luamref{defaultOptions} table is consulted to identify whether \meta{value}
% should be parsed as a string, number, table, or boolean.
% \end{markdown}
%  \begin{macrocode}
      local default_type = type(defaultOptions[key])
      if default_type == "boolean" then
        options[key] = (value == "true")
      elseif default_type == "number" then
        options[key] = tonumber(value)
      elseif default_type == "table" then
        options[key] = {}
        for item in value:gmatch("[^ ,]+") do
          table.insert(options[key], item)
        end
      else
        if default_type ~= "string" then
          if default_type == "nil" then
            warn('Option "' .. key .. '" not recognized.')
          else
            warn('Option "' .. key .. '" type not recognized, please file ' ..
                 'a report to the package maintainer.')
          end
          warn('Parsing the ' .. 'value "' .. value ..'" of option "' ..
               key .. '" as a string.')
        end
        options[key] = value
      end
      goto continue
%    \end{macrocode}
% \begin{markdown}
% Unless the `-`{}`-` argument has been specified before, an argument
% `-`{}`-help`, or `-h` causes a brief documentation for how to invoke the
% program to be printed to the standard output.
% \end{markdown}
%  \begin{macrocode}
    elseif arg[i] == "--help" or arg[i] == "-h" then
      print(HELP_STRING)
      os.exit()
%    \end{macrocode}
% \begin{markdown}
% Unless the `-`{}`-` argument has been specified before, an argument
% `-`{}`-version`, or `-v` causes the program to print information about its
% name, version, origin and legal status, all on standard output.
% \end{markdown}
%  \begin{macrocode}
    elseif arg[i] == "--version" or arg[i] == "-v" then
      print(VERSION_STRING)
      os.exit()
    end
  end
%    \end{macrocode}
% \begin{markdown}
% The first argument that matches none of the above patters is assumed to be
% the input filename. The input filename should correspond to the Markdown
% document that is going to be converted to a \TeX{} document.
% \end{markdown}
%  \begin{macrocode}
  if input_filename == nil then
    input_filename = arg[i]
%    \end{macrocode}
% \begin{markdown}
% The first argument that matches none of the above patters is assumed to be
% the output filename. The output filename should correspond to the \TeX{}
% document that will result from the conversion.
% \end{markdown}
%  \begin{macrocode}
  elseif output_filename == nil then
    output_filename = arg[i]
  else
    error('Unexpected argument: "' .. arg[i] .. '".')
  end
  ::continue::
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The command-line Lua interface is implemented by the `markdown-cli.lua`
% file that can be invoked from the command line as follows:
% ``` sh
% texlua /path/to/markdown-cli.lua cacheDir=. -- hello.md hello.tex
% ``````
% \noindent to convert the Markdown document `hello.md` to a \TeX{} document
% `hello.tex`.  After the Markdown package for our \TeX{} format has been
% loaded, the converted document can be typeset as follows:
% ``` tex
% \input hello
% ```````
%
% \end{markdown}
% \iffalse
%</lua-cli>
%<*tex>
% \fi
% \par
% \begin{markdown}
%
% Plain \TeX{} Interface {#texinterface}
%------------------------
%
% \iffalse
%</tex>
%<*manual-interfaces>

### Plain \TeX{}

The plain \TeX{} interface provides \TeX{} commands that typeset markdown
documents by using the Lua interface behind the scenes. Unlike the Lua
interface, the plain TeX interface does not provide low-level tools for
converting markdown to \TeX{}. Instead, its goal is to provide high-level
typesetting capabilities.

The plain \TeX{} interface accepts the same options as the `markdown` Lua
module, in addition to its own options, but now the options are specified as
\TeX{} commands.

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts

\markdownBegin
$\sqrt{-1}$ *equals* $i$.
\markdownEnd

\def\markdownOptionHybrid{true}
\markdownBegin
$\sqrt{-1}$ *equals* $i$.
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt{-1}\$ *equals* \$i\$.
> 
> √-̅1̅ *equals* $i$.
  
Invoking pdfTeX should have the same effect:
``` sh
pdftex --shell-escape document.tex
``````

%</manual-interfaces>
%<*tex>
% \fi
%
% The plain \TeX{} interface provides macros for the typesetting of markdown
% input from within plain \TeX{}, for setting the Lua interface options (see
% Section <#sec:luaoptions>) used during the conversion from markdown to
% plain \TeX{} and for changing the way markdown the tokens are rendered.
%
% \end{markdown}
%  \begin{macrocode}
\def\markdownLastModified{(((LASTMODIFIED)))}%
\def\markdownVersion{(((VERSION)))}%
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The plain \TeX{} interface is implemented by the `markdown.tex` file that can
% be loaded as follows:
% ``` tex
% \input markdown
% ```````
% \noindent It is expected that the special plain \TeX{} characters have the
% expected category codes, when `\input`ting the file.
%
%### Typesetting Markdown {#textypesetting}
%
% The interface exposes the \mdef{markdownBegin}, \mdef{markdownEnd},
% \mdef{markdownInput}, and \mdef{markdownEscape} macros.
%
% The \mref{markdownBegin} macro marks the beginning of a markdown document
% fragment and the \mref{markdownEnd} macro marks its end.
%
% \end{markdown}
%  \begin{macrocode}
\let\markdownBegin\relax
\let\markdownEnd\relax
%    \end{macrocode}
% \par
% \begin{markdown}
%
% You may prepend your own code to the \mref{markdownBegin} macro and redefine the
% \mref{markdownEnd} macro to produce special effects before and after the
% markdown block.
%
% There are several limitations to the macros you need to be aware of.
% The first limitation concerns the \mref{markdownEnd} macro, which must be
% visible directly from the input line buffer (it may not be produced as a
% result of input expansion). Otherwise, it will not be recognized as the end
% of the markdown string. As a corrolary, the \mref{markdownEnd} string
% may not appear anywhere inside the markdown input.
%
% Another limitation concerns spaces at the right end of an input line. In
% markdown, these are used to produce a forced line break. However, any such
% spaces are removed before the lines enter the input buffer of
% \TeX{}~[@knuth86a, p. 46]. As a corrolary, the \mref{markdownBegin} macro also
% ignores them.
%
% The \mref{markdownBegin} and \mref{markdownEnd} macros will also consume the rest
% of the lines at which they appear.  In the following example plain \TeX{}
% code, the characters `c`, `e`, and `f` will not appear in the output.
%
% ``` tex
% \input markdown
% a
% b \markdownBegin c 
% d 
% e \markdownEnd   f
% g 
% \bye
% ```````
%
% Note that you may also not nest the \mref{markdownBegin} and \mref{markdownEnd}
% macros.
%
% The following example plain \TeX{} code showcases the usage of the
% \mref{markdownBegin} and \mref{markdownEnd} macros:
%
% ``` tex
% \input markdown
% \markdownBegin
% _Hello_ **world** ...
% \markdownEnd
% \bye
% ```````
%
% The \mref{markdownInput} macro accepts a single parameter with the filename
% of a markdown document and expands to the result of the conversion of the
% input markdown document to plain \TeX{}.
%
% \end{markdown}
%  \begin{macrocode}
\let\markdownInput\relax
%    \end{macrocode}
% \par
% \begin{markdown}
%
% This macro is not subject to the abovelisted limitations of the
% \mref{markdownBegin} and \mref{markdownEnd} macros.
%
% The following example plain \TeX{} code showcases the usage of the
% \mref{markdownInput} macro:
%
% ``` tex
% \input markdown
% \markdownInput{hello.md}
% \bye
% ```````
%
% The \mref{markdownEscape} macro accepts a single parameter with the filename
% of a \TeX{} document and executes the \TeX{} document in the middle of a
% markdown document fragment. Unlike the `\input` built-in of \TeX,
% \mref{markdownEscape} guarantees that the standard catcode regime of your
% \TeX{} format will be used.
%
% \end{markdown}
%  \begin{macrocode}
\let\markdownEscape\relax
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Options {#texoptions}
%
% The plain \TeX{} options are represented by \TeX{} commands. Some of them map
% directly to the options recognized by the Lua interface (see
% Section <#sec:luaoptions>), while some of them are specific to the plain
% \TeX{} interface.
%
% To enable the enumeration of plain \TeX{} options, we will maintain the
% \mdef{g_\@\@_plain_tex_options_seq} sequence.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\seq_new:N \g_@@_plain_tex_options_seq
%    \end{macrocode}
% \begin{markdown}
%
% To enable the reflection of default plain \TeX{} options and their types, we
% will maintain the \mdef{g_\@\@_default_plain_tex_options_prop} and
% \mdef{g_\@\@_plain_tex_option_types_prop} property lists, respectively.
%
% \end{markdown}
%  \begin{macrocode}
\prop_new:N \g_@@_plain_tex_option_types_prop
\prop_new:N \g_@@_default_plain_tex_options_prop
\tl_const:Nn \c_@@_option_layer_plain_tex_tl { plain_tex }
\seq_gput_right:NV \g_@@_option_layers_seq \c_@@_option_layer_plain_tex_tl
\cs_new:Nn
  \@@_add_plain_tex_option:nnn
  {
    \@@_add_option:Vnnn
      \c_@@_option_layer_plain_tex_tl
      { #1 }
      { #2 }
      { #3 }
  }
%    \end{macrocode}
% \iffalse
%</tex>
%<*manual-options>

### Plain \TeX{}

Plain \TeX{} options control the communication between the \TeX{} interface and
the `markdown` Lua module. They are supported by all higher-level interfaces of
the Markdown package, i.e. the plain \TeX{}, \LaTeX{} and \Hologo{ConTeXt}
interfaces.

#### Setting Lua options from plain \TeX{}

As a rule of thumb, you can set all Lua options directly from plain \TeX{}. For
example, to set the \Opt{taskLists} Lua option to `true`, you would include the
following code in your plain \TeX{} document:

``` tex
\def\markdownOptionTaskLists{true}
```

%</manual-options>
%<*tex>
% \fi
% \par
% \begin{markdown}
%
%#### Finalizing and Freezing the Cache
% The \mdef{markdownOptionFinalizeCache} option corresponds to the Lua
% interface \Opt{finalizeCache} option, which creates an output file
% \Opt{frozenCacheFileName} (frozen cache) that contains a mapping
% between an enumeration of the markdown documents in the plain \TeX{} document
% and their auxiliary files cached in the \Opt{cacheDir} directory.
%
% \iffalse
%</tex>
%<*manual-options>

#### Finalizing and Freezing the Cache

% \fi
%
The \mdef{markdownOptionFrozenCache} option uses the mapping previously
% created by the \Opt{finalizeCache} option,
% \iffalse
created by the Lua interface \Opt{finalizeCache} option,
% \fi
and uses it to typeset the plain \TeX{} document without invoking Lua. As a
result, the plain \TeX{} document becomes more portable, but further changes
in the order and the content of markdown documents will not be reflected. It
defaults to `false`.

% \end{markdown}
% \iffalse
%</manual-options>
%<*tex>
% \fi
%  \begin{macrocode}
\@@_add_plain_tex_option:nnn
  { frozenCache }
  { boolean }
  { false }
%    \end{macrocode}
% \iffalse
%</tex>
%<*manual-options>
% \fi
% \begin{markdown}
%
% The standard usage of the above two options is as follows:
% \iffalse
The standard usage of the \Opt{finalizeCache} and \Opt{frozenCache}
options is as follows:
% \fi

1. Remove the \Opt{cacheDir} cache directory with stale auxiliary cache
   files.
% 2. Enable the \Opt{finalizeCache} option.
% \iffalse
2. Enable the \Opt{finalizeCache} option.
% \fi
3. Typeset the plain \TeX{} document to populate and finalize the cache.
4. Enable the \Opt{frozenCache} option.
5. Publish the source code of the plain \TeX{} document and the
   \Opt{cacheDir} directory.

% \iffalse
For more information, see the examples for the \Opt{finalizeCache} option.
% \fi

#### File and Directory Names

% \end{markdown}
% \iffalse
%</manual-options>
%<*tex>
% \fi
% \begin{markdown}
%
% The \mdef{markdownOptionHelperScriptFileName} macro sets the filename of the
% helper Lua script file that is created during the conversion from markdown to
% plain \TeX{} in \TeX{} engines without the `\directlua` primitive. It
% defaults to `\jobname.markdown.lua`, where `\jobname` is the base name
% of the document being typeset.
%
% The expansion of this macro must not contain quotation marks (`"`) or
% backslash symbols (`\`). Mind that \TeX{} engines tend to
% put quotation marks around `\jobname`, when it contains spaces.
%
% \end{markdown}
%  \begin{macrocode}
\@@_add_plain_tex_option:nnn
  { helperScriptFileName }
  { path }
  { \jobname.markdown.lua }
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \Opt{helperScriptFileName} macro has been deprecated and
% will be removed in Markdown 3.0.0. To control the filename of the helper Lua
% script file, use the `\g_luabridge_helper_script_filename_str` macro from the
% \pkg{lt3luabridge} package.
%
% \end{markdown}
%  \begin{macrocode}
\str_new:N
  \g_luabridge_helper_script_filename_str
\tl_gset:Nn
  \g_luabridge_helper_script_filename_str
  { \markdownOptionHelperScriptFileName }
%    \end{macrocode}
% \begin{markdown}
%
% The \mdef{markdownOptionInputTempFileName} macro sets the filename of the
% temporary input file that is created during the buffering of markdown text
% from a \TeX{} source. It defaults to `\jobname.markdown.in`. The same
% limitations as in the case of the \Opt{helperScriptFileName}
% macro apply here.
%
% \end{markdown}
%  \begin{macrocode}
\@@_add_plain_tex_option:nnn
  { inputTempFileName }
  { path }
  { \jobname.markdown.in }
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \mdef{markdownOptionOutputTempFileName} macro sets the filename of the
% temporary output file that is created during the conversion from markdown to
% plain \TeX{} in \mref{markdownMode} other than `2` It defaults to
% `\jobname.markdown.out`. The same limitations apply here as in the case
% of the \Opt{helperScriptFileName} macro.
%
% \end{markdown}
%  \begin{macrocode}
\@@_add_plain_tex_option:nnn
  { outputTempFileName }
  { path }
  { \jobname.markdown.out }
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \Opt{outputTempFileName} macro has been deprecated and
% will be removed in Markdown 3.0.0.
%
% \end{markdown}
%  \begin{macrocode}
\str_new:N
  \g_luabridge_standard_output_filename_str
\tl_gset:Nn
  \g_luabridge_standard_output_filename_str
  { \markdownOptionOutputTempFileName }
%    \end{macrocode}
% \begin{markdown}
%
% The \mdef{markdownOptionErrorTempFileName} macro sets the filename of the
% temporary output file that is created when a Lua error is encountered during
% the conversion from markdown to plain \TeX{} in \mref{markdownMode} other than
% `2`. It defaults to `\jobname.markdown.err`. The same limitations
% apply here as in the case of the \Opt{helperScriptFileName}
% macro.
%
% \end{markdown}
%  \begin{macrocode}
\@@_add_plain_tex_option:nnn
  { errorTempFileName }
  { path }
  { \jobname.markdown.err }
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \Opt{errorTempFileName} macro has been deprecated and
% will be removed in Markdown 3.0.0. To control the filename of the temporary
% file for Lua errors, use the `\g_luabridge_error_output_filename_str` macro
% from the \pkg{lt3luabridge} package.
%
% \end{markdown}
%  \begin{macrocode}
\str_new:N
  \g_luabridge_error_output_filename_str
\tl_gset:Nn
  \g_luabridge_error_output_filename_str
  { \markdownOptionErrorTempFileName }
%    \end{macrocode}
% \begin{markdown}
%
% The \mdef{markdownOptionOutputDir} macro sets the path to the directory that
% will contain the auxiliary cache files produced by the Lua implementation and
% also the auxiliary files produced by the plain \TeX{} implementation. The
% option defaults to `.`.
%
% The path must be set to the same value as the `-output-directory` option of
% your \TeX{} engine for the package to function correctly. We need this macro
% to make the Lua implementation aware where it should store the helper files.
% The same limitations apply here as in the case of the
% \Opt{helperScriptFileName} macro.
%
% \end{markdown}
%  \begin{macrocode}
\@@_add_plain_tex_option:nnn
  { outputDir }
  { path }
  { . }
%    \end{macrocode}
% \begin{markdown}
%
% Here, we automatically define plain \TeX{} macros for the above plain \TeX{}
% options.
%
% Furthemore, we also define macros that map directly to the options recognized
% by the Lua interface, such as \mdef{markdownOptionHybrid} for the
% \Opt{hybrid} Lua option (see Section <#sec:luaoptions>), which are not
% processed by the plain \TeX{} implementation, only passed along to Lua.
%
% For the macros that correspond to the non-boolean options recognized by the
% Lua interface, the same limitations apply here in the case of the
% \Opt{helperScriptFileName} macro.
%
% \end{markdown}
%  \begin{macrocode}
\cs_new:Nn \@@_plain_tex_define_option_commands:
  {
    \seq_map_inline:Nn
      \g_@@_option_layers_seq
      {
        \seq_map_inline:cn
          { g_@@_ ##1 _options_seq }
          {
              \@@_plain_tex_define_option_command:n
                { ####1 }
          }
      }
  }
\cs_new:Nn \@@_plain_tex_define_option_command:n
  {
    \@@_get_default_option_value:nN
      { #1 }
      \l_tmpa_tl
    \@@_set_option_value:nV
      { #1 }
      \l_tmpa_tl
  }
\cs_new:Nn
  \@@_set_option_value:nn
  {
    \@@_define_option:n
      { #1 }
    \@@_get_option_type:nN
      { #1 }
      \l_tmpa_tl
    \str_if_eq:NNTF
      \c_@@_option_type_counter_tl
      \l_tmpa_tl
      {
        \@@_option_tl_to_csname:nN
          { #1 }
          \l_tmpa_tl
        \int_gset:cn
          { \l_tmpa_tl }
          { #2 }
      }
      {
        \@@_option_tl_to_csname:nN
          { #1 }
          \l_tmpa_tl
        \cs_set:cpn
          { \l_tmpa_tl }
          { #2 }
      }
  }
\cs_generate_variant:Nn
  \@@_set_option_value:nn
  { nV }
\cs_new:Nn
  \@@_define_option:n
  {
    \@@_option_tl_to_csname:nN
      { #1 }
      \l_tmpa_tl
    \cs_if_free:cT
      { \l_tmpa_tl }
      {
        \@@_get_option_type:nN
          { #1 }
          \l_tmpb_tl
        \str_if_eq:NNT
          \c_@@_option_type_counter_tl
          \l_tmpb_tl
          {
            \@@_option_tl_to_csname:nN
              { #1 }
              \l_tmpa_tl
            \int_new:c
              { \l_tmpa_tl }
          }
      }
  }
\@@_plain_tex_define_option_commands:
%    \end{macrocode}
%
% \iffalse
%</tex>
%<*manual-options>

The plain \TeX{} interface provides the following commands that you can use to
specify the location of temporary files produced during the conversion from
Markdown to \TeX{}:

- `\markdownOptionHelperScriptFileName`,
- `\markdownOptionInputTempFileName`,
- `\markdownOptionOutputTempFileName`,
- `\markdownOptionErrorTempFileName`,
- `\markdownOptionOutputDir`,
- `\markdownOptionCacheDir`, and
- `\markdownOptionFrozenCacheFileName`.

The `\markdownOptionCacheDir` and `\markdownOptionFrozenCacheFileName` commands
correspond to the `cacheDir` and `frozenCacheFileName` Lua options.

Using a text editor, create a folder named `output-directory` and a text
document named `document.tex` with the following content:
``` tex
\input lmfonts
\input markdown
\def\markdownOptionHelperScriptFileName{helper-script.lua}
\def\markdownOptionInputTempFileName{temporary-input.md}
\def\markdownOptionOutputTempFileName{temporary-output.tex}
\def\markdownOptionErrorTempFileName{error-output.txt}
\def\markdownOptionOutputDir{output-directory}
\def\markdownOptionCacheDir{output-directory/cache-directory}
\markdownOptionFinalizeCachetrue
\def\markdownOptionFrozenCacheFileName{output-directory/cache-directory/frozen-cache.tex}
\markdownBegin
Hello *world*!
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex --output-directory output-directory document.tex
``````
A text document named `temporary-input.md` should be produced in the folder
named `output-directory` and contain the following text:

> Hello \*world\*!

A folder named `output-directory/cache-directory` should also be produced and
contain fragments of the converted markdown document. LuaTeX does not need
other temporary files to perform the conversion from markdown to \TeX{}. To
produce the remaining temporary files, invoke pdfTeX from the terminal:
``` sh
pdftex --output-directory output-directory --shell-escape document.tex
``````
Text documents named `helper-script.lua`, and `temporary-output.md` should be
produced in the folder named `output-directory`.  The document named
`helper-script.lua` will contain Lua code that was executed to convert markdown
to plain \TeX{}.  The document named `temporary-output.tex` will contain the
input markdown document converted to \TeX{}.

No document named `error-output.txt` should be produced in the folder named
`output-directory`. This document would only be produced if an error had occured
while executing the Lua code. If this happens, please [file a
bug](https://github.com/witiko/markdown/issues).

#### Package Documentation

The \mdef{markdownOptionStripPercentSigns} macro controls whether a percent
sign (`\%`) at the beginning of a line will be discarded when reading Markdown
input from a \TeX{} document. This enables the use of markdown when writing
\TeX{} package documentation using the [Doc \LaTeX{} package][doc] by Frank
Mittelbach. The recognized values of the macro are `true` (discard) and `false`
(retain). It defaults to `false`.

 [doc]: https://ctan.org/pkg/doc (doc – Format LaTeX documentation)

Using a text editor, create a text document named `document.dtx` with the
following content:

 ``` tex
 % \iffalse
 \documentclass{ltxdoc}
 \usepackage[stripPercentSigns]{markdown}
 \begin{document}
 \DocInput{document.dtx}
 \end{document}
 % \fi
 %
 % \begin{markdown}
 % Hello *world*!
 % \end{markdown}
 ```````

Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.dtx
``````
A PDF document named `document.pdf` should be produced and contain the text
“Hello *world*!”

%</manual-options>
%<*tex>
% \fi
% \begin{markdown}
%
%#### Miscellaneous Options
%
% The \mdef{markdownOptionStripPercentSigns} macro controls whether a percent
% sign (`\%`) at the beginning of a line will be discarded when buffering
% Markdown input (see Section <#sec:buffering>) or not. Notably, this
% enables the use of markdown when writing \TeX{} package documentation using
% the \pkg{Doc} \LaTeX{}~package~[@mittelbach17] or similar. The recognized
% values of the macro are `true` (discard) and `false` (retain). It defaults
% to `false`.
%
% \end{markdown}
%  \begin{macrocode}
\seq_gput_right:Nn
  \g_@@_plain_tex_options_seq
  { stripPercentSigns }
\prop_gput:Nnn
  \g_@@_plain_tex_option_types_prop
  { stripPercentSigns }
  { boolean }
\prop_gput:Nnx
  \g_@@_default_plain_tex_options_prop
  { stripPercentSigns }
  { false }
\ExplSyntaxOff
%    \end{macrocode}
% \iffalse
%</tex>
%<*manual-tokens>

## Markdown Tokens

A key feature of the Markdown package is the support for manipulating markdown
tokens, such as headings, emphasized text, links, and lists, in \TeX{}. Instead
of reducing \TeX{} to a PDF document producer, the Markdown package allows the
user to specify how every markdown token should be processed and rendered.

% \fi
% \begin{markdown}

### Token Renderers {#texrenderersuser}

% \end{markdown}
% \iffalse

Token renderers are user-defined \TeX{} macros, which render markdown tokens.
In this section, I will describe the individual token renderers.

% \fi
% \begin{markdown}
%
% The following \TeX{} macros may occur inside the output of the
% converter functions exposed by the Lua interface (see Section
% <#sec:luaconversion>) and represent the parsed markdown tokens. These
% macros are intended to be redefined by the user who is typesetting a
% document. By default, they point to the corresponding prototypes (see Section
% <#sec:texrendererprototypes>).
%
% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
% \begin{markdown}
%
% To enable the enumeration of token renderers, we will maintain the
% \mdef{g_\@\@_renderers_seq} sequence.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\seq_new:N \g_@@_renderers_seq
%    \end{macrocode}
% \begin{markdown}
%
% To enable the reflection of token renderers and their parameters, we will
% maintain the \mdef{g_\@\@_renderer_arities_prop} property list.
%
% \end{markdown}
%  \begin{macrocode}
\prop_new:N \g_@@_renderer_arities_prop
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Attribute Renderers
The following macros are only produced, when the \Opt{headerAttributes} option
is enabled.

\mdef{markdownRendererAttributeIdentifier} represents the \meta{identifier} of
a markdown element (`id="`\meta{identifier}`"` in HTML and `#`\meta{identifier}
in Markdown's \Opt{headerAttributes} syntax extension). The macro receives a
single attribute that corresponds to the \meta{identifier}.

\mdef{markdownRendererAttributeClassName} represents the \meta{class name} of a
markdown element (`class="`\meta{class name} ...`"` in HTML and
`.`\meta{class name} in Markdown's \Opt{headerAttributes} syntax extension).
The macro receives a single attribute that corresponds to the \meta{class
name}.

\mdef{markdownRendererAttributeKeyValue} represents a HTML attribute in the form
\meta{key}`=`\meta{value} that is neither an identifier nor a class name.
The macro receives two attributes that correspond to the \meta{key} and the
\meta{value}, respectively.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[headerAttributes, underscores=false]{markdown}
\markdownSetup{
  renderers = {
    attributeIdentifier = {%
      \par
      \emph{(Identifier: #1)}
      \par
    },
    attributeClassName = {%
      \par
      \emph{(Class name: #1)}
      \par
    },
    attributeKeyValue = {%
      \par
      \emph{(Key: #1, Value: #2)}
      \par
    },
  },
}
\begin{document}
\begin{markdown}

# First top-level heading {jane=doe}

## A subheading {#identifier}

# Second top-level heading {.class_name}

\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> # First top-level heading
>
> *(Key: Jane, Value: Doe)*
>
> ## A subheading
>
> *(Identifier: identifier)*
>
> # Second top-level heading
>
> *(Class name: class\_name)*

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererAttributeIdentifier{%
  \markdownRendererAttributeIdentifierPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { attributeIdentifier }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { attributeIdentifier }
  { 1 }
\ExplSyntaxOff
\def\markdownRendererAttributeClassName{%
  \markdownRendererAttributeClassNamePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { attributeClassName }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { attributeClassName }
  { 1 }
\ExplSyntaxOff
\def\markdownRendererAttributeKeyValue{%
  \markdownRendererAttributeKeyValuePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { attributeKeyValue }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { attributeKeyValue }
  { 2 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Block Quote Renderers
The \mdef{markdownRendererBlockQuoteBegin} macro represents the beginning of
a block quote. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererBlockQuoteBegin{%
  \markdownRendererBlockQuoteBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { blockQuoteBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { blockQuoteBegin }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererBlockQuoteEnd} macro represents the end of a block
quote. The macro receives no arguments.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownRendererBlockQuoteBegin{%
  \begingroup
  \vskip\parindent
  \leftskip=2\parindent
  \parindent=0pt
}
\def\markdownRendererBlockQuoteEnd{%
  \par
  \vskip\parindent
  \endgroup
}
\markdownBegin
A quote from William Shakespeare's King Lear:

> This is the excellent foppery of the world that when we are
> sick in fortune---often the surfeit of our own behavior---we
> make guilty of our disasters the sun, the moon, and the
> stars [...]
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A quote from William Shakespeare's King Lear:
>
> > This is the excellent foppery of the world that when we are
> > sick in fortune—often the surfeit of our own behavior—we
> > make guilty of our disasters the sun, the moon, and the
> > stars [...]

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\markdownSetup{
  renderers = {
    blockQuoteBegin = {\begin{quote}},
    blockQuoteEnd = {\end{quote}},
  },
}
\begin{document}
\begin{markdown}
A quote from William Shakespeare's King Lear:

> This is the excellent foppery of the world that when we are
> sick in fortune---often the surfeit of our own behavior---we
> make guilty of our disasters the sun, the moon, and the
> stars [...]
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A quote from William Shakespeare's King Lear:
>
> > This is the excellent foppery of the world that when we are
> > sick in fortune—often the surfeit of our own behavior—we
> > make guilty of our disasters the sun, the moon, and the
> > stars [...]

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\def\markdownRendererBlockQuoteBegin{\startquotation}
\def\markdownRendererBlockQuoteEnd{\stopquotation}
\starttext
\startmarkdown
A quote from William Shakespeare's King Lear:

> This is the excellent foppery of the world that when we are
> sick in fortune---often the surfeit of our own behavior---we
> make guilty of our disasters the sun, the moon, and the
> stars [...]
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> A quote from William Shakespeare's King Lear:
>
> > This is the excellent foppery of the world that when we are
> > sick in fortune—often the surfeit of our own behavior—we
> > make guilty of our disasters the sun, the moon, and the
> > stars [...]

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererBlockQuoteEnd{%
  \markdownRendererBlockQuoteEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { blockQuoteEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { blockQuoteEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Bracketed Spans Attribute Context Renderers
The following macros are only produced, when the \Opt{bracketedSpans} option is
enabled.

The \mdef{markdownRendererBracketedSpanAttributeContextBegin} and
\mdef{markdownRendererBracketedSpanAttributeContextEnd} macros represent the
beginning and the end of an inline bracketed span in which the attributes of
the span apply. The macros receive no arguments.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[bracketedSpans]{markdown}
\markdownSetup{
  renderers = {
    bracketedSpanAttributeContextBegin = {(},
    bracketedSpanAttributeContextEnd = {)},
  },
}
\begin{document}
\begin{markdown}

[foo [bar]{#identifier}]{key=value} [baz]{.class_name}

\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> (foo (bar)) (baz)

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererBracketedSpanAttributeContextBegin{%
  \markdownRendererBracketedSpanAttributeContextBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { bracketedSpanAttributeContextBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { bracketedSpanAttributeContextBegin }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererBracketedSpanAttributeContextEnd{%
  \markdownRendererBracketedSpanAttributeContextEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { bracketedSpanAttributeContextEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { bracketedSpanAttributeContextEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Bullet List Renderers
The \mdef{markdownRendererUlBegin} macro represents the beginning of a
bulleted list that contains an item with several paragraphs of text (the
list is not tight). The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererUlBegin{%
  \markdownRendererUlBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { ulBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { ulBegin }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererUlBeginTight} macro represents the beginning of a
bulleted list that contains no item with several paragraphs of text (the list
is tight). This macro will only be produced, when the \Opt{tightLists} option
is disabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererUlBeginTight{%
  \markdownRendererUlBeginTightPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { ulBeginTight }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { ulBeginTight }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererUlItem} macro represents an item in a bulleted
list. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererUlItem{%
  \markdownRendererUlItemPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { ulItem }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { ulItem }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererUlItemEnd} macro represents the end of an item in a
bulleted list. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererUlItemEnd{%
  \markdownRendererUlItemEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { ulItemEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { ulItemEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererUlEnd} macro represents the end of a bulleted list
that contains an item with several paragraphs of text (the list is not
tight). The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererUlEnd{%
  \markdownRendererUlEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { ulEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { ulEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererUlEndTight} macro represents the end of a bulleted
list that contains no item with several paragraphs of text (the list is
tight). This macro will only be produced, when the \Opt{tightLists} option is
disabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionTightLists{true}

\def\markdownRendererInterblockSeparator{}
\def\markdownRendererUlBeginTight{ (}
\def\markdownRendererUlItem{%
  \def\markdownRendererUlItem{%
    ,
    \def\markdownRendererUlItem{, and }%
  }%
}
\def\markdownRendererUlItemEnd{}
\def\markdownRendererUlEndTight{).}

\markdownBegin
This is a tight list

- the first item
- the second item
- the third item
\markdownEnd

\def\markdownRendererInterblockSeparator{%
  :\par
  \def\markdownRendererInterblockSeparator{\par}%
}
\def\markdownRendererUlBegin{}
\def\markdownRendererUlItem{--\kern 0.5em}
\def\markdownRendererUlItemEnd{.\par}
\def\markdownRendererUlEnd{}

\markdownBegin
This is a loose list

- This is the first item

- This is the second item

- This is the third item
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is a tight list (the first item, the second item, and the third item).
>
> This is a loose list:
> 
> - This is the first item.
> 
> - This is the second item.
> 
> - This is the third item.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[tightLists]{markdown}
\begin{document}

\begin{markdown*}{
  renderers = {
    interblockSeparator = {},
    ulBeginTight = { (},
    ulItem = {%
      \def\markdownRendererUlItem{%
        ,
        \def\markdownRendererUlItem{, and }%
      }%
    },
    ulItemEnd = {},
    ulEndTight = {).},
  },  
}
This is a tight list

- the first item
- the second item
- the third item
\end{markdown*}

\begin{markdown*}{
  renderers = {
    interblockSeparator = {%
      :\par
      \def\markdownRendererInterblockSeparator{\par}%
    },
    ulBeginTight = {\begin{itemize}},
    ulItem = {\item},
    ulItemEnd = {.},
    ulEnd = {\end{itemize}},
  },  
}
This is a loose list

- This is the first item

- This is the second item

- This is the third item
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is a tight list (the first item, the second item, and the third item).
>
> This is a loose list:
> 
> - This is the first item.
> 
> - This is the second item.
> 
> - This is the third item.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[tightLists = yes]
\starttext

\def\markdownRendererInterblockSeparator{}
\def\markdownRendererUlBeginTight{ (}
\def\markdownRendererUlItem{%
  \def\markdownRendererUlItem{%
    ,
    \def\markdownRendererUlItem{, and }%
  }%
}
\def\markdownRendererUlItemEnd{}
\def\markdownRendererUlEndTight{).}

\startmarkdown
This is a tight list

- the first item
- the second item
- the third item
\stopmarkdown

\def\markdownRendererInterblockSeparator{%
  :\par
  \def\markdownRendererInterblockSeparator{\par}%
}
\def\markdownRendererUlBegin{\startitemize}
\def\markdownRendererUlItem{\item}
\def\markdownRendererUlItemEnd{.}
\def\markdownRendererUlEnd{\stopitemize}

\startmarkdown
This is a loose list

- This is the first item

- This is the second item

- This is the third item
\stopmarkdown

\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is a tight list (the first item, the second item, and the third item).
>
> This is a loose list:
> 
> - This is the first item.
> 
> - This is the second item.
> 
> - This is the third item.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererUlEndTight{%
  \markdownRendererUlEndTightPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { ulEndTight }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { ulEndTight }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Code Block Renderers
The \mdef{markdownRendererInputVerbatim} macro represents a code
block. The macro receives a single argument that corresponds to the
filename of a file contaning the code block contents.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererInputVerbatim{%
  \markdownRendererInputVerbatimPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { inputVerbatim }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { inputVerbatim }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererInputFencedCode} macro represents a fenced code
block. This macro will only be produced, when the \Opt{fencedCode} option is
enabled. The macro receives two arguments that correspond to the filename of
a file contaning the code block contents and to the code fence infostring.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{verbatim}
\usepackage[hyphens]{url}
\usepackage[fencedCode]{markdown}
\markdownSetup{
  renderers = {
    interblockSeparator = {
      \def\markdownRendererInterblockSeparator{%
        \par
        \def\markdownRendererInterblockSeparator{%
          \def\markdownRendererInterblockSeparator{%
            \par
          }%
        }%
      }%
    },
    inputVerbatim = {
      is contained in file \url{#1}:%
      \verbatiminput{#1}%
    },
    inputFencedCode = {
      in #2 \markdownRendererInputVerbatim{#1}%
    },
  },
}
\begin{document}
\begin{markdown}
The following code

    def foo(bar):
      if len(bar) <= 1:
        return bar[0]
      elif len(bar) == 2:
        return sorted(bar)
      else:
        baz = len(bar) // 2
        return foo(bar[baz:], bar[:baz])

The following code

~~~ Python
>>> foo([4, 2, 1, 3])
[1, 2, 3, 4]
~~~~~~~~~~
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text except for the filename, which may differ:

> The following code is contained in file
> `./_markdown_document/882453149edcf288976647f6fe147ada.verbatim`:
> ``` py
> def foo(bar):
>   if len(bar) <= 1:
>     return bar[:1]
>   elif len(bar) == 2:
>     return sorted(bar)
>   else:
>     baz = bar[len(bar) // 2]
>     return (
>       foo([qux for qux in bar if qux < baz]) + [baz] +
>       foo([qux for qux in bar if qux > baz])
>     )
> ``````
> The following code in Python contained in file
> `./_markdown_document/cf2a96e2120cef5b1fae5fea36fcc27b.verbatim`:
> ``` py
> >>> foo([4, 2, 1, 3])
> [1, 2, 3, 4]
> ``````

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererInputFencedCode{%
  \markdownRendererInputFencedCodePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { inputFencedCode }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { inputFencedCode }
  { 2 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
% \begin{markdown}

#### Code Span Renderer
The \mdef{markdownRendererCodeSpan} macro represents inline code span in the
input text. It receives a single argument that corresponds to the inline
code span.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\input lmfonts

\def\markdownRendererCodeSpan#1{#1}

\markdownBegin
`$\sqrt{-1}$ *equals* $i$`

$\sqrt{-1}$ *equals* $i$
\markdownEnd

\def\markdownOptionHybrid{true}
\markdownBegin
$\sqrt{-1}$ *equals* $i$
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt{-1}\$ \*equals\* \$i\$.
> 
> \$\\sqrt{-1}\$ *equals* \$i\$.
> 
> √-̅1̅ *equals* $i$.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[smartEllipses]{markdown}
\markdownSetup{
  renderers = {
    codeSpan = {#1},
  },
}
\begin{document}

\begin{markdown}
`$\sqrt{-1}$ *equals* $i$`

$\sqrt{-1}$ *equals* $i$
\end{markdown}

\begin{markdown*}{hybrid}
$\sqrt{-1}$ *equals* $i$
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt{-1}\$ \*equals\* \$i\$.
> 
> \$\\sqrt{-1}\$ *equals* \$i\$.
> 
> √-̅1̅ *equals* $i$.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\def\markdownRendererCodeSpan#1{#1}
\starttext

\startmarkdown
`$\sqrt{-1}$ *equals* $i$`

$\sqrt{-1}$ *equals* $i$
\stopmarkdown

\setupmarkdown[hybrid = yes]
\startmarkdown
$\sqrt{-1}$ *equals* $i$
\stopmarkdown

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt{-1}\$ \*equals\* \$i\$.
> 
> \$\\sqrt{-1}\$ *equals* \$i\$.
> 
> √-̅1̅ *equals* $i$.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererCodeSpan{%
  \markdownRendererCodeSpanPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { codeSpan }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { codeSpan }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Content Block Renderers {#texcontentblockrenderers}

The \mdef{markdownRendererContentBlock} macro represents an iA\,Writer content
block. It receives four arguments: the local file or online image filename
extension cast to the lower case, the fully escaped \acro{uri} that can be
directly typeset, the raw \acro{uri} that can be used outside typesetting,
and the title of the content block.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererContentBlock{%
  \markdownRendererContentBlockPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { contentBlock }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { contentBlock }
  { 4 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererContentBlockOnlineImage} macro represents an
iA\,Writer online image content block. The macro receives the same arguments
as \mref{markdownRendererContentBlock}.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererContentBlockOnlineImage{%
  \markdownRendererContentBlockOnlineImagePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { contentBlockOnlineImage }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { contentBlockOnlineImage }
  { 4 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererContentBlockCode} macro represents an iA\,Writer
content block that was recognized as a file in a known programming language
by its filename extension $s$. If any `markdown-languages.json` file found
by \pkg{kpathsea}^[Filenames other than `markdown-languages.json` may
be specified using the `contentBlocksLanguageMap` Lua option.] contains a
record $(k, v)$, then a non-online-image content block with the filename
extension $s, s$`:lower()`${}=k$ is considered to be in a known programming
language $v$.
The macro receives five arguments: the local file name extension $s$ cast to
the lower case, the language $v$, the fully escaped \acro{uri} that can be
directly typeset, the raw \acro{uri} that can be used outside typesetting,
and the title of the content block.

Note that you will need to place place a `markdown-languages.json` file
inside your working directory or inside your local \TeX{} directory
structure.  In this file, you will define a mapping between filename
extensions and the language names recognized by your favorite syntax
highlighter; there may exist other creative uses beside syntax highlighting.
% The `Languages.json` file provided by @sotkov17 is a good starting point.
% \end{markdown}
%
% \iffalse
[The `Languages.json` file provided by Anton Sotkov][sotkov17] is a good
starting point.

 [sotkov17]: https://github.com/iainc/Markdown-Content-Blocks
             (File transclusion syntax for Markdown)

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionContentBlocks{true}
\def\markdownRendererContentBlock#1#2#3#4{%
  This is {\tt #2}, #4.
}
\def\markdownRendererContentBlockOnlineImage#1#2#3#4{%
  This is the image {\tt #2}, #4.
}
\def\markdownRendererContentBlockCode#1#2#3#4#5{%
  This is the #2 (\uppercase{#1}) document {\tt #3}, #5.
}
\markdownBegin
/document.tex (the document that we are currently typesetting)
/markdown-languages.json (the mapping between filename extensions
                          and programming language names)
https://tug.org/tugboat/noword.jpg (the logotype of TUGboat)
\markdownEnd
\bye
```````
Create also a text document named `markdown-languages.json` with the following
content:
``` js
{
  "json": "JavaScript Object Notation",
}
``````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is `document.tex`, the document that we are currently typesetting.
>
> This is the JavaScript Object Notation (JSON) document
> `markdown-languages.json`, the mapping between filename extensions and
> programming language names.
>
> This is the image `https://tug.org/tugboat/noword.jpg`, the logotype of
> TUGboat.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\begin{filecontents}[overwrite,nosearch,noheader]{markdown-languages.json}
{
  "json": "JavaScript Object Notation",
}
\end{filecontents}
\usepackage[contentBlocks]{markdown}
\markdownSetup{
  renderers = {
    contentBlock = {This is \texttt{#2}, #4.},
    contentBlockOnlineImage = {This is the image \texttt{#2}, #4.},
    contentBlockCode = {%
      This is the #2 (\MakeUppercase{#1}) document \texttt{#3}, #5.
    },
  },
}
\begin{document}
\begin{markdown}
/document.tex (the document that we are currently typesetting)
/markdown-languages.json (the mapping between filename extensions
                          and programming language names)
https://tug.org/tugboat/noword.jpg (the logotype of TUGboat)
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is `document.tex`, the document that we are currently typesetting.
>
> This is the JavaScript Object Notation (JSON) document
> `markdown-languages.json`, the mapping between filename extensions and
> programming language names.
>
> This is the image `https://tug.org/tugboat/noword.jpg`, the logotype of
> TUGboat.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[contentBlocks = yes]
\def\markdownRendererContentBlock#1#2#3#4{%
  This is {\tt #2}, #4.
}
\def\markdownRendererContentBlockOnlineImage#1#2#3#4{%
  This is the image {\tt #2}, #4.
}
\def\markdownRendererContentBlockCode#1#2#3#4#5{%
  This is the #2 (\uppercase{#1}) document {\tt #3}, #5.
}
\starttext
\startmarkdown
/document.tex (the document that we are currently typesetting)
/markdown-languages.json (the mapping between filename extensions
                          and programming language names)
https://tug.org/tugboat/noword.jpg (the logotype of TUGboat)
\stopmarkdown
\stoptext
```````
Create also a text document named `markdown-languages.json` with the following
content:
``` js
{
  "json": "JavaScript Object Notation",
}
``````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is `document.tex`, the document that we are currently typesetting.
>
> This is the JavaScript Object Notation (JSON) document
> `markdown-languages.json`, the mapping between filename extensions and
> programming language names.
>
> This is the image `https://tug.org/tugboat/noword.jpg`, the logotype of
> TUGboat.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererContentBlockCode{%
  \markdownRendererContentBlockCodePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { contentBlockCode }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { contentBlockCode }
  { 5 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Definition List Renderers
The following macros are only produced, when the \Opt{definitionLists} option
is enabled.

The \mdef{markdownRendererDlBegin} macro represents the beginning of a
definition list that contains an item with several paragraphs of text (the
list is not tight). The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererDlBegin{%
  \markdownRendererDlBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { dlBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { dlBegin }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererDlBeginTight} macro represents the beginning of a
definition list that contains an item with several paragraphs of text (the
list is not tight). This macro will only be produced, when the
\Opt{tightLists} option is disabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererDlBeginTight{%
  \markdownRendererDlBeginTightPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { dlBeginTight }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { dlBeginTight }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererDlItem} macro represents a term in a definition
list. The macro receives a single argument that corresponds to the term
being defined.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererDlItem{%
  \markdownRendererDlItemPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { dlItem }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { dlItem }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererDlItemEnd} macro represents the end of a list of
definitions for a single term.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererDlItemEnd{%
  \markdownRendererDlItemEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { dlItemEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { dlItemEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererDlDefinitionBegin} macro represents the beginning
of a definition in a definition list. There can be several definitions for
a single term.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererDlDefinitionBegin{%
  \markdownRendererDlDefinitionBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { dlDefinitionBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { dlDefinitionBegin }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererDlDefinitionEnd} macro represents the end of a
definition in a definition list. There can be several definitions for a
single term.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererDlDefinitionEnd{%
  \markdownRendererDlDefinitionEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { dlDefinitionEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { dlDefinitionEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererDlEnd} macro represents the end of a definition
list that contains an item with several paragraphs of text (the list is not
tight). The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererDlEnd{%
  \markdownRendererDlEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { dlEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { dlEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererDlEndTight} macro represents the end of a
definition list that contains no item with several paragraphs of text (the
list is tight). This macro will only be produced, when the \Opt{tightLists}
option is disabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionDefinitionLists{true}
\def\markdownOptionTightLists{true}

\def\markdownRendererInterblockSeparator{%
  :%
  \def\markdownRendererInterblockSeparator{\par}%
}
\def\markdownRendererDlBeginTight{%
  \begingroup
  \parindent=0pt
}
\def\markdownRendererDlItem#1{%
  \par{\bf#1}%
  \def\markdownRendererDlDefinitionEnd{%
    ,
    \def\markdownRendererDlDefinitionEnd{%
      , and
      \def\markdownRendererDlDefinitionEnd{.}%
    }%
  }%
}
\def\markdownRendererDlItemEnd{}
\def\markdownRendererDlDefinitionBegin{\par--\kern 0.5em}
\def\markdownRendererDlEndTight{\endgroup}

\markdownBegin
This is a tight definition list

Coffee
:   black hot drink
:   prepared from roasted coffee beans
:   one of the most traded agricultural commodities in the world

Milk
:   white cold drink
:   nutrient-rich
:   produced on an industrial scale
\markdownEnd

\def\markdownRendererInterblockSeparator{%
  \def\markdownRendererInterblockSeparator{\par}%
}
\def\markdownRendererDlBegin{}
\def\markdownRendererDlItem#1{%
  . #1 is a
  \def\markdownRendererDlDefinitionBegin{%
    \def\markdownRendererDlDefinitionBegin{%
      ,
      \def\markdownRendererDlDefinitionBegin{, and }%
    }%
  }%
}
\def\markdownRendererDlItemEnd{}
\def\markdownRendererDlDefinitionEnd{}
\def\markdownRendererDlEnd{.}

\markdownBegin
This is a loose definition list

Coffee

:   black hot drink

:   prepared from roasted coffee beans

:   one of the most traded agricultural commodities in the world

Milk

:   white cold drink

:   nutrient-rich

:   produced on an industrial scale
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is a tight definition list:
>
> **Coffee**
>
> - black hot drink,
> - prepared from roasted coffee beans, and
> - one of the most traded agricultural commodities in the world.
>
> **Milk**
>
> - white cold drink,
> - nutrient-rich, and
> - produced on an industrial scale.
>
> This is a loose definition list. Coffee is a black hot drink, prepared from
> roasted coffee beans, and one of the most traded agricultural commodities in
> the world. Milk is a white cold drink, nutrient-rich, and produced on an
> industrial scale.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[definitionLists, tightLists]{markdown}
\begin{document}

\begin{markdown*}{
  renderers = {
    interblockSeparator = {%
      :%
      \def\markdownRendererInterblockSeparator{\par}%
    },
    dlBeginTight = {\begin{description}},
    dlItem = {%
      \item[#1]
      \begin{itemize}
      \def\markdownRendererDlDefinitionEnd{%
        ,
        \def\markdownRendererDlDefinitionEnd{%
          , and
          \def\markdownRendererDlDefinitionEnd{.}%
        }%
      }%
    },
    dlItemEnd = {\end{itemize}},
    dlDefinitionBegin = \item,
    dlEndTight = {\end{description}},
  },
}
This is a tight definition list

Coffee
:   black hot drink
:   prepared from roasted coffee beans
:   one of the most traded agricultural commodities in the world

Milk
:   white cold drink
:   nutrient-rich
:   produced on an industrial scale
\end{markdown*}

\begin{markdown*}{
  renderers = {
    interblockSeparator = {%
      \def\markdownRendererInterblockSeparator{\par}%
    },
    dlBegin = {},
    dlItem = {%
      . #1 is a
      \def\markdownRendererDlDefinitionBegin{%
        \def\markdownRendererDlDefinitionBegin{%
          ,
          \def\markdownRendererDlDefinitionBegin{, and }%
        }%
      }%
    },
    dlItemEnd = {},
    dlDefinitionEnd = {},
    dlEnd = {.},
  },
}
This is a loose definition list

Coffee

:   black hot drink

:   prepared from roasted coffee beans

:   one of the most traded agricultural commodities in the world

Milk

:   white cold drink

:   nutrient-rich

:   produced on an industrial scale
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is a tight definition list:
>
> **Coffee**
>
> - black hot drink,
> - prepared from roasted coffee beans, and
> - one of the most traded agricultural commodities in the world.
>
> **Milk**
>
> - white cold drink,
> - nutrient-rich, and
> - produced on an industrial scale.
>
> This is a loose definition list. Coffee is a black hot drink, prepared from
> roasted coffee beans, and one of the most traded agricultural commodities in
> the world. Milk is a white cold drink, nutrient-rich, and produced on an
> industrial scale.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown
  [
    definitionLists = yes,
    tightLists = yes,
  ]
\starttext

\def\markdownRendererInterblockSeparator{%
  :%
  \def\markdownRendererInterblockSeparator{\par}%
}
\def\markdownRendererDlBeginTight{}
\def\markdownRendererDlItem#1{%
  \par{\bf#1}%
  \startitemize
  \def\markdownRendererDlDefinitionEnd{%
    ,
    \def\markdownRendererDlDefinitionEnd{%
      , and
      \def\markdownRendererDlDefinitionEnd{.}%
    }%
  }%
}
\def\markdownRendererDlItemEnd{\stopitemize}
\def\markdownRendererDlDefinitionBegin{\item}
\def\markdownRendererDlEndTight{}

\startmarkdown
This is a tight definition list

Coffee
:   black hot drink
:   prepared from roasted coffee beans
:   one of the most traded agricultural commodities in the world

Milk
:   white cold drink
:   nutrient-rich
:   produced on an industrial scale
\stopmarkdown

\def\markdownRendererInterblockSeparator{%
  \def\markdownRendererInterblockSeparator{\par}%
}
\def\markdownRendererDlBegin{}
\def\markdownRendererDlItem#1{%
  . #1 is a
  \def\markdownRendererDlDefinitionBegin{%
    \def\markdownRendererDlDefinitionBegin{%
      ,
      \def\markdownRendererDlDefinitionBegin{, and }%
    }%
  }%
}
\def\markdownRendererDlItemEnd{}
\def\markdownRendererDlDefinitionEnd{}
\def\markdownRendererDlEnd{.}

\startmarkdown
This is a loose definition list

Coffee

:   black hot drink

:   prepared from roasted coffee beans

:   one of the most traded agricultural commodities in the world

Milk

:   white cold drink

:   nutrient-rich

:   produced on an industrial scale
\stopmarkdown

\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is a tight definition list:
>
> **Coffee**
>
> - black hot drink,
> - prepared from roasted coffee beans, and
> - one of the most traded agricultural commodities in the world.
>
> **Milk**
>
> - white cold drink,
> - nutrient-rich, and
> - produced on an industrial scale.
>
> This is a loose definition list. Coffee is a black hot drink, prepared from
> roasted coffee beans, and one of the most traded agricultural commodities in
> the world. Milk is a white cold drink, nutrient-rich, and produced on an
> industrial scale.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererDlEndTight{%
  \markdownRendererDlEndTightPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { dlEndTight }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { dlEndTight }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Ellipsis Renderer
The \mdef{markdownRendererEllipsis} macro replaces any occurance of ASCII
ellipses in the input text. This macro will only be produced, when the
\Opt{smartEllipses} option is enabled.  The macro receives no arguments.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionSmartEllipses{true}
\def\markdownRendererEllipsis{{\it SHAZAM}!}
\markdownBegin
The secret word is ...
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> The secret word is *SHAZAM*!

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[smartEllipses]{markdown}
\markdownSetup{
  renderers = {
    ellipsis = \emph{SHAZAM}!,
  },
}
\begin{document}
\begin{markdown}
The secret word is ...
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> The secret word is *SHAZAM*!

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[smartEllipses = yes]
\def\markdownRendererEllipsis{\emph{SHAZAM}!}
\starttext
\startmarkdown
The secret word is ...
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Hello *world*!
>
> *(The end of a block)*
> 
> _Foo_ bar!

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererEllipsis{%
  \markdownRendererEllipsisPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { ellipsis }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { ellipsis }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Emphasis Renderers
The \mdef{markdownRendererEmphasis} macro represents an emphasized span of
text. The macro receives a single argument that corresponds to the emphasized
span of text.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownRendererEmphasis#1{{\it#1}}
\def\markdownRendererStrongEmphasis#1{{\bf#1}}
\markdownBegin
This is *emphasis*.

This is **strong emphasis**.
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is *emphasis*.
>
> This is **strong emphasis**.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\markdownSetup{
  renderers = {
    emphasis = {\emph{#1}},
    strongEmphasis = {\textbf{#1}},
  },
}
\begin{document}
\begin{markdown}
This is *emphasis*.

This is **strong emphasis**.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is *emphasis*.
>
> This is **strong emphasis**.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\def\markdownRendererEmphasis#1{\emph{#1}}
\def\markdownRendererStrongEmphasis#1{\bold{#1}}
\starttext
\startmarkdown
This is *emphasis*.

This is **strong emphasis**.
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is *emphasis*.
>
> This is **strong emphasis**.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererEmphasis{%
  \markdownRendererEmphasisPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { emphasis }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { emphasis }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererStrongEmphasis} macro represents a strongly
emphasized span of text. The macro receives a single argument that
corresponds to the emphasized span of text.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererStrongEmphasis{%
  \markdownRendererStrongEmphasisPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { strongEmphasis }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { strongEmphasis }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Fenced Div Attribute Context Renderers
The following macros are only produced, when the \Opt{fencedDiv} option is
enabled.

The \mdef{markdownRendererFencedDivAttributeContextBegin} and
\mdef{markdownRendererFencedDivAttributeContextEnd} macros represent the beginning
and the end of a div in which the attributes of the div apply. The macros
receive no arguments.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[fencedDivs]{markdown}
\markdownSetup{
  renderers = {
    fencedDivAttributeContextBegin = {%
      \par
      \emph{(The beginning of a fenced div attribute context)}
      \par
    },
    fencedDivAttributeContextEnd = {%
      \par
      \emph{(The end of a fenced div attribute context)}
      \par
    },
  },
}
\begin{document}
\begin{markdown}

::: {key=value}

foo

:::: {#identifier}

bar

::::

:::

::: {.class_name}

baz

:::

\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> *(The beginning of a fenced div attribute context)*
>
> foo
>
> *(The beginning of a fenced div attribute context)*
>
> bar
>
> *(The end of a fenced div attribute context)*
>
> *(The end of a fenced div attribute context)*
>
> *(The beginning of a fenced div attribute context)*
>
> baz
>
> *(The end of a fenced div attribute context)*

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererFencedDivAttributeContextBegin{%
  \markdownRendererFencedDivAttributeContextBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { fencedDivAttributeContextBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { fencedDivAttributeContextBegin }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererFencedDivAttributeContextEnd{%
  \markdownRendererFencedDivAttributeContextEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { fencedDivAttributeContextEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { fencedDivAttributeContextEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Header Attribute Context Renderers
The following macros are only produced, when the \Opt{headerAttributes} option
is enabled.

The \mdef{markdownRendererHeaderAttributeContextBegin} and
\mdef{markdownRendererHeaderAttributeContextEnd} macros represent the beginning
and the end of a section in which the attributes of a heading apply. The macros
receive no arguments.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[headerAttributes]{markdown}
\markdownSetup{
  renderers = {
    headerAttributeContextBegin = {%
      \par
      \emph{(The beginning of a header attribute context)}
      \par
    },
    headerAttributeContextEnd = {%
      \par
      \emph{(The end of a header attribute context)}
      \par
    },
  },
}
\begin{document}
\begin{markdown}

# First top-level heading

## A subheading {#identifier}

# Second top-level heading {.class_name}

\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> # First top-level heading
>
> *(The beginning of a header attribute context)*
>
> ## A subheading
>
> *(The end of a header attribute context)*
>
> *(The beginning of a header attribute context)*
>
> # Second top-level heading
>
> *(The end of a header attribute context)*

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererHeaderAttributeContextBegin{%
  \markdownRendererHeaderAttributeContextBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { headerAttributeContextBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { headerAttributeContextBegin }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererHeaderAttributeContextEnd{%
  \markdownRendererHeaderAttributeContextEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { headerAttributeContextEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { headerAttributeContextEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Heading Renderers
The \mdef{markdownRendererHeadingOne} macro represents a first level heading.
The macro receives a single argument that corresponds to the heading text.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererHeadingOne{%
  \markdownRendererHeadingOnePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { headingOne }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { headingOne }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererHeadingTwo} macro represents a second level
heading. The macro receives a single argument that corresponds to the heading
text.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererHeadingTwo{%
  \markdownRendererHeadingTwoPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { headingTwo }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { headingTwo }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererHeadingThree} macro represents a third level
heading. The macro receives a single argument that corresponds to the heading
text.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererHeadingThree{%
  \markdownRendererHeadingThreePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { headingThree }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { headingThree }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererHeadingFour} macro represents a fourth level
heading. The macro receives a single argument that corresponds to the heading
text.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererHeadingFour{%
  \markdownRendererHeadingFourPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { headingFour }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { headingFour }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererHeadingFive} macro represents a fifth level
heading. The macro receives a single argument that corresponds to the heading
text.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererHeadingFive{%
  \markdownRendererHeadingFivePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { headingFive }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { headingFive }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererHeadingSix} macro represents a sixth level
heading. The macro receives a single argument that corresponds to the heading
text.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownRendererInterblockSeparator{}
\def\markdownRendererHeadingOne{1}
\def\markdownRendererHeadingTwo{2}
\def\markdownRendererHeadingThree{3}
\def\markdownRendererHeadingFour{4}
\def\markdownRendererHeadingFive{5}
\def\markdownRendererHeadingSix{6}
\markdownBegin
######
#####
#####
###
######
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> 65536

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\markdownSetup{
  renderers = {
    interblockSeparator = {},
    headingOne = 1,
    headingTwo = 2,
    headingThree = 3,
    headingFour = 4,
    headingFive = 5,
    headingSix = 6,
  },
}
\begin{document}
\begin{markdown}
######
#####
#####
###
######
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> 65536

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\def\markdownRendererInterblockSeparator{}
\def\markdownRendererHeadingOne{1}
\def\markdownRendererHeadingTwo{2}
\def\markdownRendererHeadingThree{3}
\def\markdownRendererHeadingFour{4}
\def\markdownRendererHeadingFive{5}
\def\markdownRendererHeadingSix{6}
\starttext
\startmarkdown
######
#####
#####
###
######
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> 65536

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererHeadingSix{%
  \markdownRendererHeadingSixPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { headingSix }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { headingSix }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### HTML Comment Renderers

The \mdef{markdownRendererInlineHtmlComment} macro represents the contents of an
inline \acro{HTML} comment. This macro will only be produced, when the
\Opt{html} option is enabled. The macro receives a single argument that
corresponds to the contents of the \acro{HTML} comment.

The \mdef{markdownRendererBlockHtmlCommentBegin} and
\mdef{markdownRendererBlockHtmlCommentEnd} macros represent the beginning
and the end of a block \acro{HTML} comment. The macros receive no arguments.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[html]{markdown}
\usepackage{marginnote}
\markdownSetup{
  renderers = {
    inlineHtmlComment = {\marginnote{#1}},
    blockHtmlCommentBegin = {\begin{quote}},
    blockHtmlCommentEnd = {\end{quote}},
  },
}
\begin{document}
\begin{markdown}
A useful use of inline HTML comments are side notes.
<!-- Side notes are displayed in the horizontal margins next to the relevant
passages, which makes them *easier for the reader to find* than notes. -->

We can render block HTML comments as blockquotes:

<!--
Here is a block HTML comment with a code example that a programmer might understand:

    foo = bar + baz - 42
-->
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following body text:

> A useful use of HTML comments are side notes.
>
> We can render block HTML comments as blockquotes:
> 
> > Here is a block HTML comment with a code example that a programmer might
> > understand:
> >
> >     foo = bar + baz - 42

The horizontal margins should contain the following text:

> Side notes are displayed in the horizontal margins next to the relevant
> passages, which makes them *easier for the reader to find* than notes.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererInlineHtmlComment{%
  \markdownRendererInlineHtmlCommentPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { inlineHtmlComment }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { inlineHtmlComment }
  { 1 }
\ExplSyntaxOff
\def\markdownRendererBlockHtmlCommentBegin{%
  \markdownRendererBlockHtmlCommentBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { blockHtmlCommentBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { blockHtmlCommentBegin }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererBlockHtmlCommentEnd{%
  \markdownRendererBlockHtmlCommentEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { blockHtmlCommentEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { blockHtmlCommentEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### HTML Tag and Element Renderers

The \mdef{markdownRendererInlineHtmlTag} macro represents an opening, closing,
or empty inline \acro{HTML} tag. This macro will only be produced, when the
\Opt{html} option is enabled. The macro receives a single argument that
corresponds to the contents of the \acro{HTML} tag.

The \mdef{markdownRendererInputBlockHtmlElement} macro represents a block
\acro{HTML} element. This macro will only be produced, when the \Opt{html}
option is enabled. The macro receives a single argument that filename of a file
containing the contents of the \acro{HTML} element.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[html]{markdown}
\usepackage{marginnote}
\usepackage{verbatim}
\markdownSetup{
  renderers = {
    inlineHtmlTag = {\textbf{#1}},
    inputBlockHtmlElement = {\verbatiminput{#1}},
  },
}
\begin{document}
\begin{markdown}
<b>_Hello,_ world!</b><br/>

<div>_Hello,_ world!</div>
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following body text:

> **<b>**_Hello,_ world!**</b><br/>**
>
>     <div>_Hello,_ world!</div>

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererInlineHtmlTag{%
  \markdownRendererInlineHtmlTagPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { inlineHtmlTag }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { inlineHtmlTag }
  { 1 }
\ExplSyntaxOff
\def\markdownRendererInputBlockHtmlElement{%
  \markdownRendererInputBlockHtmlElementPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { inputBlockHtmlElement }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { inputBlockHtmlElement }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Image Renderer
The \mdef{markdownRendererImage} macro represents an image. It receives
four arguments: the label, the fully escaped \acro{uri} that can be directly
typeset, the raw \acro{uri} that can be used outside typesetting, and the
title of the link.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begingroup
\catcode`\@=11
\catcode`\%=12
\catcode`\^^A=14
\global\def\markdownRendererImage#1#2#3#4{^^A
  \immediate\write18{^^A
```
``` sh
    if printf '%s' "#3" | grep -q ^http; then
      OUTPUT="$(printf '%s' "#3" | md5sum | cut -d' ' -f1).^^A
              $(printf '%s' "#3" | sed 's/.*[.]//')";
      if ! [ -e "$OUTPUT" ]; then
        wget -O "$OUTPUT" '#3' || rm "$OUTPUT";
        convert "$OUTPUT" png:"$OUTPUT";
      fi;
      printf '%s%%' "$OUTPUT" > \jobname.fetched;
    else
      printf '%s%%' "#3"      > \jobname.fetched;
    fi^^A
```
``` tex
  }^^A
  {^^A
    \everyeof={\noexpand}^^A
    \edef\filename{\@@input"\jobname.fetched" }^^A
    \includegraphics[width=\textwidth]{\filename}^^A
  }^^A
}
\endgroup
\begin{document}
\begin{markdown}
![TUGboat](https://tug.org/tugboat/noword.jpg)
\end{markdown}
\end{document}
``````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex --shell-escape document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following content. This assumes that you use a Unix-like operating system with
Bourne or Bourne again shell as the default shell of the current user. It also
assumes that the `md5sum`, `wget`, and `convert` binaries are installed and
that the \TeX{} engine has shell access.

> ![TUGboat](https://tug.org/tugboat/noword.jpg "The Communications of the TeX Users Group")

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererImage{%
  \markdownRendererImagePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { image }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { image }
  { 4 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Interblock Separator Renderer
The \mdef{markdownRendererInterblockSeparator} macro represents a separator
between two markdown block elements. The macro receives no arguments.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownRendererInterblockSeparator{%
  \par
  {\it(The end of a block)}%
  \par
}
\markdownBegin
Hello *world*!

_Foo_ bar!
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Hello *world*!
>
> *(The end of a block)*
> 
> _Foo_ bar!

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\markdownSetup{
  renderers = {
    interblockSeparator = {%
      \par
      \emph{(The end of a block)}%
      \par
    },
  },
}
\begin{document}
\begin{markdown}
Hello *world*!

_Foo_ bar!
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Hello *world*!
>
> *(The end of a block)*
> 
> _Foo_ bar!

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\def\markdownRendererInterblockSeparator{%
  \par
  \emph{(The end of a block)}%
  \par
}
\starttext
\startmarkdown
Hello *world*!

_Foo_ bar!
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Hello *world*!
>
> *(The end of a block)*
> 
> _Foo_ bar!

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererInterblockSeparator{%
  \markdownRendererInterblockSeparatorPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { interblockSeparator }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { interblockSeparator }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Line Break Renderer
The \mdef{markdownRendererLineBreak} macro represents a forced line break.
The macro receives no arguments.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownRendererLineBreak{%
  \par
  {\it(A forced linebreak)}%
  \par
}
\markdownInput{example.md}
\bye
```````
Using a text editor, create a text document named `example.md` with the
following content.  Note the two spaces at the end of the first line, which
specify a hard linebreak.  Due to the limitations of the \TeX{} input
processor, hard linebreaks would be ignored if we typed them directly into the
`document.tex` document.

<pre><code>Hello world!  <br/>_Foo_ bar!</code></pre>

Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Hello *world*!
>
> *(A forced linebreak)*
> 
> _Foo_ bar!

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\markdownSetup{
  renderers = {
    lineBreak = {%
      \par
      \emph{(A forced linebreak)}%
      \par
    },
  },
}
\begin{document}
\markdownInput{example.md}
\end{document}
```````
Using a text editor, create a text document named `example.md` with the
following content.  Note the two spaces at the end of the first line, which
specify a hard linebreak.  Due to the limitations of the \TeX{} input
processor, hard linebreaks would be ignored if we typed them directly into the
`document.tex` document.

<pre><code>Hello world!  <br/>_Foo_ bar!</code></pre>

Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Hello *world*!
>
> *(A forced linebreak)*
> 
> _Foo_ bar!

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\def\markdownRendererLineBreak{%
  \par
  \emph{(A forced linebreak)}%
  \par
}
\starttext
\markdownInput{example.md}
\stoptext
```````
Using a text editor, create a text document named `example.md` with the
following content.  Note the two spaces at the end of the first line, which
specify a hard linebreak.  Due to the limitations of the \TeX{} input
processor, hard linebreaks would be ignored if we typed them directly into the
`document.tex` document.

<pre><code>Hello world!  <br/>_Foo_ bar!</code></pre>

Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Hello *world*!
>
> *(A forced linebreak)*
> 
> _Foo_ bar!

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererLineBreak{%
  \markdownRendererLineBreakPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { lineBreak }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { lineBreak }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Link Renderer
The \mdef{markdownRendererLink} macro represents a hyperlink. It receives
four arguments: the label, the fully escaped \acro{uri} that can be directly
typeset, the raw \acro{uri} that can be used outside typesetting, and the
title of the link.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownRendererLink#1#2#3#4{%
  #1 {\tt#2} titled {\it#4}%
}
\markdownBegin
Please visit [the link][ctan].

 [ctan]: https://ctan.org/
         (the Comprehensive TeX Archive Network)
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Please visit the link <https://ctan.org/> titled *the Comprehensive TeX
> Archive Network*.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\markdownSetup{
  renderers = {
    link = {%
      #1 \texttt{#2} titled \emph{#4}%
    },
  },
}
\begin{document}
\begin{markdown}
Please visit [the link][ctan].

 [ctan]: https://ctan.org/
         (the Comprehensive TeX Archive Network)
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Please visit the link <https://ctan.org/> titled *the Comprehensive TeX
> Archive Network*.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\def\markdownRendererLink#1#2#3#4{%
  #1 {\tt#2} titled \emph{#4}%
}
\starttext
\startmarkdown
Please visit [the link][ctan].

 [ctan]: https://ctan.org/
         (the Comprehensive TeX Archive Network)
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Please visit the link <https://ctan.org/> titled *the Comprehensive TeX
> Archive Network*.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererLink{%
  \markdownRendererLinkPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { link }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { link }
  { 4 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Markdown Document Renderers
The \mdef{markdownRendererDocumentBegin} and \mdef{markdownRendererDocumentEnd}
macros represent the beginning and the end of a *markdown* document. The macros
receive no arguments.

A \TeX{} document may contain any number of markdown documents. Additionally,
markdown documents may appear not only in a sequence, but several markdown
documents may also be *nested*. Redefinitions of the macros should take this
into account.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `nested.md` with the
following content:
``` md
This is a *nested* markdown document.
```

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[contentBlocks]{markdown}
\markdownSetup{
  renderers = {
    contentBlock = {%
      \markdownInput{#3}%
    },
    documentBegin = {%
      \par
      \emph{(The beginning of a document)}
      \par
      \begingroup
      \markdownSetup{snippet=first-nesting-level}%
    },
    documentEnd = {%
      \endgroup
      \par
      \emph{(The end of a document)}
      \par
    },
  },
}
\markdownSetupSnippet{first-nesting-level}{
  renderers = {
    documentBegin = {
      \par
      \emph{(The beginning of a nested document)}
      \par
      \begingroup
      \markdownSetup{snippet=second-nesting-level-and-below}
    },
  },
}
\markdownSetupSnippet{second-nesting-level-and-below}{
  renderers = {
    documentBegin = {
      \par
      \emph{(The beginning of a nested document)}
      \par
      \begingroup
    },
    documentEnd = {
      \endgroup
      \par
      \emph{(The end of a nested document)}
      \par
    },
  },
}
\begin{document}
\begin{markdown}
Hello *world*!

/nested.md

_Foo_ bar!
\end{markdown}
\begin{markdown}

Bar baz!

\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> *(The beginning of a document)*
>
> Hello *world*!
>
> *(The beginning of a nested document)*
>
> This is a *nested* markdown document.
>
> *(The end of a nested document)*
>
> _Foo_ bar!
>
> *(The end of a document)*
>
> *(The beginning of a document)*
>
> Bar baz!
>
> *(The end of a document)*

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererDocumentBegin{%
  \markdownRendererDocumentBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { documentBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { documentBegin }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererDocumentEnd{%
  \markdownRendererDocumentEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { documentEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { documentEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Non-Breaking Space Renderer
The \mdef{markdownRendererNbsp} macro represents a non-breaking space.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.bib` with the
following content:
``` bib
@book{knuth:tex,
  author    = "Knuth, Donald Ervin",
  title     = "The \TeX book, volume A of Computers and typesetting",
  publisher = "Addison-Wesley",
  year      = "1984"
}
```````
Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[
  citations,
  citationNbsps,
]{markdown}
\markdownSetup{
  renderers = {
    nbsp = {$\cdot$},
  },
}
\begin{document}

\begin{markdown}
The TeXbook [@knuth:tex, p. 123 and 130] is good.
\end{markdown}

\bibliographystyle{plain}
\bibliography{document.bib}

\end{document}
```````
Next, invoke LuaTeX and BibTeX from the terminal:
``` sh
lualatex document.tex
bibtex document.aux
lualatex document.tex
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> The TeXbook [1, p.·123·and·130] is good.
>
> ### References
> [1] Donald Ervin Knuth. _The TeXbook, volume A of Computers and typesetting._
> Addison-Wesley, 1984.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererNbsp{%
  \markdownRendererNbspPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { nbsp }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { nbsp }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Note Renderer
The \mdef{markdownRendererNote} macro represents a note. This macro
will only be produced, when the \Opt{notes} option is enabled. The
macro receives a single argument that corresponds to the note text.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionNotes{true}
\def\markdownRendererNote#1{ (and \lowercase{#1})}
\markdownBegin
This is some text[^1] and this is some other text[^2].

 [^1]: this is a note

 [^2]: this is some other note
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is some text (and this is a note) and this is some other
> text (and this is some other note).

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[notes]{markdown}
\markdownSetup{
  renderers = {
    note = { (and \MakeLowercase{#1})},
  },
}
\begin{document}
\begin{markdown}
This is some text[^1] and this is some other text[^2].

 [^1]: this is a note

 [^2]: this is some other note
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is some text (and this is a note) and this is some other
> text (and this is some other note).

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[notes = yes]
\def\markdownRendererNote#1{ (and \lowercase{#1})}
\starttext
\startmarkdown
This is some text[^1] and this is some other text[^2].

 [^1]: this is a note

 [^2]: this is some other note
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is some text (and this is a note) and this is some other
> text (and this is some other note).

%</manual-tokens>
%<*tex>
% \fi
% \begin{markdown}
%
% The \mdef{markdownRendererFootnote} and
% \mdef{markdownRendererFootnotePrototype} macros have been deprecated
% and will be removed in Markdown 3.0.0.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_new:Npn
  \markdownRendererNote
  {
    \cs_if_exist:NTF
      \markdownRendererFootnote
      {
        \markdownWarning
          {
            Footnote~renderer~has~been~deprecated,~
            to~be~removed~in~Markdown~3.0.0
          }
        \markdownRendererFootnote
      }
      {
        \cs_if_exist:NTF
          \markdownRendererFootnotePrototype
          {
            \markdownWarning
              {
                Footnote~renderer~prototype~has~been~deprecated,~
                to~be~removed~in~Markdown~3.0.0
              }
            \markdownRendererFootnotePrototype
          }
          {
            \markdownRendererNotePrototype
          }
      }
  }
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { footnote }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { footnote }
  { 1 }
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { note }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { note }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Ordered List Renderers
The \mdef{markdownRendererOlBegin} macro represents the beginning of an
ordered list that contains an item with several paragraphs of text (the
list is not tight). This macro will only be produced, when the \Opt{fancyLists}
option is disabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererOlBegin{%
  \markdownRendererOlBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { olBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { olBegin }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererOlBeginTight} macro represents the beginning of an
ordered list that contains no item with several paragraphs of text (the
list is tight). This macro will only be produced, when the \Opt{tightLists}
option is enabled and the \Opt{fancyLists} option is disabled. The macro
receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererOlBeginTight{%
  \markdownRendererOlBeginTightPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { olBeginTight }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { olBeginTight }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererFancyOlBegin} macro represents the beginning of a
fancy ordered list that contains an item with several paragraphs of text (the
list is not tight). This macro will only be produced, when the \Opt{fancyLists}
option is enabled. The macro receives two arguments: the style of the list item
labels (`Decimal`, `LowerRoman`, `UpperRoman`, `LowerAlpha`, and `UpperAlpha`),
and the style of delimiters between list item labels and texts (`Default`,
`OneParen`, and `Period`).

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererFancyOlBegin{%
  \markdownRendererFancyOlBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { fancyOlBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { fancyOlBegin }
  { 2 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererFancyOlBeginTight} macro represents the beginning of
a fancy ordered list that contains no item with several paragraphs of text (the
list is tight). This macro will only be produced, when the \Opt{fancyLists}
and \Opt{tightLists} options are enabled. The macro receives two arguments: the
style of the list item labels, and the style of delimiters between list
item labels and texts. See the \mref{markdownRendererFancyOlBegin} macro for
the valid style values.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererFancyOlBeginTight{%
  \markdownRendererFancyOlBeginTightPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { fancyOlBeginTight }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { fancyOlBeginTight }
  { 2 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererOlItem} macro represents an item in an ordered list.
This macro will only be produced, when the \Opt{startNumber} option is
disabled and the \Opt{fancyLists} option is disabled. The macro receives no
arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererOlItem{%
  \markdownRendererOlItemPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { olItem }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { olItem }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererOlItemEnd} macro represents the end of an item in
an ordered list. This macro will only be produced, when the \Opt{fancyLists}
option is disabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererOlItemEnd{%
  \markdownRendererOlItemEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { olItemEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { olItemEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererOlItemWithNumber} macro represents an item in an
ordered list.  This macro will only be produced, when the \Opt{startNumber}
option is enabled and the \Opt{fancyLists} option is disabled.  The macro
receives a single numeric argument that corresponds to the item number.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererOlItemWithNumber{%
  \markdownRendererOlItemWithNumberPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { olItemWithNumber }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { olItemWithNumber }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererFancyOlItem} macro represents an item in a fancy
ordered list. This macro will only be produced, when the \Opt{startNumber}
option is disabled and the \Opt{fancyLists} option is enabled. The macro receives
no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererFancyOlItem{%
  \markdownRendererFancyOlItemPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { fancyOlItem }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { fancyOlItem }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererFancyOlItemEnd} macro represents the end of an item in
a fancy ordered list. This macro will only be produced, when the \Opt{fancyLists}
option is enabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererFancyOlItemEnd{%
  \markdownRendererFancyOlItemEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { fancyOlItemEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { fancyOlItemEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererFancyOlItemWithNumber} macro represents an item in a
fancy ordered list. This macro will only be produced, when the \Opt{startNumber}
and \Opt{fancyLists} options are enabled. The macro receives a single numeric
argument that corresponds to the item number.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererFancyOlItemWithNumber{%
  \markdownRendererFancyOlItemWithNumberPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { fancyOlItemWithNumber }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { fancyOlItemWithNumber }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererOlEnd} macro represents the end of an ordered list
that contains an item with several paragraphs of text (the list is not
tight). This macro will only be produced, when the \Opt{fancyLists} option is
disabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererOlEnd{%
  \markdownRendererOlEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { olEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { olEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererOlEndTight} macro represents the end of an ordered
list that contains no item with several paragraphs of text (the list is
tight). This macro will only be produced, when the \Opt{tightLists} option is
enabled and the \Opt{fancyLists} option is disabled. The macro receives no
arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererOlEndTight{%
  \markdownRendererOlEndTightPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { olEndTight }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { olEndTight }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererFancyOlEnd} macro represents the end of a fancy
ordered list that contains an item with several paragraphs of text (the list
is not tight). This macro will only be produced, when the \Opt{fancyLists}
option is enabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererFancyOlEnd{%
  \markdownRendererFancyOlEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { fancyOlEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { fancyOlEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererFancyOlEndTight} macro represents the end of a
fancy ordered list that contains no item with several paragraphs of text (the
list is tight). This macro will only be produced, when the \Opt{fancyLists}
and \Opt{tightLists} options are enabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionTightLists{true}
\def\markdownOptionStartNumber{true}

\def\markdownRendererInterblockSeparator{}
\def\markdownRendererOlBeginTight{ (}
\def\markdownRendererOlItemWithNumber#1{%
  \ifnum #1=1\relax
    the first
  \else
    \ifnum #1=2\relax
      , the second
    \else
      , and the third
    \fi
  \fi
}
\def\markdownRendererOlItemEnd{}
\def\markdownRendererOlEndTight{).}

\markdownBegin
This is a tight list

1. item
2. item
3. item
\markdownEnd

\def\markdownRendererInterblockSeparator{%
  :\par
  \def\markdownRendererInterblockSeparator{\par}%
}
\def\markdownRendererOlBegin{}
\def\markdownRendererOlItemWithNumber#1{%
  #1.\kern 0.5em%
  This is the
  \ifnum #1=1\relax
    first
  \else
    \ifnum #1=2\relax
      second
    \else
      third
    \fi
  \fi
}
\def\markdownRendererOlItemEnd{.\par}
\def\markdownRendererOlEnd{}

\markdownBegin
This is a loose list

1. item

2. item

3. item
\markdownEnd

\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is a tight list (the first item, the second item, and the third item).
>
> This is a loose list:
> 
> 1. This is the first item.
> 
> 2. This is the second item.
> 
> 3. This is the third item.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[tightLists, startNumber]{markdown}
\begin{document}

\begin{markdown*}{
  renderers = {
    interblockSeparator = {},
    olBeginTight = { (},
    olItemWithNumber = {%
      \ifnum #1=1\relax
        the first
      \else
        \ifnum #1=2\relax
          , the second
        \else
          , and the third
        \fi
      \fi
    },
    olItemEnd = {},
    olEndTight = {).},
  },  
}
This is a tight list

1. item
2. item
3. item
\end{markdown*}

\begin{markdown*}{
  renderers = {
    interblockSeparator = {%
      :\par
      \def\markdownRendererInterblockSeparator{\par}%
    },
    olBeginTight = {\begin{enumerate}},
    olItemWithNumber = {%
      \item This is the
      \ifnum #1=1\relax
        first
      \else
        \ifnum #1=2\relax
          second
        \else
          third
        \fi
      \fi
    },
    olItemEnd = {.},
    olEnd = {\end{enumerate}},
  },  
}
This is a loose list

1. item

2. item

3. item
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is a tight list (the first item, the second item, and the third item).
>
> This is a loose list:
> 
> 1. This is the first item.
> 
> 2. This is the second item.
> 
> 3. This is the third item.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown
  [
    tightLists = yes,
    startNumber = yes,
  ]
\starttext

\def\markdownRendererInterblockSeparator{}
\def\markdownRendererOlBeginTight{ (}
\def\markdownRendererOlItemWithNumber#1{%
  \ifnum #1=1\relax
    the first
  \else
    \ifnum #1=2\relax
      , the second
    \else
      , and the third
    \fi
  \fi
}
\def\markdownRendererOlItemEnd{}
\def\markdownRendererOlEndTight{).}

\startmarkdown
This is a tight list

1. item
2. item
3. item
\stopmarkdown

\def\markdownRendererInterblockSeparator{%
  :\par
  \def\markdownRendererInterblockSeparator{\par}%
}
\def\markdownRendererOlBegin{\startitemize}
\def\markdownRendererOlItemWithNumber#1{%
  \sym{#1.}
  This is the
  \ifnum #1=1\relax
    first
  \else
    \ifnum #1=2\relax
      second
    \else
      third
    \fi
  \fi
}
\def\markdownRendererOlItemEnd{.\par}
\def\markdownRendererOlEnd{\stopitemize}

\startmarkdown
This is a loose list

1. item

2. item

3. item
\stopmarkdown

\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is a tight list (the first item, the second item, and the third item).
>
> This is a loose list:
> 
> 1. This is the first item.
> 
> 2. This is the second item.
> 
> 3. This is the third item.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererFancyOlEndTight{%
  \markdownRendererFancyOlEndTightPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { fancyOlEndTight }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { fancyOlEndTight }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Parenthesized Citations Renderer
The \mdef{markdownRendererCite} macro represents a string of one or more
parenthetical citations. This macro will only be produced, when the
\Opt{citations} option is enabled. The macro receives the parameter
`{`\meta{number of citations}`}` followed by \meta{suppress author}
`{`\meta{prenote}`}{`\meta{postnote}`}{`\meta{name}`}` repeated
\meta{number of citations} times. The \meta{suppress author} parameter is
either the token `-`, when the author's name is to be suppressed, or `+`
otherwise.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[citations]{markdown}
\newcount\citationsCounter
\newcount\citationsTotal
\makeatletter
\def\citations#1#2#3#4{%
  a parenthesized citation \emph{#4}
  \advance\citationsCounter by 1\relax
  \ifx\relax#2\relax
    \ifx\relax#3\relax\else
      with a postfix \emph{#3}%
    \fi
  \else
    with a prefix \emph{#2}%
    \ifx\relax#3\relax\else
      \ and a postfix \emph{#3}%
    \fi
  \fi
  \ifnum\citationsCounter>\citationsTotal\relax
    .%
    \expandafter\@gobble
  \else
    , and
  \fi\citations}
\makeatother
\markdownSetup{
  renderers = {
    cite = {%
      \citationsCounter=1%
      \citationsTotal=#1%
      This is
      \expandafter\citations
    },
  },
}
\begin{document}
\begin{markdown}
[see @abrahams90, pp. 12; @eijkhout91, pp. 34]
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is a parenthesized citation *abrahams90* with a prefix see
> and a postfix *pp. 12*, and a citation *eijkhout91* with a
> postfix *pp. 34*.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererCite{%
  \markdownRendererCitePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { cite }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { cite }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Raw Content Renderers
The \mdef{markdownRendererInputRawInline} macro represents an inline raw span.
The macro receives two arguments: the filename of a file contaning the inline
raw span contents and the raw attribute that designates the format of the
inline raw span. This macro will only be produced, when the \Opt{rawAttribute}
option is enabled.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererInputRawInline{%
  \markdownRendererInputRawInlinePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { inputRawInline }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { inputRawInline }
  { 2 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererInputRawBlock} macro represents a raw block. The
macro receives two arguments: the filename of a file contaning the raw block
and the raw attribute that designates the format of the raw block. This macro
will only be produced, when the \Opt{rawAttribute} and \Opt{fencedCode} options
are enabled.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
```` tex
\documentclass{article}
\usepackage[rawAttribute, fencedCode]{markdown}
\usepackage{expl3}
\ExplSyntaxOn
\cs_new:Nn
  \display_raw_content:nn
  {
    % If the raw attribute is TeX, execute the content as a TeX document.
    \str_if_eq:nnTF
      { #2 }
      { tex }
      { \markdownEscape { #1 } }
      % Otherwise, ignore the content.
      { }
  }
\markdownSetup{
  renderers = {
    rawInline = { \display_raw_content:nn { #1 } { #2 } },
    rawBlock  = { \display_raw_content:nn { #1 } { #2 } }
  },
}
\ExplSyntaxOff
\begin{document}
\begin{markdown}
`$H_2 O$`{=tex} is a liquid.

``` {=html}
<p>Here is some HTML content that will be ignored.</p>
```
\end{markdown}
\end{document}
````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> H~2~O is a liquid.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererInputRawBlock{%
  \markdownRendererInputRawBlockPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { inputRawBlock }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { inputRawBlock }
  { 2 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Special Character Renderers
The following macros replace any special plain \TeX{} characters, including
% \iffalse
the active pipe character (`|`) of \Hologo{ConTeXt}, in the input text:

- \mdef{markdownRendererAmpersand} replaces the ampersand (`&`).
- \mdef{markdownRendererBackslash} replaces the backslash (`\`).
- \mdef{markdownRendererCircumflex} replaces the circumflex (`^`).
- \mdef{markdownRendererDollarSign} replaces the dollar sign (`$`).
- \mdef{markdownRendererHash} replaces the hash sign (`#`).
- \mdef{markdownRendererLeftBrace} replaces the left brace (`{`).
- \mdef{markdownRendererPercentSign} replaces the percent sign (`%`).
- \mdef{markdownRendererPipe} replaces the pipe character (`|`).
- \mdef{markdownRendererRightBrace} replaces the right brace (`}`).
- \mdef{markdownRendererTilde} replaces the tilde (`~`).
- \mdef{markdownRendererUnderscore} replaces the underscore (`_`).

% \fi
% the active pipe character (`|`) of \Hologo{ConTeXt}, in the input text.
% These macros will only be produced, when the \Opt{hybrid} option is
% `false`.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content. We will make the tilde behave as if it were written in
\TeX{}, where it represents a non-breaking space.
``` tex
\input markdown
\def\markdownRendererTilde{~}
\markdownBegin
Bartel~Leendert van~der~Waerden
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text, where the middot (`·`) denotes a non-breaking space:

> Bartel·Leendert van·der·Waerden

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content. We will make the tilde behave as if it were written in
\TeX{}, where it represents a non-breaking space.
``` tex
\documentclass{article}
\usepackage{markdown}
\markdownSetup{
  renderers = {
    tilde = ~,
  },
}
\begin{document}
\begin{markdown}
Bartel~Leendert van~der~Waerden
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text, where the middot (`·`) denotes a non-breaking space:

> Bartel·Leendert van·der·Waerden

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content. We will make the tilde behave as if it were written in
\TeX{}, where it represents a non-breaking space.
``` tex
\usemodule[t][markdown]
\def\markdownRendererTilde{~}
\starttext
\startmarkdown
Bartel~Leendert van~der~Waerden
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text, where the middot (`·`) denotes a non-breaking space:

> Bartel·Leendert van·der·Waerden

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererLeftBrace{%
  \markdownRendererLeftBracePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { leftBrace }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { leftBrace }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererRightBrace{%
  \markdownRendererRightBracePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { rightBrace }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { rightBrace }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererDollarSign{%
  \markdownRendererDollarSignPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { dollarSign }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { dollarSign }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererPercentSign{%
  \markdownRendererPercentSignPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { percentSign }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { percentSign }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererAmpersand{%
  \markdownRendererAmpersandPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { ampersand }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { ampersand }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererUnderscore{%
  \markdownRendererUnderscorePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { underscore }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { underscore }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererHash{%
  \markdownRendererHashPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { hash }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { hash }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererCircumflex{%
  \markdownRendererCircumflexPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { circumflex }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { circumflex }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererBackslash{%
  \markdownRendererBackslashPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { backslash }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { backslash }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererTilde{%
  \markdownRendererTildePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { tilde }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { tilde }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererPipe{%
  \markdownRendererPipePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { pipe }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { pipe }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Strike-Through Renderer
The \mdef{markdownRendererStrikeThrough} macro represents a strike-through span of
text. The macro receives a single argument that corresponds to the striked-out
span of text. This macro will only be produced, when the \Opt{strikeThrough}
option is enabled.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionStrikeThrough{true}
\input soulutf8.sty
\def\markdownRendererStrikeThrough#1{\st{#1}}
\markdownBegin
This is ~~a lunar roving vehicle~~ strike-through text.
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is ~~a lunar roving vehicle~~ strike-through text.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[strikeThrough]{markdown}
\usepackage{soulutf8}
\markdownSetup{
  renderers = {
    strikeThrough = {\st{#1}},
  },
}
\begin{document}
\begin{markdown}
This is ~~a lunar roving vehicle~~ strike-through text.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is ~~a lunar roving vehicle~~ strike-through text.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[strikeThrough = yes]
\def\markdownRendererStrikeThrough#1{\overstrikes{#1}}
\starttext
\startmarkdown
This is ~~a lunar roving vehicle~~ strike-through text.
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is ~~a lunar roving vehicle~~ strike-through text.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererStrikeThrough{%
  \markdownRendererStrikeThroughPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { strikeThrough }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { strikeThrough }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Subscript Renderer
The \mdef{markdownRendererSubscript} macro represents a subscript span of
text. The macro receives a single argument that corresponds to the subscript
span of text. This macro will only be produced, when the \Opt{subscripts}
option is enabled.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionSubscripts{true}
\def\markdownRendererSubscript#1{ (#1 moles) and }
\markdownBegin
H~2~O is a liquid.
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> H (2 moles) and O is a liquid.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[subscripts]{markdown}
\markdownSetup{
  renderers = {
    subscript = { (#1 moles) and },
  },
}
\begin{document}
\begin{markdown}
H~2~O is a liquid.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> H (2 moles) and O is a liquid.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[subscripts = yes]
\def\markdownRendererSubscript#1{ (#1 moles) and }
\starttext
\startmarkdown
H~2~O is a liquid.
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> H (2 moles) and O is a liquid.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererSubscript{%
  \markdownRendererSubscriptPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { subscript }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { subscript }
  { 1 }
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Superscript Renderer
The \mdef{markdownRendererSuperscript} macro represents a superscript span of
text. The macro receives a single argument that corresponds to the superscript
span of text. This macro will only be produced, when the \Opt{superscripts}
option is enabled.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionSuperscripts{true}
\def\markdownRendererSuperscript#1{ taken to the power of #1}
\markdownBegin
2^10^ is 1024.
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> 2 taken to the power of 10 is 1024.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[superscripts]{markdown}
\markdownSetup{
  renderers = {
    superscript = { taken to the power of #1},
  },
}
\begin{document}
\begin{markdown}
2^10^ is 1024.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> 2 taken to the power of 10 is 1024.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[superscripts = yes]
\def\markdownRendererSuperscript#1{ taken to the power of #1}
\starttext
\startmarkdown
2^10^ is 1024.
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> 2 taken to the power of 10 is 1024.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererSuperscript{%
  \markdownRendererSuperscriptPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { superscript }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { superscript }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Table Renderer
The \mdef{markdownRendererTable} macro represents a table. This macro will only
be produced, when the \Opt{pipeTables} option is enabled. The macro receives the
parameters `{`\meta{caption}`}{`\meta{number of rows}`}{`\meta{number of columns}`}`
followed by `{`\meta{alignments}`}` and then by `{`\meta{row}`}` repeated
\meta{number of rows} times, where \meta{row} is `{`\meta{column}`}` repeated
\meta{number of columns} times, \meta{alignments} is \meta{alignment} repeated
\meta{number of columns} times, and \meta{alignment} is one of the following:

- `d` -- The corresponding column has an unspecified (default) alignment.
- `l` -- The corresponding column is left-aligned.
- `c` -- The corresponding column is centered.
- `r` -- The corresponding column is right-aligned.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[pipeTables, tableCaptions]{markdown}
\newcount\rowCounter
\newcount\columnCounter
\makeatletter
\def\processRow#1{%
  \columnCounter=1%
  \ifnum\rowCounter=0\relax
    As for the alignment,
  \else
    In row \the\rowCounter,
  \fi
  \processColumn#1
  \advance\rowCounter by 1\relax
  \ifnum\rowCounter>\rowTotal\relax
    \expandafter\@gobble
  \fi\processRow}%
\def\processColumn#1{%
  column number \the\columnCounter{}
  \ifnum\rowCounter=0\relax
    \if#1d{}has default alignment\fi
    \if#1l{}is left-aligned\fi
    \if#1c{}is centered\fi
    \if#1r{}is right-aligned\fi
  \else
    says \emph{#1}%
  \fi
  \advance\columnCounter by 1\relax
  \ifnum\columnCounter<\columnTotal\relax, \fi
  \ifnum\columnCounter=\columnTotal\relax, and \fi
  \ifnum\columnCounter>\columnTotal\relax
    .\expandafter\@gobble
  \fi\processColumn}%
\makeatother
\markdownSetup{
  renderers = {
    table = {%
      This is a table with caption \emph{#1} that is #3 colums wide
      and #2 rows long.
      \rowCounter=0%
      \def\rowTotal{#2}%
      \def\columnTotal{#3}%
      \processRow
    },
  },
}
\begin{document}
\begin{markdown}
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

  : Demonstration of pipe table syntax
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is a table with caption *Demonstration of pipe table syntax* that is 4
> colums wide and 4 rows long. As for the alignment, column number 1 is
> right-aligned, column number 2 is left-aligned, column number 3 has default
> alignment, and column number 4 is centered. In row 1, column number 1 says
> *Right*, column number 2 says *Left*, column number 3 says *Default*, and
> column number 4 says *Center*. In row 2, column number 1 says *12*, column
> number 2 says *12*, column number 3 says *12*, and column number 4 says *12*.
> In row 3, column number 1 says *123*, column number 2 says *123*, column
> number 3 says *123*, and column number 4 says *123*. In row 4, column number
> 1 says *1*, column number 2 says *1*, column number 3 says *1*, and column
> number 4 says *1*.


%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererTable{%
  \markdownRendererTablePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { table }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { table }
  { 3 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Text Citations Renderer
The \mdef{markdownRendererTextCite} macro represents a string of one or more
text citations. This macro will only be produced, when the
\Opt{citations} option is enabled. The macro receives parameters in the same 
format as the \mref{markdownRendererCite} macro.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[citations]{markdown}
\newcount\citationsCounter
\newcount\citationsTotal
\makeatletter
\def\citations#1#2#3#4{%
  a text citation \emph{#4}
  \advance\citationsCounter by 1\relax
  \ifx\relax#2\relax
    \ifx\relax#3\relax\else
      with a postfix \emph{#3}%
    \fi
  \else
    with a prefix \emph{#2}%
    \ifx\relax#3\relax\else
      \ and a postfix \emph{#3}%
    \fi
  \fi
  \ifnum\citationsCounter>\citationsTotal\relax
    .%
    \expandafter\@gobble
  \else
    , and
  \fi\citations}
\makeatother
\markdownSetup{
  renderers = {
    textCite = {%
      \citationsCounter=1%
      \citationsTotal=#1%
      This is
      \expandafter\citations
    },
  },
}
\begin{document}
\begin{markdown}
@abrahams90 [pp. 12; also @eijkhout91]
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is a text citation *abrahams90* with a postfix *pp. 12*,
> and a citation *eijkhout91* with a prefix *also*.

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererTextCite{%
  \markdownRendererTextCitePrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { textCite }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { textCite }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Thematic Break Renderer
The \mdef{markdownRendererThematicBreak} macro represents a thematic break.
The macro receives no arguments.

% \end{markdown}
%
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownRendererThematicBreak{\vfil\break}
\markdownBegin
This is the first page.

***

This is the second page.
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is the first page.
>
> ***
>
> This is the second page.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\markdownSetup{
  renderers = {
    thematicBreak = \newpage,
  },
}
\begin{document}
\begin{markdown}
This is the first page.

***

This is the second page.
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is the first page.
>
> ***
>
> This is the second page.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\def\markdownRendererThematicBreak{\page[yes]}
\starttext
\startmarkdown
This is the first page.

***

This is the second page.
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> This is the first page.
>
> ***
>
> This is the second page.

%</manual-tokens>
%<*tex>
% \fi
% \begin{markdown}
%
% The \mdef{markdownRendererHorizontalRule} and
% \mdef{markdownRendererHorizontalRulePrototype} macros have been deprecated
% and will be removed in Markdown 3.0.0.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_new:Npn
  \markdownRendererThematicBreak
  {
    \cs_if_exist:NTF
      \markdownRendererHorizontalRule
      {
        \markdownWarning
          {
            Horizontal~rule~renderer~has~been~deprecated,~
            to~be~removed~in~Markdown~3.0.0
          }
        \markdownRendererHorizontalRule
      }
      {
        \cs_if_exist:NTF
          \markdownRendererHorizontalRulePrototype
          {
            \markdownWarning
              {
                Horizontal~rule~renderer~prototype~has~been~deprecated,~
                to~be~removed~in~Markdown~3.0.0
              }
            \markdownRendererHorizontalRulePrototype
          }
          {
            \markdownRendererThematicBreakPrototype
          }
      }
  }
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { horizontalRule }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { horizontalRule }
  { 0 }
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { thematicBreak }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { thematicBreak }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### Tickbox Renderers
The macros named \mdef{markdownRendererTickedBox},
\mdef{markdownRendererHalfTickedBox}, and \mdef{markdownRendererUntickedBox}
represent ticked and unticked boxes, respectively. These macros will either be
produced, when the \Opt{taskLists} option is enabled, or when the Ballot Box
with X (☒, U+2612), Hourglass (⌛, U+231B) or Ballot Box (☐, U+2610) Unicode
characters are encountered in the markdown input, respectively.

% \end{markdown}
%
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[taskLists]{markdown}
\markdownSetup{
  renderers = {
    untickedBox = No,
    tickedBox = Yes,
  },
}
\begin{document}
\begin{markdown}
- [ ] you can't.
- [x] I can!
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> - No you can't.
> - Yes I can!

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[taskLists = yes]
\def\markdownRendererUntickedBox{No}
\def\markdownRendererTickedBox{Yes}
\starttext
\startmarkdown
- [ ] you can't.
- [x] I can!
\stopmarkdown
\stoptext
````````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
`````
A PDF document named `document.pdf` should be produced and contain the
following text:

> - No you can't.
> - Yes I can!

%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererTickedBox{%
  \markdownRendererTickedBoxPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { tickedBox }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { tickedBox }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererHalfTickedBox{%
  \markdownRendererHalfTickedBoxPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { halfTickedBox }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { halfTickedBox }
  { 0 }
\ExplSyntaxOff
\def\markdownRendererUntickedBox{%
  \markdownRendererUntickedBoxPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { untickedBox }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { untickedBox }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

#### YAML Metadata Renderers {#yamlmetadatarenderers}

The \mdef{markdownRendererJekyllDataBegin} macro represents the beginning of a
\acro{yaml} document. This macro will only be produced when the \Opt{jekyllData}
option is enabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererJekyllDataBegin{%
  \markdownRendererJekyllDataBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { jekyllDataBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { jekyllDataBegin }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererJekyllDataEnd} macro represents the end of a
\acro{yaml} document. This macro will only be produced when the
\Opt{jekyllData} option is enabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererJekyllDataEnd{%
  \markdownRendererJekyllDataEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { jekyllDataEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { jekyllDataEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererJekyllDataMappingBegin} macro represents the
beginning of a mapping in a \acro{yaml} document. This macro will only be
produced when the \Opt{jekyllData} option is enabled. The macro receives two
arguments: the scalar key in the parent structure, cast to a string following
\acro{yaml} serialization rules, and the number of items in the mapping.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererJekyllDataMappingBegin{%
  \markdownRendererJekyllDataMappingBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { jekyllDataMappingBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { jekyllDataMappingBegin }
  { 2 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererJekyllDataMappingEnd} macro represents the
end of a mapping in a \acro{yaml} document. This macro will only be produced
when the \Opt{jekyllData} option is enabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererJekyllDataMappingEnd{%
  \markdownRendererJekyllDataMappingEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { jekyllDataMappingEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { jekyllDataMappingEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererJekyllDataSequenceBegin} macro represents the
beginning of a sequence in a \acro{yaml} document. This macro will only be
produced when the \Opt{jekyllData} option is enabled. The macro receives two
arguments: the scalar key in the parent structure, cast to a string following
\acro{yaml} serialization rules, and the number of items in the sequence.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererJekyllDataSequenceBegin{%
  \markdownRendererJekyllDataSequenceBeginPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { jekyllDataSequenceBegin }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { jekyllDataSequenceBegin }
  { 2 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererJekyllDataSequenceEnd} macro represents the
end of a sequence in a \acro{yaml} document. This macro will only be produced
when the \Opt{jekyllData} option is enabled. The macro receives no arguments.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererJekyllDataSequenceEnd{%
  \markdownRendererJekyllDataSequenceEndPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { jekyllDataSequenceEnd }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { jekyllDataSequenceEnd }
  { 0 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererJekyllDataBoolean} macro represents a boolean scalar
value in a \acro{yaml} document. This macro will only be produced when the
\Opt{jekyllData} option is enabled. The macro receives two arguments: the
scalar key in the parent structure, and the scalar value, both cast to a string
following \acro{yaml} serialization rules.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererJekyllDataBoolean{%
  \markdownRendererJekyllDataBooleanPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { jekyllDataBoolean }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { jekyllDataBoolean }
  { 2 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererJekyllDataNumber} macro represents a numeric scalar
value in a \acro{yaml} document. This macro will only be produced when the
\Opt{jekyllData} option is enabled. The macro receives two arguments: the
scalar key in the parent structure, and the scalar value, both cast to a string
following \acro{yaml} serialization rules.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererJekyllDataNumber{%
  \markdownRendererJekyllDataNumberPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { jekyllDataNumber }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { jekyllDataNumber }
  { 2 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererJekyllDataString} macro represents a string scalar
value in a \acro{yaml} document. This macro will only be produced when the
\Opt{jekyllData} option is enabled. The macro receives two arguments: the
scalar key in the parent structure, cast to a string following \acro{yaml}
serialization rules, and the scalar value.

% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererJekyllDataString{%
  \markdownRendererJekyllDataStringPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { jekyllDataString }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { jekyllDataString }
  { 2 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>
% \fi
%
% \begin{markdown}

The \mdef{markdownRendererJekyllDataEmpty} macro represents an empty scalar
value in a \acro{yaml} document. This macro will only be produced when the
\Opt{jekyllData} option is enabled. The macro receives one argument: the
scalar key in the parent structure, cast to a string following \acro{yaml}
serialization rules.

% See also Section <#sec:expl3yamlmetadata> for the description of the
% high-level expl3 interface that you can also use to react to \acro{yaml}
% metadata.
%
% \end{markdown}
%
% \iffalse
%</manual-tokens>
%<*tex>
% \fi
%
%  \begin{macrocode}
\def\markdownRendererJekyllDataEmpty{%
  \markdownRendererJekyllDataEmptyPrototype}%
\ExplSyntaxOn
\seq_gput_right:Nn
  \g_@@_renderers_seq
  { jekyllDataEmpty }
\prop_gput:Nnn
  \g_@@_renderer_arities_prop
  { jekyllDataEmpty }
  { 1 }
\ExplSyntaxOff
%    \end{macrocode}
% \par
%
% \iffalse
%</tex>
%<*manual-tokens>

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionJekyllData{true}
\def\markdownRendererJekyllDataString#1#2{\gdef\name{#2}}
\def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}}
\def\markdownRendererJekyllDataEnd{%
  \name{} is \age{} years old.}
\markdownBegin
---
name: Jane Doe
age:  99
---
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Jane Doe is 99 years old.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[jekyllData]{markdown}
\markdownSetup{
  renderers = {
    jekyllDataString = {\gdef\name{#2}},
    jekyllDataNumber = {\gdef\age{#2}},
    jekyllDataEnd = {\name{} is \age{} years old.},
  }
}
\begin{document}

\begin{markdown}
---
name: Jane Doe
age:  99
---
\end{markdown}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Jane Doe is 99 years old.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[jekyllData = yes]
\def\markdownRendererJekyllDataString#1#2{\gdef\name{#2}}
\def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}}
\def\markdownRendererJekyllDataEnd{%
  \name{} is \age{} years old.}
\starttext

\startmarkdown
---
name: Jane Doe
age:  99
---
\stopmarkdown

\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Jane Doe is 99 years old.

% \fi
%
% \begin{markdown}

### Token Renderer Prototypes {#texrendererprototypes}

% \end{markdown}
% \iffalse

By default, token renderers point to package-defined \TeX{} macros, further
referred to as *prototypes*, which provide useful default definitions.

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownRendererTildePrototype{%
  Packages can specify token renderer prototypes.%
}
\markdownBegin
~
\markdownEnd

\def\markdownRendererTilde{%
  User-defined token renderers take precedence.%
}
\markdownBegin
~
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Packages can specify token renderer prototypes.
>
> User-defined token renderers take precedence.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\markdownSetup{
  rendererPrototypes = {
    tilde = {Packages can specify token renderer prototypes.},
  },
}
\begin{document}
\begin{markdown}
~
\end{markdown}

\begin{markdown*}{
  renderers = {
    tilde = {User-defined token renderers take precedence.},
  },
}
~
\end{markdown*}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Packages can specify token renderer prototypes.
>
> User-defined token renderers take precedence.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\def\markdownRendererTildePrototype{%
  Packages can specify token renderer prototypes.%
}
\starttext
\startmarkdown
~
\stopmarkdown

\def\markdownRendererTilde{%
  User-defined token renderers take precedence.%
}
\startmarkdown
~
\stopmarkdown
\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Packages can specify token renderer prototypes.
>
> User-defined token renderers take precedence.

% \fi
%
% \begin{markdown}

#### YAML Metadata Renderer Prototypes {#expl3yamlmetadata}

By default, the renderer prototypes for YAML metadata provide a high-level
interface that can be programmed using the `markdown/jekyllData` key--values
from the l3keys module of the \LaTeX{}3 kernel.

% \end{markdown}
% \iffalse

##### Plain \TeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\input markdown
\def\markdownOptionJekyllData{true}
\ExplSyntaxOn
\keys_define:nn
  { markdown/jekyllData }
  {
    name .code:n = { \gdef\name{#1} },
    age  .code:n = { \gdef\age{#1}  },
  }
\ExplSyntaxOff
\def\markdownRendererJekyllDataEnd{%
  \name{} is \age{} years old.}
\markdownBegin
---
name: Jane Doe
age:  99
---
\markdownEnd
\bye
```````
Next, invoke LuaTeX from the terminal:
``` sh
luatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Jane Doe is 99 years old.

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[jekyllData]{markdown}
\markdownSetup{
  jekyllDataRenderers = {
    name = {\gdef\name{#1}},
    code = {\gdef\age{#1}},
  },
  renderers = {
    jekyllDataEnd = {\name{} is \age{} years old.},
  }
}
\begin{document}

\begin{markdown}
---
name: Jane Doe
age:  99
---
\end{markdown}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Jane Doe is 99 years old.

##### \Hologo{ConTeXt} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\setupmarkdown[jekyllData = yes]
\ExplSyntaxOn
\keys_define:nn
  { markdown/jekyllData }
  {
    name .code:n = { \gdef\name{#1} },
    age  .code:n = { \gdef\age{#1}  },
  }
\ExplSyntaxOff
\def\markdownRendererJekyllDataEnd{%
  \name{} is \age{} years old.}
\starttext

\startmarkdown
---
name: Jane Doe
age:  99
---
\stopmarkdown

\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> Jane Doe is 99 years old.

%</manual-tokens>
%<*tex>
% \fi
%  \begin{macrocode}
\ExplSyntaxOn
\keys_define:nn
  { markdown/jekyllData }
  { }
\ExplSyntaxOff
%    \end{macrocode}
% \begin{markdown}
%
% The following \TeX{} macros provide definitions for the token renderers (see
% Section <#sec:texrenderersuser>) that have not been redefined by the
% user. These macros are intended to be redefined by macro package authors
% who wish to provide sensible default token renderers. They are also redefined
% by the \LaTeX{} and \Hologo{ConTeXt} implementations (see sections
% <#sec:lateximplementation> and <#sec:contextimplementation>).
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_new:Nn \@@_plaintex_define_renderer_prototypes:
  {
    \seq_map_function:NN
      \g_@@_renderers_seq
      \@@_plaintex_define_renderer_prototype:n
    \let\markdownRendererBlockHtmlCommentBeginPrototype=\iffalse
    \let\markdownRendererBlockHtmlCommentBegin=\iffalse
    \let\markdownRendererBlockHtmlCommentEndPrototype=\fi
    \let\markdownRendererBlockHtmlCommentEnd=\fi
%    \end{macrocode}
% \begin{markdown}
%
% The \mref{markdownRendererFootnote} and
% \mref{markdownRendererFootnotePrototype} macros have been deprecated
% and will be removed in Markdown 3.0.0.
%
% \end{markdown}
%  \begin{macrocode}
    \cs_undefine:N \markdownRendererFootnote
    \cs_undefine:N \markdownRendererFootnotePrototype
%    \end{macrocode}
% \begin{markdown}
%
% The \mref{markdownRendererHorizontalRule} and
% \mref{markdownRendererHorizontalRulePrototype} macros have been deprecated
% and will be removed in Markdown 3.0.0.
%
% \end{markdown}
%  \begin{macrocode}
    \cs_undefine:N \markdownRendererHorizontalRule
    \cs_undefine:N \markdownRendererHorizontalRulePrototype
  }
\cs_new:Nn \@@_plaintex_define_renderer_prototype:n
  {
    \@@_renderer_prototype_tl_to_csname:nN
      { #1 }
      \l_tmpa_tl
    \prop_get:NnN
      \g_@@_renderer_arities_prop
      { #1 }
      \l_tmpb_tl
    \@@_plaintex_define_renderer_prototype:cV
      { \l_tmpa_tl }
      \l_tmpb_tl
  }
\cs_new:Nn \@@_renderer_prototype_tl_to_csname:nN
  {
    \tl_set:Nn
      \l_tmpa_tl
      { \str_uppercase:n { #1 } }
    \tl_set:Nx
      #2
      {
        markdownRenderer
        \tl_head:f { \l_tmpa_tl }
        \tl_tail:n { #1 }
        Prototype
      }
  }
\cs_new:Nn \@@_plaintex_define_renderer_prototype:Nn
  {
    \cs_generate_from_arg_count:NNnn
      #1
      \cs_set:Npn
      { #2 }
      { }
  }
\cs_generate_variant:Nn
  \@@_plaintex_define_renderer_prototype:Nn
  { cV }
\@@_plaintex_define_renderer_prototypes:
\ExplSyntaxOff
%    \end{macrocode}
% \par
% \begin{markdown}
% 
%### Logging Facilities
% The \mdef{markdownInfo}, \mdef{markdownWarning}, and \mdef{markdownError}
% macros perform logging for the Markdown package. Their first argument
% specifies the text of the info, warning, or error message.
% The \mref{markdownError} macro receives a second argument that provides a help
% text. You may redefine these macros to redirect and process the info,
% warning, and error messages.
%
%### Miscellanea
% The \mdef{markdownMakeOther} macro is used by the package, when a \TeX{}
% engine that does not support direct Lua access is starting to buffer a text.
% The plain \TeX{} implementation changes the category code of plain \TeX{}
% special characters to other, but there may be other active characters that
% may break the output. This macro should temporarily change the category of
% these to *other*.
%
% \end{markdown}
%  \begin{macrocode}
\let\markdownMakeOther\relax
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \mdef{markdownReadAndConvert} macro implements the \mref{markdownBegin}
% macro. The first argument specifies the token sequence that will terminate
% the markdown input (\mref{markdownEnd} in the instance of the \mref{markdownBegin}
% macro) when the plain \TeX{} special characters have had their category
% changed to *other*. The second argument specifies the token sequence
% that will actually be inserted into the document, when the ending token
% sequence has been found.
%
% \end{markdown}
%  \begin{macrocode}
\let\markdownReadAndConvert\relax
\begingroup
%    \end{macrocode}
% \begin{markdown}
% Locally swap the category code of the backslash symbol (`\`) with the pipe
% symbol (`|`). This is required in order that all the special symbols in the
% first argument of the `markdownReadAndConvert` macro have the category code
% *other*.
%
% \end{markdown}
%  \begin{macrocode}
  \catcode`\|=0\catcode`\\=12%
  |gdef|markdownBegin{%
    |markdownReadAndConvert{\markdownEnd}%
                           {|markdownEnd}}%
|endgroup
%    \end{macrocode}
% \begin{markdown}
% The macro is exposed in the interface, so that the user can create their own
% markdown environments. Due to the way the arguments are passed to Lua (see
% Section <#sec:directlua>), the first argument may not contain the
% string `]]` (regardless of the category code of the bracket symbol (`]`)).
%
% The \mdef{markdownMode} macro specifies how the plain \TeX{} implementation
% interfaces with the Lua interface. The valid values and their meaning are
% as follows:
%
% - `0` – Shell escape via the 18 output file stream
% - `1` – Shell escape via the Lua `os.execute` method
% - `2` – Direct Lua access
% - `3` – The \pkg{lt3luabridge} Lua package
%
% By defining the macro, the user can coerce the package to use a specific mode.
% If the user does not define the macro prior to loading the plain \TeX{}
% implementation, the correct value will be automatically detected. The outcome
% of changing the value of \mref{markdownMode} after the implementation has been
% loaded is undefined.
%
% The \mref{markdownMode} macro has been deprecated and will be removed in
% Markdown 3.0.0. The code that corresponds to \mref{markdownMode} value of `3`
% will be the only implementation.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_if_exist:NF
  \markdownMode
  {
    \file_if_exist:nTF
      { lt3luabridge.tex }
      {
        \cs_new:Npn
          \markdownMode
          { 3 }
      }
      {
        \cs_if_exist:NTF
          \directlua
          {
            \cs_new:Npn
              \markdownMode
              { 2 }
          }
          {
            \cs_new:Npn
              \markdownMode
              { 0 }
          }
      }
  }
\ExplSyntaxOff
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \mdef{markdownLuaRegisterIBCallback} and
% \mdef{markdownLuaUnregisterIBCallback} macros have been deprecated and will
% be removed in Markdown 3.0.0:
%
% \end{markdown}
%  \begin{macrocode}
\def\markdownLuaRegisterIBCallback#1{\relax}%
\def\markdownLuaUnregisterIBCallback#1{\relax}%
%    \end{macrocode}
% \iffalse
%</tex>
% \fi
% \par
% \begin{markdown}
%
% \LaTeX{} Interface {#latexinterface}
%--------------------
%
% \end{markdown}
% \iffalse
%<*manual-interfaces>

### \LaTeX{}

The \LaTeX{} interface provides the same level of functionality as the plain
\TeX{} interface by using the plain \TeX{} interface behind the scenes. Unlike
the plain \TeX{} interface, the \LaTeX{} interface uses familiar \LaTeX{}
idioms, such as package options and environments.

The \LaTeX{} interface accepts the same options as the plain \TeX{} interface,
but now the options are specified as \meta{key}${}={}$\meta{value} pairs and
they are passed either as package options, in the \mref{markdownSetup} command, or
as parameters for the \envmref{markdown*} \LaTeX{} environment.

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage{markdown}
\begin{document}

\begin{markdown}
$\sqrt{-1}$ *equals* $i$
\end{markdown}

\begin{markdown*}{hybrid}
$\sqrt{-1}$ *equals* $i$
\end{markdown*}

\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt{-1}\$ *equals* \$i\$.
> 
> √-̅1̅ *equals* $i$.

Invoking pdfTeX should have the same effect:
``` sh
pdflatex --shell-escape document.tex
``````

%</manual-interfaces>
%<*latex>
% \fi
% \begin{markdown}
%
% The \LaTeX{} interface provides \LaTeX{} environments for the typesetting of
% markdown input from within \LaTeX{}, facilities for setting Lua, plain \TeX,
% and \LaTeX{} options used during the conversion from markdown to plain
% \TeX{}, and facilities for changing the way markdown tokens are rendered. The
% rest of the interface is inherited from the plain \TeX{} interface (see
% Section <#sec:texinterface>).
%
% The \LaTeX{} implementation redefines the plain \TeX{} logging macros (see
% Section <#sec:texinterfacelogging>) to use the \LaTeX{} `\PackageInfo`,
% `\PackageWarning`, and `\PackageError` macros.
%
% \end{markdown}
%  \begin{macrocode}
\newcommand\markdownInfo[1]{\PackageInfo{markdown}{#1}}%
\newcommand\markdownWarning[1]{\PackageWarning{markdown}{#1}}%
\newcommand\markdownError[2]{\PackageError{markdown}{#1}{#2.}}%
\input markdown/markdown
%    \end{macrocode}
% \begin{markdown}
%
% The \LaTeX{} interface is implemented by the `markdown.sty` file, which
% can be loaded from the \LaTeX{} document preamble as follows:
% \end{markdown}
% \begin{Verbatim}[commandchars=\\\{\},gobble=2]
% \textbackslash{}usepackage[\textrm{\meta{options}}]\{markdown\}
% \end{Verbatim}
% \begin{markdown}
% where \meta{options} are the \LaTeX{} interface options (see Section
% <#sec:latexoptions>). Note that \meta{options} inside the `\usepackage`
% macro may not set the `markdownRenderers` (see Section
% <#sec:latexrenderers>) and `markdownRendererPrototypes` (see Section
% <#sec:latexrendererprototypes>) keys. This limitation is due to the way
% \Hologo{LaTeX2e} parses package options.
%
% \end{markdown}
% \par
% \begin{markdown}
%
%### Typesetting Markdown
% The interface exposes the \envmdef{markdown} and \envmdef{markdown*}
% \LaTeX{} environments, and redefines the \mref{markdownInput} command.
%
% The \envmref{markdown} and \envmref{markdown*} \LaTeX{} environments are used to
% typeset markdown document fragments. The starred version of the
% \envmref{markdown} environment accepts \LaTeX{} interface options (see
% Section <#sec:latexoptions>) as its only argument. These options will
% only influence this markdown document fragment.
%
% \end{markdown}
%  \begin{macrocode}
\newenvironment{markdown}\relax\relax
\newenvironment{markdown*}[1]\relax\relax
%    \end{macrocode}
% \markdownBegin
%
% You may prepend your own code to the \mdef{markdown} macro and append your own
% code to the \mdef{endmarkdown} macro to produce special effects before and after
% the \envmref{markdown} \LaTeX{} environment (and likewise for the starred
% version).
%
% Note that the \envmref{markdown} and \envmref{markdown*} \LaTeX{} environments are
% subject to the same limitations as the \mref{markdownBegin} and \mref{markdownEnd}
% macros exposed by the plain \TeX{} interface.
%
% The following example \LaTeX{} code showcases the usage of the
% \envmref{markdown} and \envmref{markdown*} environments:
% ``` tex
% \documentclass{article}            \documentclass{article}
% \usepackage{markdown}              \usepackage{markdown}
% \begin{document}                   \begin{document}
% \% ...                              \% ...
% \begin{markdown}                   \begin{markdown*}{smartEllipses}
% _Hello_ **world** ...              _Hello_ **world** ...
% \end{markdown}                     \end{markdown*}
% \% ...                              \% ...
% \end{document}                     \end{document}
% ```````
%
% The \mref{markdownInput} macro accepts a single mandatory parameter containing
% the filename of a markdown document and expands to the result of the
% conversion of the input markdown document to plain \TeX{}.  Unlike the
% \mref{markdownInput} macro provided by the plain \TeX{} interface, this macro
% also accepts \LaTeX{} interface options (see Section <#sec:latexoptions>)
% as its optional argument. These options will only influnce this markdown
% document.
%
% The following example \LaTeX{} code showcases the usage of the
% \mref{markdownInput} macro:
% ``` tex
% \documentclass{article}
% \usepackage{markdown}
% \begin{document}
% % ...
% \markdownInput[smartEllipses]{hello.md}
% % ...
% \end{document}
% ```````
%
%### Options {#latexoptions}
%
% The \LaTeX{} options are represented by a comma-delimited list of
% \meta{key}`=`\meta{value} pairs. For boolean options, the `=`\meta{value}
% part is optional, and \meta{key} will be interpreted as \meta{key}`=true`
% if the `=`\meta{value} part has been omitted.
%
% Except for the `plain` option described in Section <#sec:latexplain>, and
% the \LaTeX{} themes described in Section <#sec:latexthemes>, and the
% \LaTeX{} setup snippets described in Section <#sec:latexsetupsnippets>,
% \LaTeX{} options map directly to the options recognized by the plain
% \TeX{} interface (see Section <#sec:texoptions>) and to the markdown token
% renderers and their prototypes recognized by the plain \TeX{} interface (see
% Sections <#sec:texrenderersuser> and <#sec:texrendererprototypes>).
%
% The \LaTeX{} options may be specified when loading the \LaTeX{} package, when
% using the \envmref{markdown*} \LaTeX{} environment or the \mref{markdownInput}
% macro (see Section <#sec:latexinterface>), or via the \mdef{markdownSetup}
% macro. The \mref{markdownSetup} macro receives the options to set up as its only
% argument:
%
% \markdownEnd
%  \begin{macrocode}
\ExplSyntaxOn
\cs_new:Nn
  \@@_setup:n
  {
    \keys_set:nn
      { markdown/latex-options }
      { #1 }
  }
\let\markdownSetup=\@@_setup:n
\ExplSyntaxOff
%    \end{macrocode}
% \begin{markdown}
%
% We may also store \LaTeX{} options as *setup snippets* and invoke them later
% using the \mdef{markdownSetupSnippet} macro. The \mref{markdownSetupSnippet}
% macro receives two arguments: the name of the setup snippet and the options
% to store:
%
% \end{markdown}
%  \begin{macrocode}
\newcommand\markdownSetupSnippet[2]{%
  \markdownIfSnippetExists{#1}%
    {%
      \markdownWarning
        {Redefined setup snippet \markdownLaTeXThemeName#1}%
      \csname markdownLaTeXSetupSnippet%
        \markdownLaTeXThemeName#1\endcsname={#2}%
    }{%
      \newtoks\next
        \next={#2}%
      \expandafter\let\csname markdownLaTeXSetupSnippet%
        \markdownLaTeXThemeName#1\endcsname=\next
    }}%
%    \end{macrocode}
% \begin{markdown}
%
% To decide whether a setup snippet exists, we can use the
% \mdef{markdownIfSnippetExists} macro:
%
% \end{markdown}
%  \begin{macrocode}
\newcommand\markdownIfSnippetExists[3]{%
  \@ifundefined
    {markdownLaTeXSetupSnippet\markdownLaTeXThemeName#1}%
    {#3}{#2}}%
%    \end{macrocode}
% \begin{markdown}
%
% See Section <#sec:latexthemes> for information on interactions between
% setup snippets and \LaTeX{} themes. See Section <#sec:latexsetupsnippets>
% for information about invoking the stored setup snippets.
%
% \end{markdown}
% \iffalse
%</latex>
%<*manual-options>

### \LaTeX{}

\LaTeX{} options allow us to disable the redefinition of the default renderer
prototypes from plain \TeX{}, load user-defined themes, and invoke user-defined
setup snippets.

#### Setting Lua and plain \TeX{} options from \LaTeX{}

As a rule of thumb, we can set all Lua options directly from \LaTeX{}. For
example, to set the \Opt{taskLists} Lua option to `true`, we would include the
following code in our \LaTeX{} document:

``` tex
\markdownSetup{
  taskLists = true,
}
```

We can also set all plain \TeX{} options directly from \LaTeX{}. For example,
to set the `\markdownOptionHelperScriptFileName` plain \TeX{} option to
`helper-script.lua`, we would inclde the following code in our \LaTeX{}
document:

``` tex
\markdownSetup{
  helperScriptFileName = helper-script.lua,
}
```

%</manual-options>
%<*latex>
% \fi
% \par
% \begin{markdown}
%
% To enable the enumeration of \LaTeX{} options, we will maintain the
% \mdef{g_\@\@_latex_options_seq} sequence.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\seq_new:N \g_@@_latex_options_seq
%    \end{macrocode}
% \begin{markdown}
%
% To enable the reflection of default \LaTeX{} options and their types, we
% will maintain the \mdef{g_\@\@_default_latex_options_prop} and
% \mdef{g_\@\@_latex_option_types_prop} property lists, respectively.
%
% \end{markdown}
%  \begin{macrocode}
\prop_new:N \g_@@_latex_option_types_prop
\prop_new:N \g_@@_default_latex_options_prop
\tl_const:Nn \c_@@_option_layer_latex_tl { latex }
\seq_gput_right:NV \g_@@_option_layers_seq \c_@@_option_layer_latex_tl
\cs_new:Nn
  \@@_add_latex_option:nnn
  {
    \@@_add_option:Vnnn
      \c_@@_option_layer_latex_tl
      { #1 }
      { #2 }
      { #3 }
  }
%    \end{macrocode}
% \iffalse
%</latex>
%<*manual-options>
% \fi
% \begin{markdown}

#### No default token renderer prototypes {#latexplain}

Default token renderer prototypes require \LaTeX{} packages that may clash with
other packages used in a document.  Additionally, if we redefine token
renderers and renderer prototypes ourselves, the default definitions will bring
no benefit to us. Using the `plain` package option, we can keep the default
definitions from the plain \TeX{} implementation
% (see Section <#sec:textokenrendererprototypes>)
and prevent the soft \LaTeX{} prerequisites
% in Section <#sec:latexprerequisites>
from being loaded: The plain option must be set before or when loading the
package. Setting the option after loading the package will have no effect.

``` tex
\usepackage[plain]{markdown}
```````

% \end{markdown}
% \iffalse
%</manual-options>
%<*latex>
% \fi
%  \begin{macrocode}
\@@_add_latex_option:nnn
  { plain }
  { boolean }
  { false }
\ExplSyntaxOff
%    \end{macrocode}
% \iffalse
%</latex>
%<*manual-options>
% \fi
% \begin{markdown}

#### \LaTeX{} themes {#latexthemes}

User-defined \LaTeX{} themes for the Markdown package provide a domain-specific
interpretation of Markdown tokens. Similarly to \LaTeX{} packages, themes
allow the authors to achieve a specific look and other high-level goals
without low-level programming.

% The \LaTeX{} option `theme`=\meta{theme name} loads a \LaTeX{} package
% (further referred to as *a theme*) named `markdowntheme`\meta{munged theme
% name}`.sty`, where the *munged theme name* is the *theme name* after the
% substitution of all forward slashes (`/`) for an underscore (`_`), the theme
% *name* is *qualified* and contains no underscores, and a value is qualified
% if and only if it contains at least one forward slash. Themes are inspired by
% the Beamer \LaTeX{} package, which provides similar functionality with its
% `\usetheme` macro [@tantau21, Section 15.1].
%
% Theme names must be qualified to minimize naming conflicts between different
% themes intended for a single \LaTeX{} document class or for a single \LaTeX{}
% package. The preferred format of a theme name is \meta{theme author}`/`<!--
% -->\meta{target \LaTeX{} document class or package}`/`\meta{private naming
% scheme}, where the *private naming scheme* may contain additional forward
% slashes. For example, a theme by a user `witiko` for the MU theme of the
% Beamer document class may have the name `witiko/beamer/MU`.
%
% Theme names are munged, because \LaTeX{} packages are identified only by
% their filenames, not by their pathnames. [@novotny21] Therefore, we can't
% store the qualified theme names directly using directories, but we must
% encode the individual segments of the qualified theme in the filename. For
% example, loading a theme named `witiko/beamer/MU` would load a \LaTeX{}
% package named `markdownthemewitiko_beamer_MU.sty`.
%
% If the \LaTeX{} option with key `theme` is (repeatedly) specified in the
% `\usepackage` macro, the loading of the theme(s) will be postponed in
% first-in-first-out order until after the Markdown \LaTeX{} package has been
% loaded. Otherwise, the theme(s) will be loaded immediately. For example,
% there is a theme named `witiko/dot`, which typesets fenced code blocks with
% the `dot` infostring as images of directed graphs rendered by the Graphviz
% tools. The following code would first load the Markdown package, then the
% `markdownthemewitiko_beamer_MU.sty` \LaTeX{} package, and finally the
% `markdownthemewitiko_dot.sty` \LaTeX{} package:
% \end{markdown}
% \iffalse

For example, to load themes named `witiko/beamer/MU` and `witiko/dot`, you
would use the following code in the preamble of your document:

% \fi
% \par
% \begin{markdown}

``` tex
\usepackage[
  theme = witiko/beamer/MU,
  theme = witiko/dot,
]{markdown}
```````

% \end{markdown}
% \iffalse
%</manual-options>
%<*latex>
% \fi
%  \begin{macrocode}
\newif\ifmarkdownLaTeXLoaded
  \markdownLaTeXLoadedfalse
\AtEndOfPackage{\markdownLaTeXLoadedtrue}
\ExplSyntaxOn
\tl_new:N \markdownLaTeXThemePackageName
\cs_new:Nn
  \@@_set_latex_theme:n
  {
    \str_if_in:nnF
      { #1 }
      { / }
      {
        \markdownError
        { Won't~load~theme~with~unqualified~name~#1 }
        { Theme~names~must~contain~at~least~one~forward~slash }
      }
    \str_if_in:nnT
      { #1 }
      { _ }
      {
        \markdownError
        { Won't~load~theme~with~an~underscore~in~its~name~#1 }
        { Theme~names~must~not~contain~underscores~in~their~names }
      }
    \tl_set:Nn \markdownLaTeXThemePackageName { #1 }
    \str_replace_all:Nnn
      \markdownLaTeXThemePackageName
      { / }
      { _ }
    \edef\markdownLaTeXThemePackageName{
      markdowntheme\markdownLaTeXThemePackageName}
    \expandafter\markdownLaTeXThemeLoad\expandafter{
      \markdownLaTeXThemePackageName}{#1/}
  }
\keys_define:nn
  { markdown/latex-options }
  {
    theme .code:n = { \@@_set_latex_theme:n { #1 } },
  }
\ExplSyntaxOff
%    \end{macrocode}
% \begin{markdown}
%
% The \LaTeX{} themes have a useful synergy with the setup snippets (see
% Section <#sec:latexoptions>): To make it less likely that different
% themes will define setup snippets with the same name, we will prepend
% \meta{theme name}`/` before the snippet name and use the result as the
% snippet name. For example, if the `witiko/dot` theme defines the `product`
% setup snippet, the setup snippet will be available under the name
% `witiko/dot/product`.
%
% \end{markdown}
% \iffalse
%</latex>
%<*manual-options>
% \fi
% \begin{markdown}

Due to limitations of \LaTeX{}, themes may not be loaded after the
beginning of a \LaTeX{} document.

% \end{markdown}
% \iffalse
%</manual-options>
%<*latex>
% \fi
%  \begin{macrocode}
\ExplSyntaxOn
\@onlypreamble
  \@@_set_latex_theme:n
\ExplSyntaxOff
%    \end{macrocode}
% \iffalse
%</latex>
%<*manual-options>
% \fi
% \par
% \markdownBegin

Example themes provided with the Markdown package include:

\pkg{witiko/dot}

:    A theme that typesets fenced code blocks with the `dot …` infostring
     as images of directed graphs rendered by the Graphviz tools. The
     right tail of the infostring is used as the image title.
%    ```` tex
%    \documentclass{article}
%    \usepackage[theme=witiko/dot]{markdown}
%    \setkeys{Gin}{
%      width = \columnwidth,
%      height = 0.65\paperheight,
%      keepaspectratio}
%    \begin{document}
%    \begin{markdown}
%    ``` dot Various formats of mathemathical formulae
%    digraph tree {
%      margin = 0;
%      rankdir = "LR";
%
%      latex -> pmml;
%      latex -> cmml;
%      pmml -> slt;
%      cmml -> opt;
%      cmml -> prefix;
%      cmml -> infix;
%      pmml -> mterms [style=dashed];
%      cmml -> mterms;
%
%      latex [label = "LaTeX"];
%      pmml [label = "Presentation MathML"];
%      cmml [label = "Content MathML"];
%      slt [label = "Symbol Layout Tree"];
%      opt [label = "Operator Tree"];
%      prefix [label = "Prefix"];
%      infix [label = "Infix"];
%      mterms [label = "M-Terms"];
%    }
%    ```
%    \end{markdown}
%    \end{document}
%    ````````
%    Typesetting the above document produces the output shown in
%    Figure <#fig:witiko/dot>.
%    ``` dot Various formats of mathemathical formulae \label{fig:witiko/dot}
%    digraph tree {
%      margin = 0;
%      rankdir = "LR";
%
%      latex -> pmml;
%      latex -> cmml;
%      pmml -> slt;
%      cmml -> opt;
%      cmml -> prefix;
%      cmml -> infix;
%      pmml -> mterms [style=dashed];
%      cmml -> mterms;
%
%      latex [label = "LaTeX"];
%      pmml [label = "Presentation MathML"];
%      cmml [label = "Content MathML"];
%      slt [label = "Symbol Layout Tree"];
%      opt [label = "Operator Tree"];
%      prefix [label = "Prefix"];
%      infix [label = "Infix"];
%      mterms [label = "M-Terms"];
%    }
%    ```
     The theme requires a Unix-like operating system with GNU Diffutils and
     Graphviz installed. The theme also requires shell access unless the
     \Opt{frozenCache} plain \TeX{} option is enabled.

% \markdownEnd
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
```` tex
\documentclass{article}
\usepackage[theme=witiko/dot]{markdown}
\setkeys{Gin}{
  width=\columnwidth,
  height=0.65\paperheight,
  keepaspectratio}
\begin{document}
\begin{markdown}
``` dot Various formats of mathemathical formulae
digraph tree {
  margin = 0;
  rankdir = "LR";

  latex -> pmml;
  latex -> cmml;
  pmml -> slt;
  cmml -> opt;
  cmml -> prefix;
  cmml -> infix;
  pmml -> mterms [style=dashed];
  cmml -> mterms;

  latex [label = "LaTeX"];
  pmml [label = "Presentation MathML"];
  cmml [label = "Content MathML"];
  slt [label = "Symbol Layout Tree"];
  opt [label = "Operator Tree"];
  prefix [label = "Prefix"];
  infix [label = "Infix"];
  mterms [label = "M-Terms"];
}
```
\end{markdown}
\end{document}
````````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain
a drawing of a directed graph similar to Figure 1 from the following
conference article:

> NOVOTNÝ, Vít, Petr SOJKA, Michal ŠTEFÁNIK and Dávid LUPTÁK. Three is Better
> than One: Ensembling Math Information Retrieval Systems. *CEUR Workshop
> Proceedings*. Thessaloniki, Greece: M. Jeusfeld c/o Redaktion Sun SITE,
> Informatik V, RWTH Aachen., 2020, vol. 2020, No 2696, p. 1-30. ISSN 1613-0073.
> <http://ceur-ws.org/Vol-2696/paper_235.pdf>

%</manual-options>
%<*latex-themes-witiko-dot>
% \fi
%  \begin{macrocode}
\ProvidesPackage{markdownthemewitiko_dot}[2021/03/09]%
%    \end{macrocode}
% \iffalse
%</latex-themes-witiko-dot>
%<*manual-options>
% \fi
% \par
% \markdownBegin

\pkg{witiko/graphicx/http}

:    A theme that adds support for downloading images whose URL has the
     http or https protocol.
%    ``` tex
%    \documentclass{article}
%    \usepackage[theme=witiko/graphicx/http]{markdown}
%    \begin{document}
%    \begin{markdown}
%    ![img](https://github.com/witiko/markdown/raw/main/markdown.png
%           "The banner of the Markdown package")
%    \end{markdown}
%    \end{document}
%    ```````
%    Typesetting the above document produces the output shown in
%    Figure <#fig:witiko/graphicx/http>.
%    ![img](https://github.com/witiko/markdown/raw/main/markdown.png
%           "The banner of the Markdown package \label{fig:witiko/graphicx/http}")
     The theme requires the \pkg{catchfile} \LaTeX{} package and a Unix-like
     operating system with GNU Coreutils `md5sum` and either GNU Wget or cURL
     installed. The theme also requires shell access unless the
     \Opt{frozenCache} plain \TeX{} option is enabled.

% \markdownEnd
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[theme=witiko/graphicx/http]{markdown}
\begin{document}
\begin{markdown}
![img](https://github.com/witiko/markdown/raw/main/markdown.png
       "The banner of the Markdown package")
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following image:

> ![img](https://github.com/witiko/markdown/raw/main/markdown.png
> "The banner of the Markdown package")

%</manual-options>
%<*latex-themes-witiko-graphicx-http>
% \fi
%  \begin{macrocode}
\ProvidesPackage{markdownthemewitiko_graphicx_http}[2021/03/22]%
%    \end{macrocode}
% \iffalse
%</latex-themes-witiko-graphicx-http>
%<*manual-options>
% \fi
% \par
% \markdownBegin

\pkg{witiko/tilde}

:    A theme that makes tilde (`~`) always typeset the non-breaking space even
     when the \Opt{hybrid} Lua option is disabled.
%    ``` tex
%    \documentclass{article}
%    \usepackage[theme=witiko/tilde]{markdown}
%    \begin{document}
%    \begin{markdown}
%    Bartel~Leendert van~der~Waerden
%    \end{markdown}
%    \end{document}
%    ```````
%    Typesetting the above document produces the following text:
%    “Bartel~Leendert van~der~Waerden”.
%
% \markdownEnd
% \iffalse

##### \LaTeX{} Example {.unnumbered}

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\documentclass{article}
\usepackage[theme=witiko/tilde]{markdown}
\begin{document}
\begin{markdown}
Bartel~Leendert van~der~Waerden
\end{markdown}
\end{document}
```````
Next, invoke LuaTeX from the terminal:
``` sh
lualatex document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text, where the middot (`·`) denotes a non-breaking space:

> Bartel·Leendert van·der·Waerden

%</manual-options>
%<*latex-themes-witiko-tilde>
% \fi
%  \begin{macrocode}
\ProvidesPackage{markdownthemewitiko_tilde}[2021/03/22]%
%    \end{macrocode}
% \iffalse
%</latex-themes-witiko-tilde>
%<*manual-options>
% \fi
% \par
% \begin{markdown}
%
% Please, see Section <#sec:latexthemesimplementation> for implementation
% details of the example themes.

#### \LaTeX{} setup snippets {#latexsetupsnippets}

% \end{markdown}
% \iffalse

User-defined \LaTeX{} themes provide global control over high-level goals.
However, it is often desirable to change only some local aspects of a document.
\LaTeX{} setup snippets provide syntactic sugar for defining and invoking
various options locally.

% \fi
% \begin{markdown}
% The \LaTeX{} option with key `snippet` invokes a snippet named \meta{value}:
% \end{markdown}
% \iffalse
%</manual-options>
%<*latex>
% \fi
%  \begin{macrocode}
\ExplSyntaxOn
\keys_define:nn
  { markdown/latex-options }
  {
    snippet .code:n = {
      \markdownIfSnippetExists{#1}
        {
          \expandafter\markdownSetup\expandafter{
            \the\csname markdownLaTeXSetupSnippet
            \markdownLaTeXThemeName#1\endcsname}
        }{
          \markdownError
            {Can't~invoke~setup~snippet~#1}
            {The~setup~snippet~is~undefined}
        }
    }
  }
\ExplSyntaxOff
%    \end{macrocode}
% \iffalse
%</latex>
%<*manual-options>
% \fi
% \par
% \markdownBegin

Here is how we can use setup snippets to store options and invoke them later:

``` tex
\markdownSetupSnippet{romanNumerals}{
  renderers = {
      olItemWithNumber = {%
          \item[\romannumeral#1\relax.]%
      },
  },
}
\begin{markdown}

The following ordered list will be preceded by arabic numerals:

1. wahid
2. aithnayn

\end{markdown}
\begin{markdown*}{snippet=romanNumerals}

The following ordered list will be preceded by roman numerals:

3. tres
4. quattuor

\end{markdown*}

```````

% \markdownEnd
% \iffalse
%</manual-options>
%<*latex>
% \fi
% \begin{markdown}
%
%#### Plain \TeX{} Interface Options
% Here, we automatically define plain \TeX{} macros and the
% \meta{key}`=`\meta{value} interface for the above \LaTeX{} options.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_new:Nn \@@_latex_define_option_commands_and_keyvals:
  {
    \seq_map_inline:Nn
      \g_@@_latex_options_seq
      {
          \@@_plain_tex_define_option_command:n
            { ##1 }
      }
%    \end{macrocode}
% \begin{markdown}
%
% Furthermore, we also define the \meta{key}`=`\meta{value} interface
% for all option macros recognized by the Lua and plain \TeX{} interfaces.
%
% \end{markdown}
%  \begin{macrocode}
    \seq_map_inline:Nn
      \g_@@_option_layers_seq
      {
        \seq_map_inline:cn
          { g_@@_ ##1 _options_seq }
          {
%    \end{macrocode}
% \begin{markdown}
%
% To make it easier to copy-and-paste options from Pandoc [@macfarlane22] such
% as `fancy_lists`, `header_attributes`, and `pipe_tables`, we accept
% snake\\\_case in addition to camelCase variants of options. As a bonus,
% studies [@sharif10] also show that snake\\\_case is faster to read than
% camelCase.
%
% \end{markdown}
%  \begin{macrocode}
              \@@_with_various_cases:nn
                { ####1 }
                {
                  \@@_latex_define_option_keyval:nnn
                    { ##1 }
                    { ####1 }
                    { ########1 }
                }
          }
      }
  }
\cs_new:Nn \@@_latex_define_option_keyval:nnn
  {
    \prop_get:cnN
      { g_@@_ #1 _option_types_prop }
      { #2 }
      \l_tmpa_tl
    \keys_define:nn
      { markdown/latex-options }
      {
        #3 .code:n = {
          \@@_set_option_value:nn
            { #2 }
            { ##1 }
        },
      }
    \str_if_eq:VVT
      \l_tmpa_tl
      \c_@@_option_type_boolean_tl
      {
        \keys_define:nn
          { markdown/latex-options }
          {
            #3 .default:n = { true },
          }
      }
%    \end{macrocode}
% \begin{markdown}
%
% For options of type `clist`, we assume that \meta{key} is a regular English
% noun in plural (such as `extensions`) and we also define the
% \meta{singular key}`=`\meta{value} interface, where \meta{singular key} is
% \meta{key} after stripping the trailing -s (such as `extension`). Rather
% than setting the option to \meta{value}, this interface appends \meta{value}
% to the current value as the rightmost item in the list.
%
% \end{markdown}
%  \begin{macrocode}
    \str_if_eq:VVT
      \l_tmpa_tl
      \c_@@_option_type_clist_tl
      {
        \tl_set:Nn
          \l_tmpa_tl
          { #3 }
        \tl_reverse:N
          \l_tmpa_tl
        \str_if_eq:enF
          {
            \tl_head:V
              \l_tmpa_tl
          }
          { s }
          {
              \msg_error:nnn
                { @@ }
                { malformed-name-for-clist-option }
                { #3 }
          }
        \tl_set:Nx
          \l_tmpa_tl
          {
            \tl_tail:V
              \l_tmpa_tl
          }
        \tl_reverse:N
          \l_tmpa_tl
        \tl_put_right:Nn
          \l_tmpa_tl
          {
            .code:n = {
              \@@_get_option_value:nN
                { #2 }
                \l_tmpa_tl
              \clist_set:NV
                \l_tmpa_clist
                { \l_tmpa_tl, { ##1 } }
              \@@_set_option_value:nV
                { #2 }
                \l_tmpa_clist
            }
          }
        \keys_define:nV
          { markdown/latex-options }
          \l_tmpa_tl
      }
  }
\cs_generate_variant:Nn
  \clist_set:Nn
  { NV }
\cs_generate_variant:Nn
  \keys_define:nn
  { nV }
\cs_generate_variant:Nn
  \@@_set_option_value:nn
  { nV }
\prg_generate_conditional_variant:Nnn
  \str_if_eq:nn
  { en }
  { F }
\msg_new:nnn
  { @@ }
  { malformed-name-for-clist-option }
  {
    Clist~option~name~#1~does~not~end~with~-s.
  }
\@@_latex_define_option_commands_and_keyvals:
\ExplSyntaxOff
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \Opt{finalizeCache} and \Opt{frozenCache} plain
% \TeX{} options are exposed through \LaTeX{} options with keys `finalizeCache`
% and `frozenCache`.
%
% To ensure compatibility with the `minted` package [@poore17, Section
% 5.1], which supports the `finalizecache` and `frozencache` package options
% with similar semantics, the Markdown package also recognizes these as aliases
% and recognizes them as document class options. By passing `finalizecache` and
% `frozencache` as document class options, you may conveniently control the
% behavior of both packages at once:
%
% ``` tex
% \documentclass[frozencache]{article}
% \usepackage{markdown,minted}
% \begin{document}
% % ...
% \end{document}
% ```````
%
% We hope that other packages will support the `finalizecache` and
% `frozencache` package options in the future, so that they can become a
% standard interface for preparing \LaTeX{} document sources for distribution.
%
% \end{markdown}
%  \begin{macrocode}
\DeclareOption{finalizecache}{\markdownSetup{finalizeCache}}
\DeclareOption{frozencache}{\markdownSetup{frozenCache}}
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The following example \LaTeX{} code showcases a possible configuration of
% plain \TeX{} interface options \Opt{hybrid}, \Opt{smartEllipses}, and
% \Opt{cacheDir}.
% ``` tex
% \markdownSetup{
%   hybrid,
%   smartEllipses,
%   cacheDir = /tmp,
% }
% ```````
%
%#### Plain \TeX{} Markdown Token Renderers {#latexrenderers}
%
% The \LaTeX{} interface recognizes an option with the `renderers` key,
% whose value must be a list of options that map directly to the markdown token
% renderer macros exposed by the plain \TeX{} interface (see Section
% <#sec:texrenderersuser>).
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_new:Nn \@@_latex_define_renderers:
  {
    \seq_map_function:NN
      \g_@@_renderers_seq
      \@@_latex_define_renderer:n
  }
\cs_new:Nn \@@_latex_define_renderer:n
  {
    \@@_renderer_tl_to_csname:nN
      { #1 }
      \l_tmpa_tl
    \prop_get:NnN
      \g_@@_renderer_arities_prop
      { #1 }
      \l_tmpb_tl
    \@@_latex_define_renderer:ncV
      { #1 }
      { \l_tmpa_tl }
      \l_tmpb_tl
  }
\cs_new:Nn \@@_renderer_tl_to_csname:nN
  {
    \tl_set:Nn
      \l_tmpa_tl
      { \str_uppercase:n { #1 } }
    \tl_set:Nx
      #2
      {
        markdownRenderer
        \tl_head:f { \l_tmpa_tl }
        \tl_tail:n { #1 }
      }
  }
\cs_new:Nn \@@_latex_define_renderer:nNn
  {
    \@@_with_various_cases:nn
      { #1 }
      {
        \keys_define:nn
          { markdown/latex-options/renderers }
          {
            ##1 .code:n = {
              \cs_generate_from_arg_count:NNnn
                #2
                \cs_set:Npn
                { #3 }
                { ####1 }
            },
          }
      }
  }
\cs_generate_variant:Nn
  \@@_latex_define_renderer:nNn
  { ncV }
\ExplSyntaxOff
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The following example \LaTeX{} code showcases a possible configuration of the
% \mref{markdownRendererLink} and \mref{markdownRendererEmphasis} markdown token
% renderers.
% ``` tex
% \markdownSetup{
%   renderers = {
%     link = {#4},                   \% Render links as the link title.
%     emphasis = {\emph{#1}},    \% Render emphasized text via `\emph`.
%   }
% }
% ```````
%
%#### Plain \TeX{} Markdown Token Renderer Prototypes {#latexrendererprototypes}
%
% The \LaTeX{} interface recognizes an option with the `rendererPrototypes`
% key, whose value must be a list of options that map directly to the markdown
% token renderer prototype macros exposed by the plain \TeX{} interface (see
% Section <#sec:texrendererprototypes>).
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_new:Nn \@@_latex_define_renderer_prototypes:
  {
    \seq_map_function:NN
      \g_@@_renderers_seq
      \@@_latex_define_renderer_prototype:n
  }
\cs_new:Nn \@@_latex_define_renderer_prototype:n
  {
    \@@_renderer_prototype_tl_to_csname:nN
      { #1 }
      \l_tmpa_tl
    \prop_get:NnN
      \g_@@_renderer_arities_prop
      { #1 }
      \l_tmpb_tl
    \@@_latex_define_renderer_prototype:ncV
      { #1 }
      { \l_tmpa_tl }
      \l_tmpb_tl
  }
\cs_new:Nn \@@_latex_define_renderer_prototype:nNn
  {
    \@@_with_various_cases:nn
      { #1 }
      {
        \keys_define:nn
          { markdown/latex-options/renderer-prototypes }
          {
            ##1 .code:n = {
              \cs_generate_from_arg_count:NNnn
                #2
                \cs_set:Npn
                { #3 }
                { ####1 }
            },
          }
      }
  }
\cs_generate_variant:Nn
  \@@_latex_define_renderer_prototype:nNn
  { ncV }
\ExplSyntaxOff
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The following example \LaTeX{} code showcases a possible configuration of the
% `\markdownRendererImagePrototype` and `\markdownRendererCodeSpanPrototype`
% markdown token renderer prototypes.
% ``` tex
% \markdownSetup{
%   rendererPrototypes = {
%     image = {\includegraphics{#2}},
%     codeSpan = {\texttt{#1}},    \% Render inline code via `\texttt`.
%   }
% }
% ```````
%
% \iffalse
%</latex>
%<*context>
% \fi
%
% \Hologo{ConTeXt} Interface {#contextinterface}
%----------------------------
%
% \iffalse
%</context>
%<*manual-interfaces>

### \Hologo{ConTeXt}

The \Hologo{ConTeXt} interface provides the same level of functionality as the
plain \TeX{} interface by using the plain \TeX{} interface behind the scenes.
Unlike the plain \TeX{} interface, the \Hologo{ConTeXt} interface uses familiar
\Hologo{ConTeXt} idioms as syntactic sugar.

The \Hologo{ConTeXt} interface accepts the same options as the plain \TeX{}
interface.

Using a text editor, create a text document named `document.tex` with the
following content:
``` tex
\usemodule[t][markdown]
\starttext

\startmarkdown
$\sqrt{-1}$ *equals* $i$.
\stopmarkdown

\setupmarkdown[hybrid = yes]
\startmarkdown
$\sqrt{-1}$ *equals* $i$.
\stopmarkdown

\stoptext
```````
Next, invoke LuaTeX from the terminal:
``` sh
context document.tex
``````
A PDF document named `document.pdf` should be produced and contain the
following text:

> \$\\sqrt{-1}\$ *equals* \$i\$.
> 
> √-̅1̅ *equals* $i$.
  
Invoking pdfTeX should have the same effect:
``` sh
texexec --passon=--shell-escape document.tex
``````

%</manual-interfaces>
%<*context>
% \fi
%
% The \Hologo{ConTeXt} interface provides a start-stop macro pair for the
% typesetting of markdown input from within \Hologo{ConTeXt} and facilities for
% setting Lua, plain \TeX, and \Hologo{ConTeXt} options used during the
% conversion from markdown to plain \TeX{}. The rest of the interface is
% inherited from the plain \TeX{} interface (see Section <#sec:texinterface>).
%
% \end{markdown}
%  \begin{macrocode}
\writestatus{loading}{ConTeXt User Module / markdown}%
\startmodule[markdown]
\unprotect
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \Hologo{ConTeXt} implementation redefines the plain \TeX{} logging macros
% (see Section <#sec:texinterfacelogging>) to use the \Hologo{ConTeXt}
% `\writestatus` macro.
%
% \end{markdown}
%  \begin{macrocode}
\def\markdownInfo#1{\writestatus{markdown}{#1.}}%
\def\markdownWarning#1{\writestatus{markdown\space warn}{#1.}}%
\def\dospecials{\do\ \do\\\do\{\do\}\do\$\do\&%
  \do\#\do\^\do\_\do\%\do\~}%
\input markdown/markdown
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \Hologo{ConTeXt} interface is implemented by the
% `t-markdown.tex` \Hologo{ConTeXt} module file that can be loaded as follows:
% ``` tex
% \usemodule[t][markdown]
% ```````
% \noindent It is expected that the special plain \TeX{} characters have the
% expected category codes, when `\input`ting the file.
%
%### Typesetting Markdown
% The interface exposes the \mdef{startmarkdown} and \mdef{stopmarkdown} macro
% pair for the typesetting of a markdown document fragment, and defines the
% \mdef{inputmarkdown} command.
%
% \end{markdown}
%  \begin{macrocode}
\let\startmarkdown\relax
\let\stopmarkdown\relax
\let\inputmarkdown\relax
%    \end{macrocode}
% \par
% \begin{markdown}
%
% You may prepend your own code to the \mref{startmarkdown} macro and redefine the
% \mref{stopmarkdown} macro to produce special effects before and after the
% markdown block.
%
% Note that the \mref{startmarkdown} and \mref{stopmarkdown} macros
% are subject to the same limitations as the \mref{markdownBegin} and
% \mref{markdownEnd} macros exposed by the plain \TeX{} interface.
%
% The following example \Hologo{ConTeXt} code showcases the usage of the
% \mref{startmarkdown} and \mref{stopmarkdown} macros:
% ``` tex
% \usemodule[t][markdown]
% \starttext
% \startmarkdown
% _Hello_ **world** ...
% \stopmarkdown
% \stoptext
% ```````
%
% The \mref{inputmarkdown} macro accepts a single mandatory parameter
% containing the filename of a markdown document and expands to the result of
% the conversion of the input markdown document to plain \TeX{}. Unlike the
% \mref{markdownInput} macro provided by the plain \TeX{} interface, this macro
% also accepts \Hologo{ConTeXt} interface options (see Section
% <#sec:contextoptions>) as its optional argument. These options will only
% influnce this markdown document.
%
% The following example \LaTeX{} code showcases the usage of the
% \mref{markdownInput} macro:
% ``` tex
% \usemodule[t][markdown]
% \starttext
% % ...
% \inputmarkdown[smartEllipses]{hello.md}
% % ...
% \stoptext
% ```````
%
%### Options {#contextoptions}
%
% The \Hologo{ConTeXt} options are represented by a comma-delimited list of
% \meta{key}`=`\meta{value} pairs. For boolean options, the `=`\meta{value}
% part is optional, and \meta{key} will be interpreted as \meta{key}`=true`
% (or, equivalently, \meta{key}`=yes`) if the `=`\meta{value} part has been
% omitted.
%
% \Hologo{ConTeXt} options map directly to the options recognized by the plain
% \TeX{} interface (see Section <#sec:texoptions>).
%
% The \Hologo{ConTeXt} options may be specified when using the
% \mref{inputmarkdown} macro (see Section <#sec:contextinterface>), or via the
% \mdef{setupmarkdown} macro. The \mref{setupmarkdown} macro receives the
% options to set up as its only argument:
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_new:Nn
  \@@_setup:n
  {
    \keys_set:nn
      { markdown/context-options }
      { #1 }
  }
\long\def\setupmarkdown[#1]
  {
    \@@_setup:n
      { #1 }
  }
\ExplSyntaxOff
%    \end{macrocode}
% \begin{markdown}
%
%#### \Hologo{ConTeXt} Interface Options
% We define the \meta{key}`=`\meta{value} interface for all option macros
% recognized by the Lua and plain \TeX{} interfaces.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_new:Nn \@@_context_define_option_commands_and_keyvals:
  {
    \seq_map_inline:Nn
      \g_@@_option_layers_seq
      {
        \seq_map_inline:cn
          { g_@@_ ##1 _options_seq }
          {
%    \end{macrocode}
% \begin{markdown}
%
% To make it easier to copy-and-paste options from Pandoc [@macfarlane22] such
% as `fancy_lists`, `header_attributes`, and `pipe_tables`, we accept
% snake\\\_case in addition to camelCase variants of options. As a bonus,
% studies [@sharif10] also show that snake\\\_case is faster to read than
% camelCase.
%
% \end{markdown}
%  \begin{macrocode}
              \@@_with_various_cases:nn
                { ####1 }
                {
                  \@@_context_define_option_keyval:nnn
                    { ##1 }
                    { ####1 }
                    { ########1 }
                }
          }
      }
  }
%    \end{macrocode}
% \begin{markdown}
%
% Furthermore, we also accept caseless variants of options in line with the
% style of \Hologo{ConTeXt}.
%
% \end{markdown}
%  \begin{macrocode}
\cs_new:Nn \@@_caseless:N
  {
    \regex_replace_all:nnN
      { ([a-z])([A-Z]) }
      { \1 \c { str_lowercase:n } \cB\{ \2 \cE\} }
      #1
    \tl_set:Nx
      #1
      { #1 }
  }
\seq_gput_right:Nn \g_@@_cases_seq { @@_caseless:N }
\cs_new:Nn \@@_context_define_option_keyval:nnn
  {
    \prop_get:cnN
      { g_@@_ #1 _option_types_prop }
      { #2 }
      \l_tmpa_tl
    \keys_define:nn
      { markdown/context-options }
      {
        #3 .code:n = {
          \tl_set:Nx
            \l_tmpa_tl
            {
              \str_case:nnF
                { ##1 }
                {
                  { yes } { true }
                  { no } { false }
                }
                { ##1 }
            }
          \@@_set_option_value:nV
            { #2 }
            \l_tmpa_tl
        },
      }
    \str_if_eq:VVT
      \l_tmpa_tl
      \c_@@_option_type_boolean_tl
      {
        \keys_define:nn
          { markdown/context-options }
          {
            #3 .default:n = { true },
          }
      }
  }
\cs_generate_variant:Nn
  \@@_set_option_value:nn
  { nV }
\@@_context_define_option_commands_and_keyvals:
\ExplSyntaxOff
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Implementation {#implementation}
%================
%
% This part of the documentation describes the implementation of the interfaces
% exposed by the package (see Section <#sec:interfaces>) and is aimed at the
% developers of the package, as well as the curious users.
%
% Figure <#fig:block-diagram> shows the high-level structure of the Markdown
% package: The translation from markdown to \TeX{} *token renderers* is
% performed by the Lua layer. The plain \TeX{} layer provides default
% definitions for the token renderers. The \LaTeX{} and \Hologo{ConTeXt} layers
% correct idiosyncrasies of the respective \TeX{} formats, and provide
% format-specific default definitions for the token renderers.
%
% \end{markdown}
% \iffalse
%</context>
%<*lua>
% \fi
% \begin{markdown}
%
% Lua Implementation {#luaimplementation}
%--------------------
%
% The Lua implementation implements \luamdef{writer} and \luamref{reader}
% objects, which provide the conversion from markdown to plain \TeX, and
% \luamdef{extensions} objects, which provide syntax extensions for the
% \luamref{writer} and \luamref{reader} objects.
%
% The Lunamark Lua module implements writers for the conversion to various
% other formats, such as DocBook, Groff, or \acro{HTML}. These were stripped
% from the module and the remaining markdown reader and plain \TeX{} writer
% were hidden behind the converter functions exposed by the Lua interface (see
% Section <#sec:luainterface>).
%
% \end{markdown}
%  \begin{macrocode}
local upper, gsub, format, length =
  string.upper, string.gsub, string.format, string.len
local P, R, S, V, C, Cg, Cb, Cmt, Cc, Ct, B, Cs, any =
  lpeg.P, lpeg.R, lpeg.S, lpeg.V, lpeg.C, lpeg.Cg, lpeg.Cb,
  lpeg.Cmt, lpeg.Cc, lpeg.Ct, lpeg.B, lpeg.Cs, lpeg.P(1)
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Utility Functions
% This section documents the utility functions used by the plain \TeX{}
% writer and the markdown reader. These functions are encapsulated in the
% `util` object. The functions were originally located in the
% `lunamark/util.lua` file in the Lunamark Lua module.
%
% \end{markdown}
%  \begin{macrocode}
local util = {}
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{util.err} method prints an error message `msg` and exits.
% If `exit_code` is provided, it specifies the exit code.  Otherwise, the
% exit code will be 1.
%
% \end{markdown}
%  \begin{macrocode}
function util.err(msg, exit_code)
  io.stderr:write("markdown.lua: " .. msg .. "\n")
  os.exit(exit_code or 1)
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{util.cache} method computes the digest of `string` and
% `salt`, adds the `suffix` and looks into the directory `dir`, whether a
% file with such a name exists. If it does not, it gets created with
% `transform(string)` as its content. The filename is then returned.
%
% \end{markdown}
%  \begin{macrocode}
function util.cache(dir, string, salt, transform, suffix)
  local digest = md5.sumhexa(string .. (salt or ""))
  local name = util.pathname(dir, digest .. suffix)
  local file = io.open(name, "r")
  if file == nil then -- If no cache entry exists, then create a new one.
    file = assert(io.open(name, "w"),
      [[Could not open file "]] .. name .. [[" for writing]])
    local result = string
    if transform ~= nil then
      result = transform(result)
    end
    assert(file:write(result))
    assert(file:close())
  end
  return name
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{util.cache_verbatim} method strips whitespaces from the
% end of `string` and calls \luamref{util.cache} with `dir`, `string`,
% no salt or transformations, and the `.verbatim` suffix.
%
% \end{markdown}
%  \begin{macrocode}
function util.cache_verbatim(dir, string)
  string = string:gsub('[\r\n%s]*$', '')
  local name = util.cache(dir, string, nil, nil, ".verbatim")
  return name
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{util.table_copy} method creates a shallow copy of a table `t`
% and its metatable.
%
% \end{markdown}
%  \begin{macrocode}
function util.table_copy(t)
  local u = { }
  for k, v in pairs(t) do u[k] = v end
  return setmetatable(u, getmetatable(t))
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{util.encode_json_string} method encodes a string `s` in
% \acro{JSON}.
%
% \end{markdown}
%  \begin{macrocode}
function util.encode_json_string(s)
  s = s:gsub([[\]], [[\\]])
  s = s:gsub([["]], [[\"]])
  return [["]] .. s .. [["]]
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{util.lookup_files} method looks up files with filename `f`
% and returns its path. If the \pkg{kpathsea} library is available, it will
% search for files not only in the current working directory but also in the
% \TeX{} directory structure. Further options for \pkg{kpathsea} can be
% specified in table `options`. [@luatex21, Section 10.7.4]
%
% \end{markdown}
%  \begin{macrocode}
util.lookup_files = (function()
  local ran_ok, kpse = pcall(require, "kpse")
  if ran_ok then
    kpse.set_program_name("luatex")
  else
    kpse = { lookup = function(f, _) return f end }
  end

  local function lookup_files(f, options)
    return kpse.lookup(f, options)
  end

  return lookup_files
end)()
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{util.expand_tabs_in_line} expands tabs in string `s`. If
% `tabstop` is specified, it is used as the tab stop width. Otherwise,
% the tab stop width of 4 characters is used. The method is a copy of the tab
% expansion algorithm from @ierusalimschy13 [Chapter 21].
%
% \end{markdown}
%  \begin{macrocode}
function util.expand_tabs_in_line(s, tabstop)
  local tab = tabstop or 4
  local corr = 0
  return (s:gsub("()\t", function(p)
            local sp = tab - (p - 1 + corr) % tab
            corr = corr - 1 + sp
            return string.rep(" ", sp)
          end))
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{util.walk} method walks a rope `t`, applying a function `f`
% to each leaf element in order. A rope is an array whose elements may be
% ropes, strings, numbers, or functions.  If a leaf element is a function, call
% it and get the return value before proceeding.
%
% \end{markdown}
%  \begin{macrocode}
function util.walk(t, f)
  local typ = type(t)
  if typ == "string" then
    f(t)
  elseif typ == "table" then
    local i = 1
    local n
    n = t[i]
    while n do
      util.walk(n, f)
      i = i + 1
      n = t[i]
    end
  elseif typ == "function" then
    local ok, val = pcall(t)
    if ok then
      util.walk(val,f)
    end
  else
    f(tostring(t))
  end
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{util.flatten} method flattens an array `ary` that does not
% contain cycles and returns the result.
%
% \end{markdown}
%  \begin{macrocode}
function util.flatten(ary)
  local new = {}
  for _,v in ipairs(ary) do
    if type(v) == "table" then
      for _,w in ipairs(util.flatten(v)) do
        new[#new + 1] = w
      end
    else
      new[#new + 1] = v
    end
  end
  return new
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{util.rope_to_string} method converts a rope `rope` to a
% string and returns it. For the definition of a rope, see the definition of
% the \luamref{util.walk} method.
%
% \end{markdown}
%  \begin{macrocode}
function util.rope_to_string(rope)
  local buffer = {}
  util.walk(rope, function(x) buffer[#buffer + 1] = x end)
  return table.concat(buffer)
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{util.rope_last} method retrieves the last item in a rope. For
% the definition of a rope, see the definition of the \luamref{util.walk} method.
%
% \end{markdown}
%  \begin{macrocode}
function util.rope_last(rope)
  if #rope == 0 then
    return nil
  else
    local l = rope[#rope]
    if type(l) == "table" then
      return util.rope_last(l)
    else
      return l
    end
  end
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Given an array `ary` and a string `x`, the \luamdef{util.intersperse}
% method returns an array `new`, such that `ary[i] == new[2*(i-1)+1]` and
% `new[2*i] == x` for all $1\leq`i`\leq`#ary`$.
%
% \end{markdown}
%  \begin{macrocode}
function util.intersperse(ary, x)
  local new = {}
  local l = #ary
  for i,v in ipairs(ary) do
    local n = #new
    new[n + 1] = v
    if i ~= l then
      new[n + 2] = x
    end
  end
  return new
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Given an array `ary` and a function `f`, the \luamdef{util.map} method
% returns an array `new`, such that `new[i] == f(ary[i])` for all
% $1\leq`i`\leq`#ary`$.
%
% \end{markdown}
%  \begin{macrocode}
function util.map(ary, f)
  local new = {}
  for i,v in ipairs(ary) do
    new[i] = f(v)
  end
  return new
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Given a table `char_escapes` mapping escapable characters to escaped
% strings and optionally a table `string_escapes` mapping escapable strings
% to escaped strings, the \luamdef{util.escaper} method returns an escaper
% function that escapes all occurances of escapable strings and characters (in
% this order).
%
% The method uses \pkg{LPeg}, which is faster than the Lua `string.gsub`
% built-in method.
%
% \end{markdown}
%  \begin{macrocode}
function util.escaper(char_escapes, string_escapes)
%    \end{macrocode}
% \begin{markdown}
% Build a string of escapable characters.
% \end{markdown}
%  \begin{macrocode}
  local char_escapes_list = ""
  for i,_ in pairs(char_escapes) do
    char_escapes_list = char_escapes_list .. i
  end
%    \end{macrocode}
% \begin{markdown}
% Create an \pkg{LPeg} capture `escapable` that produces the escaped string
% corresponding to the matched escapable character.
% \end{markdown}
%  \begin{macrocode}
  local escapable = S(char_escapes_list) / char_escapes
%    \end{macrocode}
% \begin{markdown}
% If `string_escapes` is provided, turn `escapable` into the
% $$\sum^^B{(`k`, `v`)\in`string_escapes`}`P(k) / v` + `escapable`$$
% capture that replaces any occurance of the string `k` with the string
% `v` for each $(`k`, `v`)\in`string_escapes`$. Note that the pattern
% summation is not commutative and its operands are inspected in the
% summation order during the matching. As a corrolary, the strings always
% take precedence over the characters.
%
% \end{markdown}
%  \begin{macrocode}
  if string_escapes then
    for k,v in pairs(string_escapes) do
      escapable = P(k) / v + escapable
    end
  end
%    \end{macrocode}
% \begin{markdown}
% Create an \pkg{LPeg} capture `escape_string` that captures anything
% `escapable` does and matches any other unmatched characters.
% \end{markdown}
%  \begin{macrocode}
  local escape_string = Cs((escapable + any)^0)
%    \end{macrocode}
% \begin{markdown}
% Return a function that matches the input string `s` against the
% `escape_string` capture.
% \end{markdown}
%  \begin{macrocode}
  return function(s)
    return lpeg.match(escape_string, s)
  end
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{util.pathname} method produces a pathname out of a directory
% name `dir` and a filename `file` and returns it.
%
% \end{markdown}
%  \begin{macrocode}
function util.pathname(dir, file)
  if #dir == 0 then
    return file
  else
    return dir .. "/" .. file
  end
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### HTML Entities
% This section documents the \acro{HTML} entities recognized by the
% markdown reader.  These functions are encapsulated in the `entities`
% object. The functions were originally located in the
% `lunamark/entities.lua` file in the Lunamark Lua module.
%
% \end{markdown}
%  \begin{macrocode}
local entities = {}

local character_entities = {
  ["Tab"] = 9,
  ["NewLine"] = 10,
  ["excl"] = 33,
  ["quot"] = 34,
  ["QUOT"] = 34,
  ["num"] = 35,
  ["dollar"] = 36,
  ["percnt"] = 37,
  ["amp"] = 38,
  ["AMP"] = 38,
  ["apos"] = 39,
  ["lpar"] = 40,
  ["rpar"] = 41,
  ["ast"] = 42,
  ["midast"] = 42,
  ["plus"] = 43,
  ["comma"] = 44,
  ["period"] = 46,
  ["sol"] = 47,
  ["colon"] = 58,
  ["semi"] = 59,
  ["lt"] = 60,
  ["LT"] = 60,
  ["equals"] = 61,
  ["gt"] = 62,
  ["GT"] = 62,
  ["quest"] = 63,
  ["commat"] = 64,
  ["lsqb"] = 91,
  ["lbrack"] = 91,
  ["bsol"] = 92,
  ["rsqb"] = 93,
  ["rbrack"] = 93,
  ["Hat"] = 94,
  ["lowbar"] = 95,
  ["grave"] = 96,
  ["DiacriticalGrave"] = 96,
  ["lcub"] = 123,
  ["lbrace"] = 123,
  ["verbar"] = 124,
  ["vert"] = 124,
  ["VerticalLine"] = 124,
  ["rcub"] = 125,
  ["rbrace"] = 125,
  ["nbsp"] = 160,
  ["NonBreakingSpace"] = 160,
  ["iexcl"] = 161,
  ["cent"] = 162,
  ["pound"] = 163,
  ["curren"] = 164,
  ["yen"] = 165,
  ["brvbar"] = 166,
  ["sect"] = 167,
  ["Dot"] = 168,
  ["die"] = 168,
  ["DoubleDot"] = 168,
  ["uml"] = 168,
  ["copy"] = 169,
  ["COPY"] = 169,
  ["ordf"] = 170,
  ["laquo"] = 171,
  ["not"] = 172,
  ["shy"] = 173,
  ["reg"] = 174,
  ["circledR"] = 174,
  ["REG"] = 174,
  ["macr"] = 175,
  ["OverBar"] = 175,
  ["strns"] = 175,
  ["deg"] = 176,
  ["plusmn"] = 177,
  ["pm"] = 177,
  ["PlusMinus"] = 177,
  ["sup2"] = 178,
  ["sup3"] = 179,
  ["acute"] = 180,
  ["DiacriticalAcute"] = 180,
  ["micro"] = 181,
  ["para"] = 182,
  ["middot"] = 183,
  ["centerdot"] = 183,
  ["CenterDot"] = 183,
  ["cedil"] = 184,
  ["Cedilla"] = 184,
  ["sup1"] = 185,
  ["ordm"] = 186,
  ["raquo"] = 187,
  ["frac14"] = 188,
  ["frac12"] = 189,
  ["half"] = 189,
  ["frac34"] = 190,
  ["iquest"] = 191,
  ["Agrave"] = 192,
  ["Aacute"] = 193,
  ["Acirc"] = 194,
  ["Atilde"] = 195,
  ["Auml"] = 196,
  ["Aring"] = 197,
  ["AElig"] = 198,
  ["Ccedil"] = 199,
  ["Egrave"] = 200,
  ["Eacute"] = 201,
  ["Ecirc"] = 202,
  ["Euml"] = 203,
  ["Igrave"] = 204,
  ["Iacute"] = 205,
  ["Icirc"] = 206,
  ["Iuml"] = 207,
  ["ETH"] = 208,
  ["Ntilde"] = 209,
  ["Ograve"] = 210,
  ["Oacute"] = 211,
  ["Ocirc"] = 212,
  ["Otilde"] = 213,
  ["Ouml"] = 214,
  ["times"] = 215,
  ["Oslash"] = 216,
  ["Ugrave"] = 217,
  ["Uacute"] = 218,
  ["Ucirc"] = 219,
  ["Uuml"] = 220,
  ["Yacute"] = 221,
  ["THORN"] = 222,
  ["szlig"] = 223,
  ["agrave"] = 224,
  ["aacute"] = 225,
  ["acirc"] = 226,
  ["atilde"] = 227,
  ["auml"] = 228,
  ["aring"] = 229,
  ["aelig"] = 230,
  ["ccedil"] = 231,
  ["egrave"] = 232,
  ["eacute"] = 233,
  ["ecirc"] = 234,
  ["euml"] = 235,
  ["igrave"] = 236,
  ["iacute"] = 237,
  ["icirc"] = 238,
  ["iuml"] = 239,
  ["eth"] = 240,
  ["ntilde"] = 241,
  ["ograve"] = 242,
  ["oacute"] = 243,
  ["ocirc"] = 244,
  ["otilde"] = 245,
  ["ouml"] = 246,
  ["divide"] = 247,
  ["div"] = 247,
  ["oslash"] = 248,
  ["ugrave"] = 249,
  ["uacute"] = 250,
  ["ucirc"] = 251,
  ["uuml"] = 252,
  ["yacute"] = 253,
  ["thorn"] = 254,
  ["yuml"] = 255,
  ["Amacr"] = 256,
  ["amacr"] = 257,
  ["Abreve"] = 258,
  ["abreve"] = 259,
  ["Aogon"] = 260,
  ["aogon"] = 261,
  ["Cacute"] = 262,
  ["cacute"] = 263,
  ["Ccirc"] = 264,
  ["ccirc"] = 265,
  ["Cdot"] = 266,
  ["cdot"] = 267,
  ["Ccaron"] = 268,
  ["ccaron"] = 269,
  ["Dcaron"] = 270,
  ["dcaron"] = 271,
  ["Dstrok"] = 272,
  ["dstrok"] = 273,
  ["Emacr"] = 274,
  ["emacr"] = 275,
  ["Edot"] = 278,
  ["edot"] = 279,
  ["Eogon"] = 280,
  ["eogon"] = 281,
  ["Ecaron"] = 282,
  ["ecaron"] = 283,
  ["Gcirc"] = 284,
  ["gcirc"] = 285,
  ["Gbreve"] = 286,
  ["gbreve"] = 287,
  ["Gdot"] = 288,
  ["gdot"] = 289,
  ["Gcedil"] = 290,
  ["Hcirc"] = 292,
  ["hcirc"] = 293,
  ["Hstrok"] = 294,
  ["hstrok"] = 295,
  ["Itilde"] = 296,
  ["itilde"] = 297,
  ["Imacr"] = 298,
  ["imacr"] = 299,
  ["Iogon"] = 302,
  ["iogon"] = 303,
  ["Idot"] = 304,
  ["imath"] = 305,
  ["inodot"] = 305,
  ["IJlig"] = 306,
  ["ijlig"] = 307,
  ["Jcirc"] = 308,
  ["jcirc"] = 309,
  ["Kcedil"] = 310,
  ["kcedil"] = 311,
  ["kgreen"] = 312,
  ["Lacute"] = 313,
  ["lacute"] = 314,
  ["Lcedil"] = 315,
  ["lcedil"] = 316,
  ["Lcaron"] = 317,
  ["lcaron"] = 318,
  ["Lmidot"] = 319,
  ["lmidot"] = 320,
  ["Lstrok"] = 321,
  ["lstrok"] = 322,
  ["Nacute"] = 323,
  ["nacute"] = 324,
  ["Ncedil"] = 325,
  ["ncedil"] = 326,
  ["Ncaron"] = 327,
  ["ncaron"] = 328,
  ["napos"] = 329,
  ["ENG"] = 330,
  ["eng"] = 331,
  ["Omacr"] = 332,
  ["omacr"] = 333,
  ["Odblac"] = 336,
  ["odblac"] = 337,
  ["OElig"] = 338,
  ["oelig"] = 339,
  ["Racute"] = 340,
  ["racute"] = 341,
  ["Rcedil"] = 342,
  ["rcedil"] = 343,
  ["Rcaron"] = 344,
  ["rcaron"] = 345,
  ["Sacute"] = 346,
  ["sacute"] = 347,
  ["Scirc"] = 348,
  ["scirc"] = 349,
  ["Scedil"] = 350,
  ["scedil"] = 351,
  ["Scaron"] = 352,
  ["scaron"] = 353,
  ["Tcedil"] = 354,
  ["tcedil"] = 355,
  ["Tcaron"] = 356,
  ["tcaron"] = 357,
  ["Tstrok"] = 358,
  ["tstrok"] = 359,
  ["Utilde"] = 360,
  ["utilde"] = 361,
  ["Umacr"] = 362,
  ["umacr"] = 363,
  ["Ubreve"] = 364,
  ["ubreve"] = 365,
  ["Uring"] = 366,
  ["uring"] = 367,
  ["Udblac"] = 368,
  ["udblac"] = 369,
  ["Uogon"] = 370,
  ["uogon"] = 371,
  ["Wcirc"] = 372,
  ["wcirc"] = 373,
  ["Ycirc"] = 374,
  ["ycirc"] = 375,
  ["Yuml"] = 376,
  ["Zacute"] = 377,
  ["zacute"] = 378,
  ["Zdot"] = 379,
  ["zdot"] = 380,
  ["Zcaron"] = 381,
  ["zcaron"] = 382,
  ["fnof"] = 402,
  ["imped"] = 437,
  ["gacute"] = 501,
  ["jmath"] = 567,
  ["circ"] = 710,
  ["caron"] = 711,
  ["Hacek"] = 711,
  ["breve"] = 728,
  ["Breve"] = 728,
  ["dot"] = 729,
  ["DiacriticalDot"] = 729,
  ["ring"] = 730,
  ["ogon"] = 731,
  ["tilde"] = 732,
  ["DiacriticalTilde"] = 732,
  ["dblac"] = 733,
  ["DiacriticalDoubleAcute"] = 733,
  ["DownBreve"] = 785,
  ["UnderBar"] = 818,
  ["Alpha"] = 913,
  ["Beta"] = 914,
  ["Gamma"] = 915,
  ["Delta"] = 916,
  ["Epsilon"] = 917,
  ["Zeta"] = 918,
  ["Eta"] = 919,
  ["Theta"] = 920,
  ["Iota"] = 921,
  ["Kappa"] = 922,
  ["Lambda"] = 923,
  ["Mu"] = 924,
  ["Nu"] = 925,
  ["Xi"] = 926,
  ["Omicron"] = 927,
  ["Pi"] = 928,
  ["Rho"] = 929,
  ["Sigma"] = 931,
  ["Tau"] = 932,
  ["Upsilon"] = 933,
  ["Phi"] = 934,
  ["Chi"] = 935,
  ["Psi"] = 936,
  ["Omega"] = 937,
  ["alpha"] = 945,
  ["beta"] = 946,
  ["gamma"] = 947,
  ["delta"] = 948,
  ["epsiv"] = 949,
  ["varepsilon"] = 949,
  ["epsilon"] = 949,
  ["zeta"] = 950,
  ["eta"] = 951,
  ["theta"] = 952,
  ["iota"] = 953,
  ["kappa"] = 954,
  ["lambda"] = 955,
  ["mu"] = 956,
  ["nu"] = 957,
  ["xi"] = 958,
  ["omicron"] = 959,
  ["pi"] = 960,
  ["rho"] = 961,
  ["sigmav"] = 962,
  ["varsigma"] = 962,
  ["sigmaf"] = 962,
  ["sigma"] = 963,
  ["tau"] = 964,
  ["upsi"] = 965,
  ["upsilon"] = 965,
  ["phi"] = 966,
  ["phiv"] = 966,
  ["varphi"] = 966,
  ["chi"] = 967,
  ["psi"] = 968,
  ["omega"] = 969,
  ["thetav"] = 977,
  ["vartheta"] = 977,
  ["thetasym"] = 977,
  ["Upsi"] = 978,
  ["upsih"] = 978,
  ["straightphi"] = 981,
  ["piv"] = 982,
  ["varpi"] = 982,
  ["Gammad"] = 988,
  ["gammad"] = 989,
  ["digamma"] = 989,
  ["kappav"] = 1008,
  ["varkappa"] = 1008,
  ["rhov"] = 1009,
  ["varrho"] = 1009,
  ["epsi"] = 1013,
  ["straightepsilon"] = 1013,
  ["bepsi"] = 1014,
  ["backepsilon"] = 1014,
  ["IOcy"] = 1025,
  ["DJcy"] = 1026,
  ["GJcy"] = 1027,
  ["Jukcy"] = 1028,
  ["DScy"] = 1029,
  ["Iukcy"] = 1030,
  ["YIcy"] = 1031,
  ["Jsercy"] = 1032,
  ["LJcy"] = 1033,
  ["NJcy"] = 1034,
  ["TSHcy"] = 1035,
  ["KJcy"] = 1036,
  ["Ubrcy"] = 1038,
  ["DZcy"] = 1039,
  ["Acy"] = 1040,
  ["Bcy"] = 1041,
  ["Vcy"] = 1042,
  ["Gcy"] = 1043,
  ["Dcy"] = 1044,
  ["IEcy"] = 1045,
  ["ZHcy"] = 1046,
  ["Zcy"] = 1047,
  ["Icy"] = 1048,
  ["Jcy"] = 1049,
  ["Kcy"] = 1050,
  ["Lcy"] = 1051,
  ["Mcy"] = 1052,
  ["Ncy"] = 1053,
  ["Ocy"] = 1054,
  ["Pcy"] = 1055,
  ["Rcy"] = 1056,
  ["Scy"] = 1057,
  ["Tcy"] = 1058,
  ["Ucy"] = 1059,
  ["Fcy"] = 1060,
  ["KHcy"] = 1061,
  ["TScy"] = 1062,
  ["CHcy"] = 1063,
  ["SHcy"] = 1064,
  ["SHCHcy"] = 1065,
  ["HARDcy"] = 1066,
  ["Ycy"] = 1067,
  ["SOFTcy"] = 1068,
  ["Ecy"] = 1069,
  ["YUcy"] = 1070,
  ["YAcy"] = 1071,
  ["acy"] = 1072,
  ["bcy"] = 1073,
  ["vcy"] = 1074,
  ["gcy"] = 1075,
  ["dcy"] = 1076,
  ["iecy"] = 1077,
  ["zhcy"] = 1078,
  ["zcy"] = 1079,
  ["icy"] = 1080,
  ["jcy"] = 1081,
  ["kcy"] = 1082,
  ["lcy"] = 1083,
  ["mcy"] = 1084,
  ["ncy"] = 1085,
  ["ocy"] = 1086,
  ["pcy"] = 1087,
  ["rcy"] = 1088,
  ["scy"] = 1089,
  ["tcy"] = 1090,
  ["ucy"] = 1091,
  ["fcy"] = 1092,
  ["khcy"] = 1093,
  ["tscy"] = 1094,
  ["chcy"] = 1095,
  ["shcy"] = 1096,
  ["shchcy"] = 1097,
  ["hardcy"] = 1098,
  ["ycy"] = 1099,
  ["softcy"] = 1100,
  ["ecy"] = 1101,
  ["yucy"] = 1102,
  ["yacy"] = 1103,
  ["iocy"] = 1105,
  ["djcy"] = 1106,
  ["gjcy"] = 1107,
  ["jukcy"] = 1108,
  ["dscy"] = 1109,
  ["iukcy"] = 1110,
  ["yicy"] = 1111,
  ["jsercy"] = 1112,
  ["ljcy"] = 1113,
  ["njcy"] = 1114,
  ["tshcy"] = 1115,
  ["kjcy"] = 1116,
  ["ubrcy"] = 1118,
  ["dzcy"] = 1119,
  ["ensp"] = 8194,
  ["emsp"] = 8195,
  ["emsp13"] = 8196,
  ["emsp14"] = 8197,
  ["numsp"] = 8199,
  ["puncsp"] = 8200,
  ["thinsp"] = 8201,
  ["ThinSpace"] = 8201,
  ["hairsp"] = 8202,
  ["VeryThinSpace"] = 8202,
  ["ZeroWidthSpace"] = 8203,
  ["NegativeVeryThinSpace"] = 8203,
  ["NegativeThinSpace"] = 8203,
  ["NegativeMediumSpace"] = 8203,
  ["NegativeThickSpace"] = 8203,
  ["zwnj"] = 8204,
  ["zwj"] = 8205,
  ["lrm"] = 8206,
  ["rlm"] = 8207,
  ["hyphen"] = 8208,
  ["dash"] = 8208,
  ["ndash"] = 8211,
  ["mdash"] = 8212,
  ["horbar"] = 8213,
  ["Verbar"] = 8214,
  ["Vert"] = 8214,
  ["lsquo"] = 8216,
  ["OpenCurlyQuote"] = 8216,
  ["rsquo"] = 8217,
  ["rsquor"] = 8217,
  ["CloseCurlyQuote"] = 8217,
  ["lsquor"] = 8218,
  ["sbquo"] = 8218,
  ["ldquo"] = 8220,
  ["OpenCurlyDoubleQuote"] = 8220,
  ["rdquo"] = 8221,
  ["rdquor"] = 8221,
  ["CloseCurlyDoubleQuote"] = 8221,
  ["ldquor"] = 8222,
  ["bdquo"] = 8222,
  ["dagger"] = 8224,
  ["Dagger"] = 8225,
  ["ddagger"] = 8225,
  ["bull"] = 8226,
  ["bullet"] = 8226,
  ["nldr"] = 8229,
  ["hellip"] = 8230,
  ["mldr"] = 8230,
  ["permil"] = 8240,
  ["pertenk"] = 8241,
  ["prime"] = 8242,
  ["Prime"] = 8243,
  ["tprime"] = 8244,
  ["bprime"] = 8245,
  ["backprime"] = 8245,
  ["lsaquo"] = 8249,
  ["rsaquo"] = 8250,
  ["oline"] = 8254,
  ["caret"] = 8257,
  ["hybull"] = 8259,
  ["frasl"] = 8260,
  ["bsemi"] = 8271,
  ["qprime"] = 8279,
  ["MediumSpace"] = 8287,
  ["NoBreak"] = 8288,
  ["ApplyFunction"] = 8289,
  ["af"] = 8289,
  ["InvisibleTimes"] = 8290,
  ["it"] = 8290,
  ["InvisibleComma"] = 8291,
  ["ic"] = 8291,
  ["euro"] = 8364,
  ["tdot"] = 8411,
  ["TripleDot"] = 8411,
  ["DotDot"] = 8412,
  ["Copf"] = 8450,
  ["complexes"] = 8450,
  ["incare"] = 8453,
  ["gscr"] = 8458,
  ["hamilt"] = 8459,
  ["HilbertSpace"] = 8459,
  ["Hscr"] = 8459,
  ["Hfr"] = 8460,
  ["Poincareplane"] = 8460,
  ["quaternions"] = 8461,
  ["Hopf"] = 8461,
  ["planckh"] = 8462,
  ["planck"] = 8463,
  ["hbar"] = 8463,
  ["plankv"] = 8463,
  ["hslash"] = 8463,
  ["Iscr"] = 8464,
  ["imagline"] = 8464,
  ["image"] = 8465,
  ["Im"] = 8465,
  ["imagpart"] = 8465,
  ["Ifr"] = 8465,
  ["Lscr"] = 8466,
  ["lagran"] = 8466,
  ["Laplacetrf"] = 8466,
  ["ell"] = 8467,
  ["Nopf"] = 8469,
  ["naturals"] = 8469,
  ["numero"] = 8470,
  ["copysr"] = 8471,
  ["weierp"] = 8472,
  ["wp"] = 8472,
  ["Popf"] = 8473,
  ["primes"] = 8473,
  ["rationals"] = 8474,
  ["Qopf"] = 8474,
  ["Rscr"] = 8475,
  ["realine"] = 8475,
  ["real"] = 8476,
  ["Re"] = 8476,
  ["realpart"] = 8476,
  ["Rfr"] = 8476,
  ["reals"] = 8477,
  ["Ropf"] = 8477,
  ["rx"] = 8478,
  ["trade"] = 8482,
  ["TRADE"] = 8482,
  ["integers"] = 8484,
  ["Zopf"] = 8484,
  ["ohm"] = 8486,
  ["mho"] = 8487,
  ["Zfr"] = 8488,
  ["zeetrf"] = 8488,
  ["iiota"] = 8489,
  ["angst"] = 8491,
  ["bernou"] = 8492,
  ["Bernoullis"] = 8492,
  ["Bscr"] = 8492,
  ["Cfr"] = 8493,
  ["Cayleys"] = 8493,
  ["escr"] = 8495,
  ["Escr"] = 8496,
  ["expectation"] = 8496,
  ["Fscr"] = 8497,
  ["Fouriertrf"] = 8497,
  ["phmmat"] = 8499,
  ["Mellintrf"] = 8499,
  ["Mscr"] = 8499,
  ["order"] = 8500,
  ["orderof"] = 8500,
  ["oscr"] = 8500,
  ["alefsym"] = 8501,
  ["aleph"] = 8501,
  ["beth"] = 8502,
  ["gimel"] = 8503,
  ["daleth"] = 8504,
  ["CapitalDifferentialD"] = 8517,
  ["DD"] = 8517,
  ["DifferentialD"] = 8518,
  ["dd"] = 8518,
  ["ExponentialE"] = 8519,
  ["exponentiale"] = 8519,
  ["ee"] = 8519,
  ["ImaginaryI"] = 8520,
  ["ii"] = 8520,
  ["frac13"] = 8531,
  ["frac23"] = 8532,
  ["frac15"] = 8533,
  ["frac25"] = 8534,
  ["frac35"] = 8535,
  ["frac45"] = 8536,
  ["frac16"] = 8537,
  ["frac56"] = 8538,
  ["frac18"] = 8539,
  ["frac38"] = 8540,
  ["frac58"] = 8541,
  ["frac78"] = 8542,
  ["larr"] = 8592,
  ["leftarrow"] = 8592,
  ["LeftArrow"] = 8592,
  ["slarr"] = 8592,
  ["ShortLeftArrow"] = 8592,
  ["uarr"] = 8593,
  ["uparrow"] = 8593,
  ["UpArrow"] = 8593,
  ["ShortUpArrow"] = 8593,
  ["rarr"] = 8594,
  ["rightarrow"] = 8594,
  ["RightArrow"] = 8594,
  ["srarr"] = 8594,
  ["ShortRightArrow"] = 8594,
  ["darr"] = 8595,
  ["downarrow"] = 8595,
  ["DownArrow"] = 8595,
  ["ShortDownArrow"] = 8595,
  ["harr"] = 8596,
  ["leftrightarrow"] = 8596,
  ["LeftRightArrow"] = 8596,
  ["varr"] = 8597,
  ["updownarrow"] = 8597,
  ["UpDownArrow"] = 8597,
  ["nwarr"] = 8598,
  ["UpperLeftArrow"] = 8598,
  ["nwarrow"] = 8598,
  ["nearr"] = 8599,
  ["UpperRightArrow"] = 8599,
  ["nearrow"] = 8599,
  ["searr"] = 8600,
  ["searrow"] = 8600,
  ["LowerRightArrow"] = 8600,
  ["swarr"] = 8601,
  ["swarrow"] = 8601,
  ["LowerLeftArrow"] = 8601,
  ["nlarr"] = 8602,
  ["nleftarrow"] = 8602,
  ["nrarr"] = 8603,
  ["nrightarrow"] = 8603,
  ["rarrw"] = 8605,
  ["rightsquigarrow"] = 8605,
  ["Larr"] = 8606,
  ["twoheadleftarrow"] = 8606,
  ["Uarr"] = 8607,
  ["Rarr"] = 8608,
  ["twoheadrightarrow"] = 8608,
  ["Darr"] = 8609,
  ["larrtl"] = 8610,
  ["leftarrowtail"] = 8610,
  ["rarrtl"] = 8611,
  ["rightarrowtail"] = 8611,
  ["LeftTeeArrow"] = 8612,
  ["mapstoleft"] = 8612,
  ["UpTeeArrow"] = 8613,
  ["mapstoup"] = 8613,
  ["map"] = 8614,
  ["RightTeeArrow"] = 8614,
  ["mapsto"] = 8614,
  ["DownTeeArrow"] = 8615,
  ["mapstodown"] = 8615,
  ["larrhk"] = 8617,
  ["hookleftarrow"] = 8617,
  ["rarrhk"] = 8618,
  ["hookrightarrow"] = 8618,
  ["larrlp"] = 8619,
  ["looparrowleft"] = 8619,
  ["rarrlp"] = 8620,
  ["looparrowright"] = 8620,
  ["harrw"] = 8621,
  ["leftrightsquigarrow"] = 8621,
  ["nharr"] = 8622,
  ["nleftrightarrow"] = 8622,
  ["lsh"] = 8624,
  ["Lsh"] = 8624,
  ["rsh"] = 8625,
  ["Rsh"] = 8625,
  ["ldsh"] = 8626,
  ["rdsh"] = 8627,
  ["crarr"] = 8629,
  ["cularr"] = 8630,
  ["curvearrowleft"] = 8630,
  ["curarr"] = 8631,
  ["curvearrowright"] = 8631,
  ["olarr"] = 8634,
  ["circlearrowleft"] = 8634,
  ["orarr"] = 8635,
  ["circlearrowright"] = 8635,
  ["lharu"] = 8636,
  ["LeftVector"] = 8636,
  ["leftharpoonup"] = 8636,
  ["lhard"] = 8637,
  ["leftharpoondown"] = 8637,
  ["DownLeftVector"] = 8637,
  ["uharr"] = 8638,
  ["upharpoonright"] = 8638,
  ["RightUpVector"] = 8638,
  ["uharl"] = 8639,
  ["upharpoonleft"] = 8639,
  ["LeftUpVector"] = 8639,
  ["rharu"] = 8640,
  ["RightVector"] = 8640,
  ["rightharpoonup"] = 8640,
  ["rhard"] = 8641,
  ["rightharpoondown"] = 8641,
  ["DownRightVector"] = 8641,
  ["dharr"] = 8642,
  ["RightDownVector"] = 8642,
  ["downharpoonright"] = 8642,
  ["dharl"] = 8643,
  ["LeftDownVector"] = 8643,
  ["downharpoonleft"] = 8643,
  ["rlarr"] = 8644,
  ["rightleftarrows"] = 8644,
  ["RightArrowLeftArrow"] = 8644,
  ["udarr"] = 8645,
  ["UpArrowDownArrow"] = 8645,
  ["lrarr"] = 8646,
  ["leftrightarrows"] = 8646,
  ["LeftArrowRightArrow"] = 8646,
  ["llarr"] = 8647,
  ["leftleftarrows"] = 8647,
  ["uuarr"] = 8648,
  ["upuparrows"] = 8648,
  ["rrarr"] = 8649,
  ["rightrightarrows"] = 8649,
  ["ddarr"] = 8650,
  ["downdownarrows"] = 8650,
  ["lrhar"] = 8651,
  ["ReverseEquilibrium"] = 8651,
  ["leftrightharpoons"] = 8651,
  ["rlhar"] = 8652,
  ["rightleftharpoons"] = 8652,
  ["Equilibrium"] = 8652,
  ["nlArr"] = 8653,
  ["nLeftarrow"] = 8653,
  ["nhArr"] = 8654,
  ["nLeftrightarrow"] = 8654,
  ["nrArr"] = 8655,
  ["nRightarrow"] = 8655,
  ["lArr"] = 8656,
  ["Leftarrow"] = 8656,
  ["DoubleLeftArrow"] = 8656,
  ["uArr"] = 8657,
  ["Uparrow"] = 8657,
  ["DoubleUpArrow"] = 8657,
  ["rArr"] = 8658,
  ["Rightarrow"] = 8658,
  ["Implies"] = 8658,
  ["DoubleRightArrow"] = 8658,
  ["dArr"] = 8659,
  ["Downarrow"] = 8659,
  ["DoubleDownArrow"] = 8659,
  ["hArr"] = 8660,
  ["Leftrightarrow"] = 8660,
  ["DoubleLeftRightArrow"] = 8660,
  ["iff"] = 8660,
  ["vArr"] = 8661,
  ["Updownarrow"] = 8661,
  ["DoubleUpDownArrow"] = 8661,
  ["nwArr"] = 8662,
  ["neArr"] = 8663,
  ["seArr"] = 8664,
  ["swArr"] = 8665,
  ["lAarr"] = 8666,
  ["Lleftarrow"] = 8666,
  ["rAarr"] = 8667,
  ["Rrightarrow"] = 8667,
  ["zigrarr"] = 8669,
  ["larrb"] = 8676,
  ["LeftArrowBar"] = 8676,
  ["rarrb"] = 8677,
  ["RightArrowBar"] = 8677,
  ["duarr"] = 8693,
  ["DownArrowUpArrow"] = 8693,
  ["loarr"] = 8701,
  ["roarr"] = 8702,
  ["hoarr"] = 8703,
  ["forall"] = 8704,
  ["ForAll"] = 8704,
  ["comp"] = 8705,
  ["complement"] = 8705,
  ["part"] = 8706,
  ["PartialD"] = 8706,
  ["exist"] = 8707,
  ["Exists"] = 8707,
  ["nexist"] = 8708,
  ["NotExists"] = 8708,
  ["nexists"] = 8708,
  ["empty"] = 8709,
  ["emptyset"] = 8709,
  ["emptyv"] = 8709,
  ["varnothing"] = 8709,
  ["nabla"] = 8711,
  ["Del"] = 8711,
  ["isin"] = 8712,
  ["isinv"] = 8712,
  ["Element"] = 8712,
  ["in"] = 8712,
  ["notin"] = 8713,
  ["NotElement"] = 8713,
  ["notinva"] = 8713,
  ["niv"] = 8715,
  ["ReverseElement"] = 8715,
  ["ni"] = 8715,
  ["SuchThat"] = 8715,
  ["notni"] = 8716,
  ["notniva"] = 8716,
  ["NotReverseElement"] = 8716,
  ["prod"] = 8719,
  ["Product"] = 8719,
  ["coprod"] = 8720,
  ["Coproduct"] = 8720,
  ["sum"] = 8721,
  ["Sum"] = 8721,
  ["minus"] = 8722,
  ["mnplus"] = 8723,
  ["mp"] = 8723,
  ["MinusPlus"] = 8723,
  ["plusdo"] = 8724,
  ["dotplus"] = 8724,
  ["setmn"] = 8726,
  ["setminus"] = 8726,
  ["Backslash"] = 8726,
  ["ssetmn"] = 8726,
  ["smallsetminus"] = 8726,
  ["lowast"] = 8727,
  ["compfn"] = 8728,
  ["SmallCircle"] = 8728,
  ["radic"] = 8730,
  ["Sqrt"] = 8730,
  ["prop"] = 8733,
  ["propto"] = 8733,
  ["Proportional"] = 8733,
  ["vprop"] = 8733,
  ["varpropto"] = 8733,
  ["infin"] = 8734,
  ["angrt"] = 8735,
  ["ang"] = 8736,
  ["angle"] = 8736,
  ["angmsd"] = 8737,
  ["measuredangle"] = 8737,
  ["angsph"] = 8738,
  ["mid"] = 8739,
  ["VerticalBar"] = 8739,
  ["smid"] = 8739,
  ["shortmid"] = 8739,
  ["nmid"] = 8740,
  ["NotVerticalBar"] = 8740,
  ["nsmid"] = 8740,
  ["nshortmid"] = 8740,
  ["par"] = 8741,
  ["parallel"] = 8741,
  ["DoubleVerticalBar"] = 8741,
  ["spar"] = 8741,
  ["shortparallel"] = 8741,
  ["npar"] = 8742,
  ["nparallel"] = 8742,
  ["NotDoubleVerticalBar"] = 8742,
  ["nspar"] = 8742,
  ["nshortparallel"] = 8742,
  ["and"] = 8743,
  ["wedge"] = 8743,
  ["or"] = 8744,
  ["vee"] = 8744,
  ["cap"] = 8745,
  ["cup"] = 8746,
  ["int"] = 8747,
  ["Integral"] = 8747,
  ["Int"] = 8748,
  ["tint"] = 8749,
  ["iiint"] = 8749,
  ["conint"] = 8750,
  ["oint"] = 8750,
  ["ContourIntegral"] = 8750,
  ["Conint"] = 8751,
  ["DoubleContourIntegral"] = 8751,
  ["Cconint"] = 8752,
  ["cwint"] = 8753,
  ["cwconint"] = 8754,
  ["ClockwiseContourIntegral"] = 8754,
  ["awconint"] = 8755,
  ["CounterClockwiseContourIntegral"] = 8755,
  ["there4"] = 8756,
  ["therefore"] = 8756,
  ["Therefore"] = 8756,
  ["becaus"] = 8757,
  ["because"] = 8757,
  ["Because"] = 8757,
  ["ratio"] = 8758,
  ["Colon"] = 8759,
  ["Proportion"] = 8759,
  ["minusd"] = 8760,
  ["dotminus"] = 8760,
  ["mDDot"] = 8762,
  ["homtht"] = 8763,
  ["sim"] = 8764,
  ["Tilde"] = 8764,
  ["thksim"] = 8764,
  ["thicksim"] = 8764,
  ["bsim"] = 8765,
  ["backsim"] = 8765,
  ["ac"] = 8766,
  ["mstpos"] = 8766,
  ["acd"] = 8767,
  ["wreath"] = 8768,
  ["VerticalTilde"] = 8768,
  ["wr"] = 8768,
  ["nsim"] = 8769,
  ["NotTilde"] = 8769,
  ["esim"] = 8770,
  ["EqualTilde"] = 8770,
  ["eqsim"] = 8770,
  ["sime"] = 8771,
  ["TildeEqual"] = 8771,
  ["simeq"] = 8771,
  ["nsime"] = 8772,
  ["nsimeq"] = 8772,
  ["NotTildeEqual"] = 8772,
  ["cong"] = 8773,
  ["TildeFullEqual"] = 8773,
  ["simne"] = 8774,
  ["ncong"] = 8775,
  ["NotTildeFullEqual"] = 8775,
  ["asymp"] = 8776,
  ["ap"] = 8776,
  ["TildeTilde"] = 8776,
  ["approx"] = 8776,
  ["thkap"] = 8776,
  ["thickapprox"] = 8776,
  ["nap"] = 8777,
  ["NotTildeTilde"] = 8777,
  ["napprox"] = 8777,
  ["ape"] = 8778,
  ["approxeq"] = 8778,
  ["apid"] = 8779,
  ["bcong"] = 8780,
  ["backcong"] = 8780,
  ["asympeq"] = 8781,
  ["CupCap"] = 8781,
  ["bump"] = 8782,
  ["HumpDownHump"] = 8782,
  ["Bumpeq"] = 8782,
  ["bumpe"] = 8783,
  ["HumpEqual"] = 8783,
  ["bumpeq"] = 8783,
  ["esdot"] = 8784,
  ["DotEqual"] = 8784,
  ["doteq"] = 8784,
  ["eDot"] = 8785,
  ["doteqdot"] = 8785,
  ["efDot"] = 8786,
  ["fallingdotseq"] = 8786,
  ["erDot"] = 8787,
  ["risingdotseq"] = 8787,
  ["colone"] = 8788,
  ["coloneq"] = 8788,
  ["Assign"] = 8788,
  ["ecolon"] = 8789,
  ["eqcolon"] = 8789,
  ["ecir"] = 8790,
  ["eqcirc"] = 8790,
  ["cire"] = 8791,
  ["circeq"] = 8791,
  ["wedgeq"] = 8793,
  ["veeeq"] = 8794,
  ["trie"] = 8796,
  ["triangleq"] = 8796,
  ["equest"] = 8799,
  ["questeq"] = 8799,
  ["ne"] = 8800,
  ["NotEqual"] = 8800,
  ["equiv"] = 8801,
  ["Congruent"] = 8801,
  ["nequiv"] = 8802,
  ["NotCongruent"] = 8802,
  ["le"] = 8804,
  ["leq"] = 8804,
  ["ge"] = 8805,
  ["GreaterEqual"] = 8805,
  ["geq"] = 8805,
  ["lE"] = 8806,
  ["LessFullEqual"] = 8806,
  ["leqq"] = 8806,
  ["gE"] = 8807,
  ["GreaterFullEqual"] = 8807,
  ["geqq"] = 8807,
  ["lnE"] = 8808,
  ["lneqq"] = 8808,
  ["gnE"] = 8809,
  ["gneqq"] = 8809,
  ["Lt"] = 8810,
  ["NestedLessLess"] = 8810,
  ["ll"] = 8810,
  ["Gt"] = 8811,
  ["NestedGreaterGreater"] = 8811,
  ["gg"] = 8811,
  ["twixt"] = 8812,
  ["between"] = 8812,
  ["NotCupCap"] = 8813,
  ["nlt"] = 8814,
  ["NotLess"] = 8814,
  ["nless"] = 8814,
  ["ngt"] = 8815,
  ["NotGreater"] = 8815,
  ["ngtr"] = 8815,
  ["nle"] = 8816,
  ["NotLessEqual"] = 8816,
  ["nleq"] = 8816,
  ["nge"] = 8817,
  ["NotGreaterEqual"] = 8817,
  ["ngeq"] = 8817,
  ["lsim"] = 8818,
  ["LessTilde"] = 8818,
  ["lesssim"] = 8818,
  ["gsim"] = 8819,
  ["gtrsim"] = 8819,
  ["GreaterTilde"] = 8819,
  ["nlsim"] = 8820,
  ["NotLessTilde"] = 8820,
  ["ngsim"] = 8821,
  ["NotGreaterTilde"] = 8821,
  ["lg"] = 8822,
  ["lessgtr"] = 8822,
  ["LessGreater"] = 8822,
  ["gl"] = 8823,
  ["gtrless"] = 8823,
  ["GreaterLess"] = 8823,
  ["ntlg"] = 8824,
  ["NotLessGreater"] = 8824,
  ["ntgl"] = 8825,
  ["NotGreaterLess"] = 8825,
  ["pr"] = 8826,
  ["Precedes"] = 8826,
  ["prec"] = 8826,
  ["sc"] = 8827,
  ["Succeeds"] = 8827,
  ["succ"] = 8827,
  ["prcue"] = 8828,
  ["PrecedesSlantEqual"] = 8828,
  ["preccurlyeq"] = 8828,
  ["sccue"] = 8829,
  ["SucceedsSlantEqual"] = 8829,
  ["succcurlyeq"] = 8829,
  ["prsim"] = 8830,
  ["precsim"] = 8830,
  ["PrecedesTilde"] = 8830,
  ["scsim"] = 8831,
  ["succsim"] = 8831,
  ["SucceedsTilde"] = 8831,
  ["npr"] = 8832,
  ["nprec"] = 8832,
  ["NotPrecedes"] = 8832,
  ["nsc"] = 8833,
  ["nsucc"] = 8833,
  ["NotSucceeds"] = 8833,
  ["sub"] = 8834,
  ["subset"] = 8834,
  ["sup"] = 8835,
  ["supset"] = 8835,
  ["Superset"] = 8835,
  ["nsub"] = 8836,
  ["nsup"] = 8837,
  ["sube"] = 8838,
  ["SubsetEqual"] = 8838,
  ["subseteq"] = 8838,
  ["supe"] = 8839,
  ["supseteq"] = 8839,
  ["SupersetEqual"] = 8839,
  ["nsube"] = 8840,
  ["nsubseteq"] = 8840,
  ["NotSubsetEqual"] = 8840,
  ["nsupe"] = 8841,
  ["nsupseteq"] = 8841,
  ["NotSupersetEqual"] = 8841,
  ["subne"] = 8842,
  ["subsetneq"] = 8842,
  ["supne"] = 8843,
  ["supsetneq"] = 8843,
  ["cupdot"] = 8845,
  ["uplus"] = 8846,
  ["UnionPlus"] = 8846,
  ["sqsub"] = 8847,
  ["SquareSubset"] = 8847,
  ["sqsubset"] = 8847,
  ["sqsup"] = 8848,
  ["SquareSuperset"] = 8848,
  ["sqsupset"] = 8848,
  ["sqsube"] = 8849,
  ["SquareSubsetEqual"] = 8849,
  ["sqsubseteq"] = 8849,
  ["sqsupe"] = 8850,
  ["SquareSupersetEqual"] = 8850,
  ["sqsupseteq"] = 8850,
  ["sqcap"] = 8851,
  ["SquareIntersection"] = 8851,
  ["sqcup"] = 8852,
  ["SquareUnion"] = 8852,
  ["oplus"] = 8853,
  ["CirclePlus"] = 8853,
  ["ominus"] = 8854,
  ["CircleMinus"] = 8854,
  ["otimes"] = 8855,
  ["CircleTimes"] = 8855,
  ["osol"] = 8856,
  ["odot"] = 8857,
  ["CircleDot"] = 8857,
  ["ocir"] = 8858,
  ["circledcirc"] = 8858,
  ["oast"] = 8859,
  ["circledast"] = 8859,
  ["odash"] = 8861,
  ["circleddash"] = 8861,
  ["plusb"] = 8862,
  ["boxplus"] = 8862,
  ["minusb"] = 8863,
  ["boxminus"] = 8863,
  ["timesb"] = 8864,
  ["boxtimes"] = 8864,
  ["sdotb"] = 8865,
  ["dotsquare"] = 8865,
  ["vdash"] = 8866,
  ["RightTee"] = 8866,
  ["dashv"] = 8867,
  ["LeftTee"] = 8867,
  ["top"] = 8868,
  ["DownTee"] = 8868,
  ["bottom"] = 8869,
  ["bot"] = 8869,
  ["perp"] = 8869,
  ["UpTee"] = 8869,
  ["models"] = 8871,
  ["vDash"] = 8872,
  ["DoubleRightTee"] = 8872,
  ["Vdash"] = 8873,
  ["Vvdash"] = 8874,
  ["VDash"] = 8875,
  ["nvdash"] = 8876,
  ["nvDash"] = 8877,
  ["nVdash"] = 8878,
  ["nVDash"] = 8879,
  ["prurel"] = 8880,
  ["vltri"] = 8882,
  ["vartriangleleft"] = 8882,
  ["LeftTriangle"] = 8882,
  ["vrtri"] = 8883,
  ["vartriangleright"] = 8883,
  ["RightTriangle"] = 8883,
  ["ltrie"] = 8884,
  ["trianglelefteq"] = 8884,
  ["LeftTriangleEqual"] = 8884,
  ["rtrie"] = 8885,
  ["trianglerighteq"] = 8885,
  ["RightTriangleEqual"] = 8885,
  ["origof"] = 8886,
  ["imof"] = 8887,
  ["mumap"] = 8888,
  ["multimap"] = 8888,
  ["hercon"] = 8889,
  ["intcal"] = 8890,
  ["intercal"] = 8890,
  ["veebar"] = 8891,
  ["barvee"] = 8893,
  ["angrtvb"] = 8894,
  ["lrtri"] = 8895,
  ["xwedge"] = 8896,
  ["Wedge"] = 8896,
  ["bigwedge"] = 8896,
  ["xvee"] = 8897,
  ["Vee"] = 8897,
  ["bigvee"] = 8897,
  ["xcap"] = 8898,
  ["Intersection"] = 8898,
  ["bigcap"] = 8898,
  ["xcup"] = 8899,
  ["Union"] = 8899,
  ["bigcup"] = 8899,
  ["diam"] = 8900,
  ["diamond"] = 8900,
  ["Diamond"] = 8900,
  ["sdot"] = 8901,
  ["sstarf"] = 8902,
  ["Star"] = 8902,
  ["divonx"] = 8903,
  ["divideontimes"] = 8903,
  ["bowtie"] = 8904,
  ["ltimes"] = 8905,
  ["rtimes"] = 8906,
  ["lthree"] = 8907,
  ["leftthreetimes"] = 8907,
  ["rthree"] = 8908,
  ["rightthreetimes"] = 8908,
  ["bsime"] = 8909,
  ["backsimeq"] = 8909,
  ["cuvee"] = 8910,
  ["curlyvee"] = 8910,
  ["cuwed"] = 8911,
  ["curlywedge"] = 8911,
  ["Sub"] = 8912,
  ["Subset"] = 8912,
  ["Sup"] = 8913,
  ["Supset"] = 8913,
  ["Cap"] = 8914,
  ["Cup"] = 8915,
  ["fork"] = 8916,
  ["pitchfork"] = 8916,
  ["epar"] = 8917,
  ["ltdot"] = 8918,
  ["lessdot"] = 8918,
  ["gtdot"] = 8919,
  ["gtrdot"] = 8919,
  ["Ll"] = 8920,
  ["Gg"] = 8921,
  ["ggg"] = 8921,
  ["leg"] = 8922,
  ["LessEqualGreater"] = 8922,
  ["lesseqgtr"] = 8922,
  ["gel"] = 8923,
  ["gtreqless"] = 8923,
  ["GreaterEqualLess"] = 8923,
  ["cuepr"] = 8926,
  ["curlyeqprec"] = 8926,
  ["cuesc"] = 8927,
  ["curlyeqsucc"] = 8927,
  ["nprcue"] = 8928,
  ["NotPrecedesSlantEqual"] = 8928,
  ["nsccue"] = 8929,
  ["NotSucceedsSlantEqual"] = 8929,
  ["nsqsube"] = 8930,
  ["NotSquareSubsetEqual"] = 8930,
  ["nsqsupe"] = 8931,
  ["NotSquareSupersetEqual"] = 8931,
  ["lnsim"] = 8934,
  ["gnsim"] = 8935,
  ["prnsim"] = 8936,
  ["precnsim"] = 8936,
  ["scnsim"] = 8937,
  ["succnsim"] = 8937,
  ["nltri"] = 8938,
  ["ntriangleleft"] = 8938,
  ["NotLeftTriangle"] = 8938,
  ["nrtri"] = 8939,
  ["ntriangleright"] = 8939,
  ["NotRightTriangle"] = 8939,
  ["nltrie"] = 8940,
  ["ntrianglelefteq"] = 8940,
  ["NotLeftTriangleEqual"] = 8940,
  ["nrtrie"] = 8941,
  ["ntrianglerighteq"] = 8941,
  ["NotRightTriangleEqual"] = 8941,
  ["vellip"] = 8942,
  ["ctdot"] = 8943,
  ["utdot"] = 8944,
  ["dtdot"] = 8945,
  ["disin"] = 8946,
  ["isinsv"] = 8947,
  ["isins"] = 8948,
  ["isindot"] = 8949,
  ["notinvc"] = 8950,
  ["notinvb"] = 8951,
  ["isinE"] = 8953,
  ["nisd"] = 8954,
  ["xnis"] = 8955,
  ["nis"] = 8956,
  ["notnivc"] = 8957,
  ["notnivb"] = 8958,
  ["barwed"] = 8965,
  ["barwedge"] = 8965,
  ["Barwed"] = 8966,
  ["doublebarwedge"] = 8966,
  ["lceil"] = 8968,
  ["LeftCeiling"] = 8968,
  ["rceil"] = 8969,
  ["RightCeiling"] = 8969,
  ["lfloor"] = 8970,
  ["LeftFloor"] = 8970,
  ["rfloor"] = 8971,
  ["RightFloor"] = 8971,
  ["drcrop"] = 8972,
  ["dlcrop"] = 8973,
  ["urcrop"] = 8974,
  ["ulcrop"] = 8975,
  ["bnot"] = 8976,
  ["profline"] = 8978,
  ["profsurf"] = 8979,
  ["telrec"] = 8981,
  ["target"] = 8982,
  ["ulcorn"] = 8988,
  ["ulcorner"] = 8988,
  ["urcorn"] = 8989,
  ["urcorner"] = 8989,
  ["dlcorn"] = 8990,
  ["llcorner"] = 8990,
  ["drcorn"] = 8991,
  ["lrcorner"] = 8991,
  ["frown"] = 8994,
  ["sfrown"] = 8994,
  ["smile"] = 8995,
  ["ssmile"] = 8995,
  ["cylcty"] = 9005,
  ["profalar"] = 9006,
  ["topbot"] = 9014,
  ["ovbar"] = 9021,
  ["solbar"] = 9023,
  ["angzarr"] = 9084,
  ["lmoust"] = 9136,
  ["lmoustache"] = 9136,
  ["rmoust"] = 9137,
  ["rmoustache"] = 9137,
  ["tbrk"] = 9140,
  ["OverBracket"] = 9140,
  ["bbrk"] = 9141,
  ["UnderBracket"] = 9141,
  ["bbrktbrk"] = 9142,
  ["OverParenthesis"] = 9180,
  ["UnderParenthesis"] = 9181,
  ["OverBrace"] = 9182,
  ["UnderBrace"] = 9183,
  ["trpezium"] = 9186,
  ["elinters"] = 9191,
  ["blank"] = 9251,
  ["oS"] = 9416,
  ["circledS"] = 9416,
  ["boxh"] = 9472,
  ["HorizontalLine"] = 9472,
  ["boxv"] = 9474,
  ["boxdr"] = 9484,
  ["boxdl"] = 9488,
  ["boxur"] = 9492,
  ["boxul"] = 9496,
  ["boxvr"] = 9500,
  ["boxvl"] = 9508,
  ["boxhd"] = 9516,
  ["boxhu"] = 9524,
  ["boxvh"] = 9532,
  ["boxH"] = 9552,
  ["boxV"] = 9553,
  ["boxdR"] = 9554,
  ["boxDr"] = 9555,
  ["boxDR"] = 9556,
  ["boxdL"] = 9557,
  ["boxDl"] = 9558,
  ["boxDL"] = 9559,
  ["boxuR"] = 9560,
  ["boxUr"] = 9561,
  ["boxUR"] = 9562,
  ["boxuL"] = 9563,
  ["boxUl"] = 9564,
  ["boxUL"] = 9565,
  ["boxvR"] = 9566,
  ["boxVr"] = 9567,
  ["boxVR"] = 9568,
  ["boxvL"] = 9569,
  ["boxVl"] = 9570,
  ["boxVL"] = 9571,
  ["boxHd"] = 9572,
  ["boxhD"] = 9573,
  ["boxHD"] = 9574,
  ["boxHu"] = 9575,
  ["boxhU"] = 9576,
  ["boxHU"] = 9577,
  ["boxvH"] = 9578,
  ["boxVh"] = 9579,
  ["boxVH"] = 9580,
  ["uhblk"] = 9600,
  ["lhblk"] = 9604,
  ["block"] = 9608,
  ["blk14"] = 9617,
  ["blk12"] = 9618,
  ["blk34"] = 9619,
  ["squ"] = 9633,
  ["square"] = 9633,
  ["Square"] = 9633,
  ["squf"] = 9642,
  ["squarf"] = 9642,
  ["blacksquare"] = 9642,
  ["FilledVerySmallSquare"] = 9642,
  ["EmptyVerySmallSquare"] = 9643,
  ["rect"] = 9645,
  ["marker"] = 9646,
  ["fltns"] = 9649,
  ["xutri"] = 9651,
  ["bigtriangleup"] = 9651,
  ["utrif"] = 9652,
  ["blacktriangle"] = 9652,
  ["utri"] = 9653,
  ["triangle"] = 9653,
  ["rtrif"] = 9656,
  ["blacktriangleright"] = 9656,
  ["rtri"] = 9657,
  ["triangleright"] = 9657,
  ["xdtri"] = 9661,
  ["bigtriangledown"] = 9661,
  ["dtrif"] = 9662,
  ["blacktriangledown"] = 9662,
  ["dtri"] = 9663,
  ["triangledown"] = 9663,
  ["ltrif"] = 9666,
  ["blacktriangleleft"] = 9666,
  ["ltri"] = 9667,
  ["triangleleft"] = 9667,
  ["loz"] = 9674,
  ["lozenge"] = 9674,
  ["cir"] = 9675,
  ["tridot"] = 9708,
  ["xcirc"] = 9711,
  ["bigcirc"] = 9711,
  ["ultri"] = 9720,
  ["urtri"] = 9721,
  ["lltri"] = 9722,
  ["EmptySmallSquare"] = 9723,
  ["FilledSmallSquare"] = 9724,
  ["starf"] = 9733,
  ["bigstar"] = 9733,
  ["star"] = 9734,
  ["phone"] = 9742,
  ["female"] = 9792,
  ["male"] = 9794,
  ["spades"] = 9824,
  ["spadesuit"] = 9824,
  ["clubs"] = 9827,
  ["clubsuit"] = 9827,
  ["hearts"] = 9829,
  ["heartsuit"] = 9829,
  ["diams"] = 9830,
  ["diamondsuit"] = 9830,
  ["sung"] = 9834,
  ["flat"] = 9837,
  ["natur"] = 9838,
  ["natural"] = 9838,
  ["sharp"] = 9839,
  ["check"] = 10003,
  ["checkmark"] = 10003,
  ["cross"] = 10007,
  ["malt"] = 10016,
  ["maltese"] = 10016,
  ["sext"] = 10038,
  ["VerticalSeparator"] = 10072,
  ["lbbrk"] = 10098,
  ["rbbrk"] = 10099,
  ["lobrk"] = 10214,
  ["LeftDoubleBracket"] = 10214,
  ["robrk"] = 10215,
  ["RightDoubleBracket"] = 10215,
  ["lang"] = 10216,
  ["LeftAngleBracket"] = 10216,
  ["langle"] = 10216,
  ["rang"] = 10217,
  ["RightAngleBracket"] = 10217,
  ["rangle"] = 10217,
  ["Lang"] = 10218,
  ["Rang"] = 10219,
  ["loang"] = 10220,
  ["roang"] = 10221,
  ["xlarr"] = 10229,
  ["longleftarrow"] = 10229,
  ["LongLeftArrow"] = 10229,
  ["xrarr"] = 10230,
  ["longrightarrow"] = 10230,
  ["LongRightArrow"] = 10230,
  ["xharr"] = 10231,
  ["longleftrightarrow"] = 10231,
  ["LongLeftRightArrow"] = 10231,
  ["xlArr"] = 10232,
  ["Longleftarrow"] = 10232,
  ["DoubleLongLeftArrow"] = 10232,
  ["xrArr"] = 10233,
  ["Longrightarrow"] = 10233,
  ["DoubleLongRightArrow"] = 10233,
  ["xhArr"] = 10234,
  ["Longleftrightarrow"] = 10234,
  ["DoubleLongLeftRightArrow"] = 10234,
  ["xmap"] = 10236,
  ["longmapsto"] = 10236,
  ["dzigrarr"] = 10239,
  ["nvlArr"] = 10498,
  ["nvrArr"] = 10499,
  ["nvHarr"] = 10500,
  ["Map"] = 10501,
  ["lbarr"] = 10508,
  ["rbarr"] = 10509,
  ["bkarow"] = 10509,
  ["lBarr"] = 10510,
  ["rBarr"] = 10511,
  ["dbkarow"] = 10511,
  ["RBarr"] = 10512,
  ["drbkarow"] = 10512,
  ["DDotrahd"] = 10513,
  ["UpArrowBar"] = 10514,
  ["DownArrowBar"] = 10515,
  ["Rarrtl"] = 10518,
  ["latail"] = 10521,
  ["ratail"] = 10522,
  ["lAtail"] = 10523,
  ["rAtail"] = 10524,
  ["larrfs"] = 10525,
  ["rarrfs"] = 10526,
  ["larrbfs"] = 10527,
  ["rarrbfs"] = 10528,
  ["nwarhk"] = 10531,
  ["nearhk"] = 10532,
  ["searhk"] = 10533,
  ["hksearow"] = 10533,
  ["swarhk"] = 10534,
  ["hkswarow"] = 10534,
  ["nwnear"] = 10535,
  ["nesear"] = 10536,
  ["toea"] = 10536,
  ["seswar"] = 10537,
  ["tosa"] = 10537,
  ["swnwar"] = 10538,
  ["rarrc"] = 10547,
  ["cudarrr"] = 10549,
  ["ldca"] = 10550,
  ["rdca"] = 10551,
  ["cudarrl"] = 10552,
  ["larrpl"] = 10553,
  ["curarrm"] = 10556,
  ["cularrp"] = 10557,
  ["rarrpl"] = 10565,
  ["harrcir"] = 10568,
  ["Uarrocir"] = 10569,
  ["lurdshar"] = 10570,
  ["ldrushar"] = 10571,
  ["LeftRightVector"] = 10574,
  ["RightUpDownVector"] = 10575,
  ["DownLeftRightVector"] = 10576,
  ["LeftUpDownVector"] = 10577,
  ["LeftVectorBar"] = 10578,
  ["RightVectorBar"] = 10579,
  ["RightUpVectorBar"] = 10580,
  ["RightDownVectorBar"] = 10581,
  ["DownLeftVectorBar"] = 10582,
  ["DownRightVectorBar"] = 10583,
  ["LeftUpVectorBar"] = 10584,
  ["LeftDownVectorBar"] = 10585,
  ["LeftTeeVector"] = 10586,
  ["RightTeeVector"] = 10587,
  ["RightUpTeeVector"] = 10588,
  ["RightDownTeeVector"] = 10589,
  ["DownLeftTeeVector"] = 10590,
  ["DownRightTeeVector"] = 10591,
  ["LeftUpTeeVector"] = 10592,
  ["LeftDownTeeVector"] = 10593,
  ["lHar"] = 10594,
  ["uHar"] = 10595,
  ["rHar"] = 10596,
  ["dHar"] = 10597,
  ["luruhar"] = 10598,
  ["ldrdhar"] = 10599,
  ["ruluhar"] = 10600,
  ["rdldhar"] = 10601,
  ["lharul"] = 10602,
  ["llhard"] = 10603,
  ["rharul"] = 10604,
  ["lrhard"] = 10605,
  ["udhar"] = 10606,
  ["UpEquilibrium"] = 10606,
  ["duhar"] = 10607,
  ["ReverseUpEquilibrium"] = 10607,
  ["RoundImplies"] = 10608,
  ["erarr"] = 10609,
  ["simrarr"] = 10610,
  ["larrsim"] = 10611,
  ["rarrsim"] = 10612,
  ["rarrap"] = 10613,
  ["ltlarr"] = 10614,
  ["gtrarr"] = 10616,
  ["subrarr"] = 10617,
  ["suplarr"] = 10619,
  ["lfisht"] = 10620,
  ["rfisht"] = 10621,
  ["ufisht"] = 10622,
  ["dfisht"] = 10623,
  ["lopar"] = 10629,
  ["ropar"] = 10630,
  ["lbrke"] = 10635,
  ["rbrke"] = 10636,
  ["lbrkslu"] = 10637,
  ["rbrksld"] = 10638,
  ["lbrksld"] = 10639,
  ["rbrkslu"] = 10640,
  ["langd"] = 10641,
  ["rangd"] = 10642,
  ["lparlt"] = 10643,
  ["rpargt"] = 10644,
  ["gtlPar"] = 10645,
  ["ltrPar"] = 10646,
  ["vzigzag"] = 10650,
  ["vangrt"] = 10652,
  ["angrtvbd"] = 10653,
  ["ange"] = 10660,
  ["range"] = 10661,
  ["dwangle"] = 10662,
  ["uwangle"] = 10663,
  ["angmsdaa"] = 10664,
  ["angmsdab"] = 10665,
  ["angmsdac"] = 10666,
  ["angmsdad"] = 10667,
  ["angmsdae"] = 10668,
  ["angmsdaf"] = 10669,
  ["angmsdag"] = 10670,
  ["angmsdah"] = 10671,
  ["bemptyv"] = 10672,
  ["demptyv"] = 10673,
  ["cemptyv"] = 10674,
  ["raemptyv"] = 10675,
  ["laemptyv"] = 10676,
  ["ohbar"] = 10677,
  ["omid"] = 10678,
  ["opar"] = 10679,
  ["operp"] = 10681,
  ["olcross"] = 10683,
  ["odsold"] = 10684,
  ["olcir"] = 10686,
  ["ofcir"] = 10687,
  ["olt"] = 10688,
  ["ogt"] = 10689,
  ["cirscir"] = 10690,
  ["cirE"] = 10691,
  ["solb"] = 10692,
  ["bsolb"] = 10693,
  ["boxbox"] = 10697,
  ["trisb"] = 10701,
  ["rtriltri"] = 10702,
  ["LeftTriangleBar"] = 10703,
  ["RightTriangleBar"] = 10704,
  ["race"] = 10714,
  ["iinfin"] = 10716,
  ["infintie"] = 10717,
  ["nvinfin"] = 10718,
  ["eparsl"] = 10723,
  ["smeparsl"] = 10724,
  ["eqvparsl"] = 10725,
  ["lozf"] = 10731,
  ["blacklozenge"] = 10731,
  ["RuleDelayed"] = 10740,
  ["dsol"] = 10742,
  ["xodot"] = 10752,
  ["bigodot"] = 10752,
  ["xoplus"] = 10753,
  ["bigoplus"] = 10753,
  ["xotime"] = 10754,
  ["bigotimes"] = 10754,
  ["xuplus"] = 10756,
  ["biguplus"] = 10756,
  ["xsqcup"] = 10758,
  ["bigsqcup"] = 10758,
  ["qint"] = 10764,
  ["iiiint"] = 10764,
  ["fpartint"] = 10765,
  ["cirfnint"] = 10768,
  ["awint"] = 10769,
  ["rppolint"] = 10770,
  ["scpolint"] = 10771,
  ["npolint"] = 10772,
  ["pointint"] = 10773,
  ["quatint"] = 10774,
  ["intlarhk"] = 10775,
  ["pluscir"] = 10786,
  ["plusacir"] = 10787,
  ["simplus"] = 10788,
  ["plusdu"] = 10789,
  ["plussim"] = 10790,
  ["plustwo"] = 10791,
  ["mcomma"] = 10793,
  ["minusdu"] = 10794,
  ["loplus"] = 10797,
  ["roplus"] = 10798,
  ["Cross"] = 10799,
  ["timesd"] = 10800,
  ["timesbar"] = 10801,
  ["smashp"] = 10803,
  ["lotimes"] = 10804,
  ["rotimes"] = 10805,
  ["otimesas"] = 10806,
  ["Otimes"] = 10807,
  ["odiv"] = 10808,
  ["triplus"] = 10809,
  ["triminus"] = 10810,
  ["tritime"] = 10811,
  ["iprod"] = 10812,
  ["intprod"] = 10812,
  ["amalg"] = 10815,
  ["capdot"] = 10816,
  ["ncup"] = 10818,
  ["ncap"] = 10819,
  ["capand"] = 10820,
  ["cupor"] = 10821,
  ["cupcap"] = 10822,
  ["capcup"] = 10823,
  ["cupbrcap"] = 10824,
  ["capbrcup"] = 10825,
  ["cupcup"] = 10826,
  ["capcap"] = 10827,
  ["ccups"] = 10828,
  ["ccaps"] = 10829,
  ["ccupssm"] = 10832,
  ["And"] = 10835,
  ["Or"] = 10836,
  ["andand"] = 10837,
  ["oror"] = 10838,
  ["orslope"] = 10839,
  ["andslope"] = 10840,
  ["andv"] = 10842,
  ["orv"] = 10843,
  ["andd"] = 10844,
  ["ord"] = 10845,
  ["wedbar"] = 10847,
  ["sdote"] = 10854,
  ["simdot"] = 10858,
  ["congdot"] = 10861,
  ["easter"] = 10862,
  ["apacir"] = 10863,
  ["apE"] = 10864,
  ["eplus"] = 10865,
  ["pluse"] = 10866,
  ["Esim"] = 10867,
  ["Colone"] = 10868,
  ["Equal"] = 10869,
  ["eDDot"] = 10871,
  ["ddotseq"] = 10871,
  ["equivDD"] = 10872,
  ["ltcir"] = 10873,
  ["gtcir"] = 10874,
  ["ltquest"] = 10875,
  ["gtquest"] = 10876,
  ["les"] = 10877,
  ["LessSlantEqual"] = 10877,
  ["leqslant"] = 10877,
  ["ges"] = 10878,
  ["GreaterSlantEqual"] = 10878,
  ["geqslant"] = 10878,
  ["lesdot"] = 10879,
  ["gesdot"] = 10880,
  ["lesdoto"] = 10881,
  ["gesdoto"] = 10882,
  ["lesdotor"] = 10883,
  ["gesdotol"] = 10884,
  ["lap"] = 10885,
  ["lessapprox"] = 10885,
  ["gap"] = 10886,
  ["gtrapprox"] = 10886,
  ["lne"] = 10887,
  ["lneq"] = 10887,
  ["gne"] = 10888,
  ["gneq"] = 10888,
  ["lnap"] = 10889,
  ["lnapprox"] = 10889,
  ["gnap"] = 10890,
  ["gnapprox"] = 10890,
  ["lEg"] = 10891,
  ["lesseqqgtr"] = 10891,
  ["gEl"] = 10892,
  ["gtreqqless"] = 10892,
  ["lsime"] = 10893,
  ["gsime"] = 10894,
  ["lsimg"] = 10895,
  ["gsiml"] = 10896,
  ["lgE"] = 10897,
  ["glE"] = 10898,
  ["lesges"] = 10899,
  ["gesles"] = 10900,
  ["els"] = 10901,
  ["eqslantless"] = 10901,
  ["egs"] = 10902,
  ["eqslantgtr"] = 10902,
  ["elsdot"] = 10903,
  ["egsdot"] = 10904,
  ["el"] = 10905,
  ["eg"] = 10906,
  ["siml"] = 10909,
  ["simg"] = 10910,
  ["simlE"] = 10911,
  ["simgE"] = 10912,
  ["LessLess"] = 10913,
  ["GreaterGreater"] = 10914,
  ["glj"] = 10916,
  ["gla"] = 10917,
  ["ltcc"] = 10918,
  ["gtcc"] = 10919,
  ["lescc"] = 10920,
  ["gescc"] = 10921,
  ["smt"] = 10922,
  ["lat"] = 10923,
  ["smte"] = 10924,
  ["late"] = 10925,
  ["bumpE"] = 10926,
  ["pre"] = 10927,
  ["preceq"] = 10927,
  ["PrecedesEqual"] = 10927,
  ["sce"] = 10928,
  ["succeq"] = 10928,
  ["SucceedsEqual"] = 10928,
  ["prE"] = 10931,
  ["scE"] = 10932,
  ["prnE"] = 10933,
  ["precneqq"] = 10933,
  ["scnE"] = 10934,
  ["succneqq"] = 10934,
  ["prap"] = 10935,
  ["precapprox"] = 10935,
  ["scap"] = 10936,
  ["succapprox"] = 10936,
  ["prnap"] = 10937,
  ["precnapprox"] = 10937,
  ["scnap"] = 10938,
  ["succnapprox"] = 10938,
  ["Pr"] = 10939,
  ["Sc"] = 10940,
  ["subdot"] = 10941,
  ["supdot"] = 10942,
  ["subplus"] = 10943,
  ["supplus"] = 10944,
  ["submult"] = 10945,
  ["supmult"] = 10946,
  ["subedot"] = 10947,
  ["supedot"] = 10948,
  ["subE"] = 10949,
  ["subseteqq"] = 10949,
  ["supE"] = 10950,
  ["supseteqq"] = 10950,
  ["subsim"] = 10951,
  ["supsim"] = 10952,
  ["subnE"] = 10955,
  ["subsetneqq"] = 10955,
  ["supnE"] = 10956,
  ["supsetneqq"] = 10956,
  ["csub"] = 10959,
  ["csup"] = 10960,
  ["csube"] = 10961,
  ["csupe"] = 10962,
  ["subsup"] = 10963,
  ["supsub"] = 10964,
  ["subsub"] = 10965,
  ["supsup"] = 10966,
  ["suphsub"] = 10967,
  ["supdsub"] = 10968,
  ["forkv"] = 10969,
  ["topfork"] = 10970,
  ["mlcp"] = 10971,
  ["Dashv"] = 10980,
  ["DoubleLeftTee"] = 10980,
  ["Vdashl"] = 10982,
  ["Barv"] = 10983,
  ["vBar"] = 10984,
  ["vBarv"] = 10985,
  ["Vbar"] = 10987,
  ["Not"] = 10988,
  ["bNot"] = 10989,
  ["rnmid"] = 10990,
  ["cirmid"] = 10991,
  ["midcir"] = 10992,
  ["topcir"] = 10993,
  ["nhpar"] = 10994,
  ["parsim"] = 10995,
  ["parsl"] = 11005,
  ["fflig"] = 64256,
  ["filig"] = 64257,
  ["fllig"] = 64258,
  ["ffilig"] = 64259,
  ["ffllig"] = 64260,
  ["Ascr"] = 119964,
  ["Cscr"] = 119966,
  ["Dscr"] = 119967,
  ["Gscr"] = 119970,
  ["Jscr"] = 119973,
  ["Kscr"] = 119974,
  ["Nscr"] = 119977,
  ["Oscr"] = 119978,
  ["Pscr"] = 119979,
  ["Qscr"] = 119980,
  ["Sscr"] = 119982,
  ["Tscr"] = 119983,
  ["Uscr"] = 119984,
  ["Vscr"] = 119985,
  ["Wscr"] = 119986,
  ["Xscr"] = 119987,
  ["Yscr"] = 119988,
  ["Zscr"] = 119989,
  ["ascr"] = 119990,
  ["bscr"] = 119991,
  ["cscr"] = 119992,
  ["dscr"] = 119993,
  ["fscr"] = 119995,
  ["hscr"] = 119997,
  ["iscr"] = 119998,
  ["jscr"] = 119999,
  ["kscr"] = 120000,
  ["lscr"] = 120001,
  ["mscr"] = 120002,
  ["nscr"] = 120003,
  ["pscr"] = 120005,
  ["qscr"] = 120006,
  ["rscr"] = 120007,
  ["sscr"] = 120008,
  ["tscr"] = 120009,
  ["uscr"] = 120010,
  ["vscr"] = 120011,
  ["wscr"] = 120012,
  ["xscr"] = 120013,
  ["yscr"] = 120014,
  ["zscr"] = 120015,
  ["Afr"] = 120068,
  ["Bfr"] = 120069,
  ["Dfr"] = 120071,
  ["Efr"] = 120072,
  ["Ffr"] = 120073,
  ["Gfr"] = 120074,
  ["Jfr"] = 120077,
  ["Kfr"] = 120078,
  ["Lfr"] = 120079,
  ["Mfr"] = 120080,
  ["Nfr"] = 120081,
  ["Ofr"] = 120082,
  ["Pfr"] = 120083,
  ["Qfr"] = 120084,
  ["Sfr"] = 120086,
  ["Tfr"] = 120087,
  ["Ufr"] = 120088,
  ["Vfr"] = 120089,
  ["Wfr"] = 120090,
  ["Xfr"] = 120091,
  ["Yfr"] = 120092,
  ["afr"] = 120094,
  ["bfr"] = 120095,
  ["cfr"] = 120096,
  ["dfr"] = 120097,
  ["efr"] = 120098,
  ["ffr"] = 120099,
  ["gfr"] = 120100,
  ["hfr"] = 120101,
  ["ifr"] = 120102,
  ["jfr"] = 120103,
  ["kfr"] = 120104,
  ["lfr"] = 120105,
  ["mfr"] = 120106,
  ["nfr"] = 120107,
  ["ofr"] = 120108,
  ["pfr"] = 120109,
  ["qfr"] = 120110,
  ["rfr"] = 120111,
  ["sfr"] = 120112,
  ["tfr"] = 120113,
  ["ufr"] = 120114,
  ["vfr"] = 120115,
  ["wfr"] = 120116,
  ["xfr"] = 120117,
  ["yfr"] = 120118,
  ["zfr"] = 120119,
  ["Aopf"] = 120120,
  ["Bopf"] = 120121,
  ["Dopf"] = 120123,
  ["Eopf"] = 120124,
  ["Fopf"] = 120125,
  ["Gopf"] = 120126,
  ["Iopf"] = 120128,
  ["Jopf"] = 120129,
  ["Kopf"] = 120130,
  ["Lopf"] = 120131,
  ["Mopf"] = 120132,
  ["Oopf"] = 120134,
  ["Sopf"] = 120138,
  ["Topf"] = 120139,
  ["Uopf"] = 120140,
  ["Vopf"] = 120141,
  ["Wopf"] = 120142,
  ["Xopf"] = 120143,
  ["Yopf"] = 120144,
  ["aopf"] = 120146,
  ["bopf"] = 120147,
  ["copf"] = 120148,
  ["dopf"] = 120149,
  ["eopf"] = 120150,
  ["fopf"] = 120151,
  ["gopf"] = 120152,
  ["hopf"] = 120153,
  ["iopf"] = 120154,
  ["jopf"] = 120155,
  ["kopf"] = 120156,
  ["lopf"] = 120157,
  ["mopf"] = 120158,
  ["nopf"] = 120159,
  ["oopf"] = 120160,
  ["popf"] = 120161,
  ["qopf"] = 120162,
  ["ropf"] = 120163,
  ["sopf"] = 120164,
  ["topf"] = 120165,
  ["uopf"] = 120166,
  ["vopf"] = 120167,
  ["wopf"] = 120168,
  ["xopf"] = 120169,
  ["yopf"] = 120170,
  ["zopf"] = 120171,
}
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Given a string `s` of decimal digits, the \luamdef{entities.dec_entity}
% returns the corresponding \acro{utf}8-encoded Unicode codepoint.
%
% \end{markdown}
%  \begin{macrocode}
function entities.dec_entity(s)
  return unicode.utf8.char(tonumber(s))
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Given a string `s` of hexadecimal digits, the
% \luamdef{entities.hex_entity} returns the corresponding
% \acro{utf}8-encoded Unicode codepoint.
%
% \end{markdown}
%  \begin{macrocode}
function entities.hex_entity(s)
  return unicode.utf8.char(tonumber("0x"..s))
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Given a character entity name `s` (like `ouml`), the
% \luamdef{entities.char_entity} returns the corresponding
% \acro{utf}8-encoded Unicode codepoint.
%
% \end{markdown}
%  \begin{macrocode}
function entities.char_entity(s)
  local n = character_entities[s]
  if n == nil then
    return "&" .. s .. ";"
  end
  return unicode.utf8.char(n)
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Plain \TeX{} Writer {#texwriter}
%
% This section documents the \luamref{writer} object, which implements the
% routines for producing the \TeX{} output. The object is an amalgamate of the
% generic, \TeX{}, \LaTeX{} writer objects that were located in the
% `lunamark/writer/generic.lua`, `lunamark/writer/tex.lua`, and
% `lunamark/writer/latex.lua` files in the Lunamark Lua module.
%
% Although not specified in the Lua interface (see Section
% <#sec:luainterface>), the \luamref{writer} object is exported, so that the
% curious user could easily tinker with the methods of the objects produced by
% the \luamref{writer.new} method described below. The user should be aware,
% however, that the implementation may change in a future revision.
%
% \end{markdown}
%  \begin{macrocode}
M.writer = {}
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{writer.new} method creates and returns a new \TeX{} writer
% object associated with the Lua interface options (see Section
% <#sec:luaoptions>) `options`. When `options` are unspecified, it is
% assumed that an empty table was passed to the method.
%
% The objects produced by the \luamref{writer.new} method expose instance methods
% and variables of their own. As a convention, I will refer to these
% \meta{member}s as `writer->`\meta{member}. All member variables are
% immutable unless explicitly stated otherwise.
%
% \end{markdown}
%  \begin{macrocode}
function M.writer.new(options)
  local self = {}
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Make `options` available as \luamdef{writer->options}, so that it is
% accessible from extensions.
%
% \end{markdown}
%  \begin{macrocode}
  self.options = options
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Parse the \Opt{slice} option and define \luamdef{writer->slice\_begin},
% \luamdef{writer->slice\_end}, and \luamdef{writer->is\_writing}. The
% \luamref{writer->is\_writing} member variable is mutable.
%
% \end{markdown}
%  \begin{macrocode}
  local slice_specifiers = {}
  for specifier in options.slice:gmatch("[^%s]+") do
    table.insert(slice_specifiers, specifier)
  end

  if #slice_specifiers == 2 then
    self.slice_begin, self.slice_end = table.unpack(slice_specifiers)
    local slice_begin_type = self.slice_begin:sub(1, 1)
    if slice_begin_type ~= "^" and slice_begin_type ~= "$" then
      self.slice_begin = "^" .. self.slice_begin
    end
    local slice_end_type = self.slice_end:sub(1, 1)
    if slice_end_type ~= "^" and slice_end_type ~= "$" then
      self.slice_end = "$" .. self.slice_end
    end
  elseif #slice_specifiers == 1 then
    self.slice_begin = "^" .. slice_specifiers[1]
    self.slice_end = "$" .. slice_specifiers[1]
  end

  if self.slice_begin == "^" and self.slice_end ~= "^" then
    self.is_writing = true
  else
    self.is_writing = false
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->suffix} as the suffix of the produced cache files.
%
% \end{markdown}
%  \begin{macrocode}
  self.suffix = ".tex"
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->space} as the output format of a space character.
%
% \end{markdown}
%  \begin{macrocode}
  self.space = " "
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->nbsp} as the output format of a non-breaking space
% character.
%
% \end{markdown}
%  \begin{macrocode}
  self.nbsp = "\\markdownRendererNbsp{}"
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->plain} as a function that will transform an input
% plain text block `s` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
  function self.plain(s)
    return s
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->paragraph} as a function that will transform an
% input paragraph `s` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
  function self.paragraph(s)
    if not self.is_writing then return "" end
    return s
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->pack} as a function that will take the filename
% `name` of the output file prepared by the reader and transform it to the
% output format.
%
% \end{markdown}
%  \begin{macrocode}
  function self.pack(name)
    return [[\input ]] .. name .. [[\relax]]
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->interblocksep} as the output format of a block
% element separator.
%
% \end{markdown}
%  \begin{macrocode}
  function self.interblocksep()
    if not self.is_writing then return "" end
    return "\\markdownRendererInterblockSeparator\n{}"
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->linebreak} as the output format of a forced line break.
%
% \end{markdown}
%  \begin{macrocode}
  self.linebreak = "\\markdownRendererLineBreak\n{}"
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->ellipsis} as the output format of an ellipsis.
%
% \end{markdown}
%  \begin{macrocode}
  self.ellipsis = "\\markdownRendererEllipsis{}"
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->thematic_break} as the output format of a thematic
% break.
%
% \end{markdown}
%  \begin{macrocode}
  function self.thematic_break()
    if not self.is_writing then return "" end
    return "\\markdownRendererThematicBreak{}"
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define tables \luamdef{writer->escaped_uri_chars} and
% \luamdef{writer->escaped_minimal_strings} containing the mapping from
% special plain characters and character strings that always need to be
% escaped.
%
% \end{markdown}
%  \begin{macrocode}
   self.escaped_uri_chars = {
     ["{"] = "\\markdownRendererLeftBrace{}",
     ["}"] = "\\markdownRendererRightBrace{}",
     ["\\"] = "\\markdownRendererBackslash{}",
   }
   self.escaped_minimal_strings = {
     ["^^"] = "\\markdownRendererCircumflex\\markdownRendererCircumflex ",
     ["☒"] = "\\markdownRendererTickedBox{}",
     ["⌛"] = "\\markdownRendererHalfTickedBox{}",
     ["☐"] = "\\markdownRendererUntickedBox{}",
   }
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define a table \luamdef{writer->escaped_chars} containing the mapping from
% special plain \TeX{} characters (including the active pipe character (`|`)
% of \Hologo{ConTeXt}) that need to be escaped for typeset content.
%
% \end{markdown}
%  \begin{macrocode}
  self.escaped_chars = {
     ["{"] = "\\markdownRendererLeftBrace{}",
     ["}"] = "\\markdownRendererRightBrace{}",
     ["%"] = "\\markdownRendererPercentSign{}",
     ["\\"] = "\\markdownRendererBackslash{}",
     ["#"] = "\\markdownRendererHash{}",
     ["$"] = "\\markdownRendererDollarSign{}",
     ["&"] = "\\markdownRendererAmpersand{}",
     ["_"] = "\\markdownRendererUnderscore{}",
     ["^"] = "\\markdownRendererCircumflex{}",
     ["~"] = "\\markdownRendererTilde{}",
     ["|"] = "\\markdownRendererPipe{}",
   }
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Use the \luamref{writer->escaped_chars}, \luamref{writer->escaped_uri_chars},
% and \luamref{writer->escaped_minimal_strings} tables to create the
% \luamdef{writer->escape}, \luamdef{writer->escape_uri}, and
% \luamdef{writer->escape_minimal} escaper functions.
%
% \end{markdown}
%  \begin{macrocode}
  self.escape = util.escaper(self.escaped_chars, self.escaped_minimal_strings)
  self.escape_uri = util.escaper(self.escaped_uri_chars, self.escaped_minimal_strings)
  self.escape_minimal = util.escaper({}, self.escaped_minimal_strings)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->string} as a function that will transform an input
% plain text span `s` to the output format and \luamdef{writer->uri} as a
% function that will transform an input \acro{uri} `u` to the output format.
% If the \Opt{hybrid} option is enabled, use the
% \luamref{writer->escape_minimal}.  Otherwise, use the
% \luamref{writer->escape}, and \luamref{writer->escape_uri} functions.
%
% \end{markdown}
%  \begin{macrocode}
  if options.hybrid then
    self.string = self.escape_minimal
    self.uri = self.escape_minimal
  else
    self.string = self.escape
    self.uri = self.escape_uri
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->code} as a function that will transform an input
% inline code span `s` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
  function self.code(s)
    return {"\\markdownRendererCodeSpan{",self.escape(s),"}"}
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->link} as a function that will transform an input
% hyperlink to the output format, where `lab` corresponds to the label,
% `src` to \acro{uri}, and `tit` to the title of the link.
%
% \end{markdown}
%  \begin{macrocode}
  function self.link(lab,src,tit)
    return {"\\markdownRendererLink{",lab,"}",
                          "{",self.escape(src),"}",
                          "{",self.uri(src),"}",
                          "{",self.string(tit or ""),"}"}
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->image} as a function that will transform an input
% image to the output format, where `lab` corresponds to the label, `src`
% to the \acro{url}, and `tit` to the title of the image.
%
% \end{markdown}
%  \begin{macrocode}
  function self.image(lab,src,tit)
    return {"\\markdownRendererImage{",lab,"}",
                           "{",self.string(src),"}",
                           "{",self.uri(src),"}",
                           "{",self.string(tit or ""),"}"}
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->bulletlist} as a function that will transform an input
% bulleted list to the output format, where `items` is an array of the list
% items and `tight` specifies, whether the list is tight or not.
%
% \end{markdown}
%  \begin{macrocode}
  function self.bulletlist(items,tight)
    if not self.is_writing then return "" end
    local buffer = {}
    for _,item in ipairs(items) do
      buffer[#buffer + 1] = self.bulletitem(item)
    end
    local contents = util.intersperse(buffer,"\n")
    if tight and options.tightLists then
      return {"\\markdownRendererUlBeginTight\n",contents,
        "\n\\markdownRendererUlEndTight "}
    else
      return {"\\markdownRendererUlBegin\n",contents,
        "\n\\markdownRendererUlEnd "}
    end
  end
%    \end{macrocode}
% \begin{markdown}
%
% Define \luamdef{writer->bulletitem} as a function that will transform an
% input bulleted list item to the output format, where `s` is the text of
% the list item.
%
% \end{markdown}
%  \begin{macrocode}
  function self.bulletitem(s)
    return {"\\markdownRendererUlItem ",s,
            "\\markdownRendererUlItemEnd "}
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->orderedlist} as a function that will transform an
% input ordered list to the output format, where `items` is an array of the
% list items and `tight` specifies, whether the list is tight or not. If the
% optional parameter `startnum` is present, it is the number of the first list
% item.
%
% \end{markdown}
%  \begin{macrocode}
  function self.orderedlist(items,tight,startnum)
    if not self.is_writing then return "" end
    local buffer = {}
    local num = startnum
    for _,item in ipairs(items) do
      buffer[#buffer + 1] = self.ordereditem(item,num)
      if num ~= nil then
        num = num + 1
      end
    end
    local contents = util.intersperse(buffer,"\n")
    if tight and options.tightLists then
      return {"\\markdownRendererOlBeginTight\n",contents,
              "\n\\markdownRendererOlEndTight "}
    else
      return {"\\markdownRendererOlBegin\n",contents,
              "\n\\markdownRendererOlEnd "}
    end
  end
%    \end{macrocode}
% \begin{markdown}
%
% Define \luamdef{writer->ordereditem} as a function that will transform an
% input ordered list item to the output format, where `s` is the text of
% the list item. If the optional parameter `num` is present, it is the number
% of the list item.
%
% \end{markdown}
%  \begin{macrocode}
  function self.ordereditem(s,num)
    if num ~= nil then
      return {"\\markdownRendererOlItemWithNumber{",num,"}",s,
              "\\markdownRendererOlItemEnd "}
    else
      return {"\\markdownRendererOlItem ",s,
              "\\markdownRendererOlItemEnd "}
    end
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->inline_html_comment} as a function that will
% transform the contents of an inline \acro{HTML} comment, to the output
% format, where `contents` are the contents of the \acro{HTML} comment.
%
% \end{markdown}
%  \begin{macrocode}
  function self.inline_html_comment(contents)
    return {"\\markdownRendererInlineHtmlComment{",contents,"}"}
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->block_html_comment} as a function that will
% transform the contents of a block \acro{HTML} comment, to the output
% format, where `contents` are the contents of the \acro{HTML} comment.
%
% \end{markdown}
%  \begin{macrocode}
  function self.block_html_comment(contents)
    if not self.is_writing then return "" end
    return {"\\markdownRendererBlockHtmlCommentBegin\n",contents,
            "\n\\markdownRendererBlockHtmlCommentEnd "}
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->inline_html_tag} as a function that will
% transform the contents of an opening, closing, or empty inline \acro{HTML}
% tag to the output format, where `contents` are the contents of the
% \acro{HTML} tag.
%
% \end{markdown}
%  \begin{macrocode}
  function self.inline_html_tag(contents)
    return {"\\markdownRendererInlineHtmlTag{",self.string(contents),"}"}
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->block_html_element} as a function that will
% transform the contents of a block \acro{HTML} element to the output format,
% where `s` are the contents of the \acro{HTML} element.
%
% \end{markdown}
%  \begin{macrocode}
  function self.block_html_element(s)
    if not self.is_writing then return "" end
    local name = util.cache(options.cacheDir, s, nil, nil, ".verbatim")
    return {"\\markdownRendererInputBlockHtmlElement{",name,"}"}
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->emphasis} as a function that will transform an
% emphasized span `s` of input text to the output format.
%
% \end{markdown}
%  \begin{macrocode}
  function self.emphasis(s)
    return {"\\markdownRendererEmphasis{",s,"}"}
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->tickbox} as a function that will transform a
% number `f` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
  function self.tickbox(f)
    if f == 1.0 then
      return "☒ "
    elseif f == 0.0 then
      return "☐ "
    else
      return "⌛ "
    end
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->strong} as a function that will transform a strongly
% emphasized span `s` of input text to the output format.
%
% \end{markdown}
%  \begin{macrocode}
  function self.strong(s)
    return {"\\markdownRendererStrongEmphasis{",s,"}"}
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->blockquote} as a function that will transform an
% input block quote `s` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
  function self.blockquote(s)
    if #util.rope_to_string(s) == 0 then return "" end
    return {"\\markdownRendererBlockQuoteBegin\n",s,
      "\n\\markdownRendererBlockQuoteEnd "}
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->verbatim} as a function that will transform an
% input code block `s` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
  function self.verbatim(s)
    if not self.is_writing then return "" end
    local name = util.cache_verbatim(options.cacheDir, s)
    return {"\\markdownRendererInputVerbatim{",name,"}"}
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->document} as a function that will transform a
% document `d` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
  function self.document(d)
    local active_attributes = self.active_attributes
    local buf = {"\\markdownRendererDocumentBegin\n", d}

    -- pop attributes for sections that have ended
    if options.headerAttributes and self.is_writing then
      while #active_attributes > 0 do
        local attributes = active_attributes[#active_attributes]
        if #attributes > 0 then
          table.insert(buf, "\\markdownRendererHeaderAttributeContextEnd")
        end
        table.remove(active_attributes, #active_attributes)
      end
    end

    table.insert(buf, "\\markdownRendererDocumentEnd")

    return buf
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->attributes} as a function that will transform
% input attributes `attr` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
  function self.attributes(attr)
    local buf = {}

    table.sort(attr)
    local key, value
    for i = 1, #attr do
      if attr[i]:sub(1, 1) == "#" then
        table.insert(buf, {"\\markdownRendererAttributeIdentifier{",
                           attr[i]:sub(2), "}"})
      elseif attr[i]:sub(1, 1) == "." then
        table.insert(buf, {"\\markdownRendererAttributeClassName{",
                           attr[i]:sub(2), "}"})
      else
        key, value = attr[i]:match("([^= ]+)%s*=%s*(.*)")
        table.insert(buf, {"\\markdownRendererAttributeKeyValue{",
                           key, "}{", value, "}"})
      end
    end

    return buf
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->active\_attributes} as a stack of attributes
% of the headings that are currently active. The
% \luamdef{writer->active\_headings} member variable is mutable.
%
% \end{markdown}
%  \begin{macrocode}
  self.active_attributes = {}
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->heading} as a function that will transform an
% input heading `s` at level `level` with attributes `attributes` to the
% output format.
%
% \end{markdown}
%  \begin{macrocode}
  function self.heading(s, level, attributes)
    attributes = attributes or {}
    for i = 1, #attributes do
      attributes[attributes[i]] = true
    end

    local active_attributes = self.active_attributes
    local slice_begin_type = self.slice_begin:sub(1, 1)
    local slice_begin_identifier = self.slice_begin:sub(2) or ""
    local slice_end_type = self.slice_end:sub(1, 1)
    local slice_end_identifier = self.slice_end:sub(2) or ""

    local buf = {}

    -- push empty attributes for implied sections
    while #active_attributes < level-1 do
      table.insert(active_attributes, {})
    end

    -- pop attributes for sections that have ended
    while #active_attributes >= level do
      local active_identifiers = active_attributes[#active_attributes]
      -- tear down all active attributes at slice end
      if active_identifiers["#" .. slice_end_identifier] ~= nil
          and slice_end_type == "$" then
        for header_level = #active_attributes, 1, -1 do
          if options.headerAttributes and #active_attributes[header_level] > 0 then
            table.insert(buf, "\\markdownRendererHeaderAttributeContextEnd")
          end
        end
        self.is_writing = false
      end
      table.remove(active_attributes, #active_attributes)
      if self.is_writing and options.headerAttributes and #active_identifiers > 0 then
        table.insert(buf, "\\markdownRendererHeaderAttributeContextEnd")
      end
      -- apply all active attributes at slice beginning
      if active_identifiers["#" .. slice_begin_identifier] ~= nil
          and slice_begin_type == "$" then
        for header_level = 1, #active_attributes do
          if options.headerAttributes and #active_attributes[header_level] > 0 then
            table.insert(buf, "\\markdownRendererHeaderAttributeContextBegin")
          end
        end
        self.is_writing = true
      end
    end

    -- tear down all active attributes at slice end
    if attributes["#" .. slice_end_identifier] ~= nil
        and slice_end_type == "^" then
      for header_level = #active_attributes, 1, -1 do
        if options.headerAttributes and #active_attributes[header_level] > 0 then
          table.insert(buf, "\\markdownRendererHeaderAttributeContextEnd")
        end
      end
      self.is_writing = false
    end

    -- push attributes for the new section
    table.insert(active_attributes, attributes)
    if self.is_writing and options.headerAttributes and #attributes > 0 then
      table.insert(buf, "\\markdownRendererHeaderAttributeContextBegin")
    end

    -- apply all active attributes at slice beginning
    if attributes["#" .. slice_begin_identifier] ~= nil
        and slice_begin_type == "^" then
      for header_level = 1, #active_attributes do
        if options.headerAttributes and #active_attributes[header_level] > 0 then
          table.insert(buf, "\\markdownRendererHeaderAttributeContextBegin")
        end
      end
      self.is_writing = true
    end

    if self.is_writing then
      table.insert(buf, self.attributes(attributes))
    end

    local cmd
    level = level + options.shiftHeadings
    if level <= 1 then
      cmd = "\\markdownRendererHeadingOne"
    elseif level == 2 then
      cmd = "\\markdownRendererHeadingTwo"
    elseif level == 3 then
      cmd = "\\markdownRendererHeadingThree"
    elseif level == 4 then
      cmd = "\\markdownRendererHeadingFour"
    elseif level == 5 then
      cmd = "\\markdownRendererHeadingFive"
    elseif level >= 6 then
      cmd = "\\markdownRendererHeadingSix"
    else
      cmd = ""
    end
    if self.is_writing then
      table.insert(buf, {cmd, "{", s, "}"})
    end

    return buf
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->get_state} as a function that returns the current
% state of the writer, where the state of a writer are its mutable member
% variables.
%
% \end{markdown}
%  \begin{macrocode}
  function self.get_state()
    return {
      is_writing=self.is_writing,
      active_attributes={table.unpack(self.active_attributes)},
    }
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->set_state} as a function that restores the input
% state `s` and returns the previous state of the writer.
%
% \end{markdown}
%  \begin{macrocode}
  function self.set_state(s)
    local previous_state = self.get_state()
    for key, value in pairs(s) do
      self[key] = value
    end
    return previous_state
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->defer_call} as a function that will encapsulate the
% input function `f`, so that `f` is called with the state of the writer at the
% time of calling \luamref{writer->defer_call}.
%
% \end{markdown}
%  \begin{macrocode}
  function self.defer_call(f)
    local previous_state = self.get_state()
    return function(...)
      local state = self.set_state(previous_state)
      local return_value = f(...)
      self.set_state(state)
      return return_value
    end
  end

  return self
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Parsers
% The \luamdef{parsers} hash table stores \acro{peg} patterns that are
% static and can be reused between different \luamref{reader} objects.
%
% \end{markdown}
%  \begin{macrocode}
local parsers                  = {}
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Basic Parsers
%
% \end{markdown}
%  \begin{macrocode}
parsers.percent                = P("%")
parsers.at                     = P("@")
parsers.comma                  = P(",")
parsers.asterisk               = P("*")
parsers.dash                   = P("-")
parsers.plus                   = P("+")
parsers.underscore             = P("_")
parsers.period                 = P(".")
parsers.hash                   = P("#")
parsers.ampersand              = P("&")
parsers.backtick               = P("`")
parsers.less                   = P("<")
parsers.more                   = P(">")
parsers.space                  = P(" ")
parsers.squote                 = P("'")
parsers.dquote                 = P('"')
parsers.lparent                = P("(")
parsers.rparent                = P(")")
parsers.lbracket               = P("[")
parsers.rbracket               = P("]")
parsers.lbrace                 = P("{")
parsers.rbrace                 = P("}")
parsers.circumflex             = P("^")
parsers.slash                  = P("/")
parsers.equal                  = P("=")
parsers.colon                  = P(":")
parsers.semicolon              = P(";")
parsers.exclamation            = P("!")
parsers.pipe                   = P("|")
parsers.tilde                  = P("~")
parsers.backslash              = P("\\")
parsers.tab                    = P("\t")
parsers.newline                = P("\n")
parsers.tightblocksep          = P("\001")

parsers.digit                  = R("09")
parsers.hexdigit               = R("09","af","AF")
parsers.letter                 = R("AZ","az")
parsers.alphanumeric           = R("AZ","az","09")
parsers.keyword                = parsers.letter
                               * parsers.alphanumeric^0
parsers.internal_punctuation   = S(":;,.?")

parsers.doubleasterisks        = P("**")
parsers.doubleunderscores      = P("__")
parsers.doubletildes           = P("~~")
parsers.fourspaces             = P("    ")

parsers.any                    = P(1)
parsers.succeed                = P(true)
parsers.fail                   = P(false)

parsers.escapable              = S("!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~")
parsers.anyescaped             = parsers.backslash / "" * parsers.escapable
                               + parsers.any

parsers.spacechar              = S("\t ")
parsers.spacing                = S(" \n\r\t")
parsers.nonspacechar           = parsers.any - parsers.spacing
parsers.optionalspace          = parsers.spacechar^0

parsers.normalchar             = parsers.any - (V("SpecialChar")
                                                + parsers.spacing
                                                + parsers.tightblocksep)
parsers.eof                    = -parsers.any
parsers.nonindentspace         = parsers.space^-3 * - parsers.spacechar
parsers.indent                 = parsers.space^-3 * parsers.tab
                               + parsers.fourspaces / ""
parsers.linechar               = P(1 - parsers.newline)

parsers.blankline              = parsers.optionalspace
                               * parsers.newline / "\n"
parsers.blanklines             = parsers.blankline^0
parsers.skipblanklines         = (parsers.optionalspace * parsers.newline)^0
parsers.indentedline           = parsers.indent    /""
                               * C(parsers.linechar^1 * parsers.newline^-1)
parsers.optionallyindentedline = parsers.indent^-1 /""
                               * C(parsers.linechar^1 * parsers.newline^-1)
parsers.sp                     = parsers.spacing^0
parsers.spnl                   = parsers.optionalspace
                               * (parsers.newline * parsers.optionalspace)^-1
parsers.line                   = parsers.linechar^0 * parsers.newline
parsers.nonemptyline           = parsers.line - parsers.blankline
%    \end{macrocode}
% \begin{figure}
% \hspace*{-0.1\textwidth}
% \begin{minipage}{1.2\textwidth}
% \centering
% \begin{tikzpicture}[shorten >=1pt, line width=0.1mm, >={Stealth[length=2mm]}, node distance=4.5cm, on grid, auto]
% \node[state, initial by diamond, accepting] (noop) {initial};
% \node[state] (odd_backslash) [above right=of noop] {odd backslash};
% \node[state] (even_backslash) [below right=of odd_backslash] {even backslash};
% \node[state] (comment) [below=of noop] {comment};
% \node[state] (leading_spaces) [below=of even_backslash, align=center] {leading tabs\\and spaces};
% \node[state] (blank_line) [below right=of comment] {blank line};
% \path[->]
% (noop) edge [in=150, out=180, loop] node [align=center, yshift=-0.75cm] {match [$^\wedge$\textbackslash\%]\\capture \textbackslash$\!^{2k}$\meta{match}\\reset $k$} ()
%        edge [bend right=10] node [below right=-0.2cm] {match \textbackslash} (odd_backslash)
%        edge [bend left=30] node [left, align=center] {match \%\\capture \textbackslash$\!^k$\\reset $k$} (comment)
% (comment) edge [in=305, out=325, loop] node [xshift=-1.2cm] {match [$^\wedge$$\drsh$]} ()
%           edge [bend left=10] node {match $\drsh$} (leading_spaces)
% (leading_spaces) edge [loop below] node {match [\textvisiblespace$\rightleftarrows$]} ()
%                  edge [bend right=90] node [right] {match \textbackslash} (odd_backslash)
%                  edge [bend left=10] node {match \%} (comment)
%                  edge [bend right=10] node {$\epsilon$} (blank_line)
%                  edge [bend left=10] node [align=center, right=0.3cm] {match [$^\wedge$\textvisiblespace$\rightleftarrows$$\drsh$\textbackslash\%]\\capture \meta{match}} (noop)
% (blank_line) edge [loop below] node {match [\textvisiblespace$\rightleftarrows$]} ()
%              edge [bend left=90] node [align=center, below=1.2cm] {match $\drsh$\\ capture $\drsh\drsh$} (noop)
% (odd_backslash) edge [bend right=10] node [align=center, xshift=-0.3cm, yshift=0.2cm] {match \textbackslash\\increment $k$} (even_backslash)
%                 edge [bend right=10] node [align=center, above left=-0.3cm, xshift=0.1cm] {match [$^\wedge$\textbackslash]\\for \%, capture \textbackslash$\!^k$\%\\for [$^\wedge$\%], capture \textbackslash$\!^{2k+1}$\meta{match}\\reset $k$} (noop)
% (even_backslash) edge [bend left=10] node {$\epsilon$} (noop);
% \end{tikzpicture}
% \caption{A pushdown automaton that recognizes \TeX{} comments}
% \label{fig:commented_line}
% \end{minipage}
% \end{figure}
% \begin{markdown}
%
% The \luamdef{parsers.commented_line}`^1` parser recognizes the regular
% language of \TeX{} comments, see an equivalent finite automaton in Figure
% <#fig:commented_line>.
%
% \end{markdown}
%  \begin{macrocode}
parsers.commented_line_letter  = parsers.linechar
                               + parsers.newline
                               - parsers.backslash
                               - parsers.percent
parsers.commented_line         = Cg(Cc(""), "backslashes")
                               * ((#(parsers.commented_line_letter
                                    - parsers.newline)
                                  * Cb("backslashes")
                                  * Cs(parsers.commented_line_letter
                                    - parsers.newline)^1  -- initial
                                  * Cg(Cc(""), "backslashes"))
                                 + #(parsers.backslash * parsers.backslash)
                                 * Cg((parsers.backslash  -- even backslash
                                      * parsers.backslash)^1, "backslashes")
                                 + (parsers.backslash
                                   * (#parsers.percent
                                     * Cb("backslashes")
                                     / function(backslashes)
                                       return string.rep("\\", #backslashes / 2)
                                     end
                                     * C(parsers.percent)
                                     + #parsers.commented_line_letter
                                     * Cb("backslashes")
                                     * Cc("\\")
                                     * C(parsers.commented_line_letter))
                                   * Cg(Cc(""), "backslashes")))^0
                               * (#parsers.percent
                                 * Cb("backslashes")
                                 / function(backslashes)
                                   return string.rep("\\", #backslashes / 2)
                                 end
                                 * ((parsers.percent  -- comment
                                    * parsers.line
                                    * #parsers.blankline) -- blank line
                                   / "\n"
                                   + parsers.percent  -- comment
                                   * parsers.line
                                   * parsers.optionalspace)  -- leading tabs and spaces
                                 + #(parsers.newline)
                                 * Cb("backslashes")
                                 * C(parsers.newline))

parsers.chunk                  = parsers.line * (parsers.optionallyindentedline
                                                - parsers.blankline)^0

parsers.attribute_key_char     = parsers.alphanumeric + S("_-")
parsers.attribute_key          = (parsers.attribute_key_char
                                 - parsers.dash - parsers.digit)
                               * parsers.attribute_key_char^0
parsers.attribute_value        = ( (parsers.dquote / "")
                                 * (parsers.anyescaped - parsers.dquote)^0
                                 * (parsers.dquote / ""))
                               + ( parsers.anyescaped - parsers.dquote - parsers.rbrace
                                 - parsers.space)^0

parsers.attribute = (parsers.dash * Cc(".unnumbered"))
                  + C((parsers.hash + parsers.period)
                     * parsers.attribute_key)
                  + Cs( parsers.attribute_key
                      * parsers.optionalspace * parsers.equal * parsers.optionalspace
                      * parsers.attribute_value)
parsers.attributes = parsers.lbrace
                   * parsers.optionalspace
                   * parsers.attribute
                   * (parsers.spacechar^1
                     * parsers.attribute)^0
                   * parsers.optionalspace
                   * parsers.rbrace

-- block followed by 0 or more optionally
-- indented blocks with first line indented.
parsers.indented_blocks = function(bl)
  return Cs( bl
         * (parsers.blankline^1 * parsers.indent * -parsers.blankline * bl)^0
         * (parsers.blankline^1 + parsers.eof) )
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Parsers Used for Markdown Lists
%
% \end{markdown}
%  \begin{macrocode}
parsers.bulletchar = C(parsers.plus + parsers.asterisk + parsers.dash)

parsers.bullet = ( parsers.bulletchar * #parsers.spacing
                                      * (parsers.tab + parsers.space^-3)
                 + parsers.space * parsers.bulletchar * #parsers.spacing
                                 * (parsers.tab + parsers.space^-2)
                 + parsers.space * parsers.space * parsers.bulletchar
                                 * #parsers.spacing
                                 * (parsers.tab + parsers.space^-1)
                 + parsers.space * parsers.space * parsers.space
                                 * parsers.bulletchar * #parsers.spacing
                 )

local function tickbox(interior)
  return parsers.optionalspace * parsers.lbracket
       * interior * parsers.rbracket * parsers.spacechar^1
end

parsers.ticked_box = tickbox(S("xX")) * Cc(1.0)
parsers.halfticked_box = tickbox(S("./")) * Cc(0.5)
parsers.unticked_box = tickbox(parsers.spacechar^1) * Cc(0.0)

%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Parsers Used for Markdown Code Spans
%
% \end{markdown}
%  \begin{macrocode}
parsers.openticks   = Cg(parsers.backtick^1, "ticks")

local function captures_equal_length(_,i,a,b)
  return #a == #b and i
end

parsers.closeticks  = parsers.space^-1
                    * Cmt(C(parsers.backtick^1)
                         * Cb("ticks"), captures_equal_length)

parsers.intickschar = (parsers.any - S(" \n\r`"))
                    + (parsers.newline * -parsers.blankline)
                    + (parsers.space - parsers.closeticks)
                    + (parsers.backtick^1 - parsers.closeticks)

parsers.inticks     = parsers.openticks * parsers.space^-1
                    * C(parsers.intickschar^0) * parsers.closeticks
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Parsers Used for Fenced Code Blocks
%
% \end{markdown}
%  \begin{macrocode}
local function captures_geq_length(_,i,a,b)
  return #a >= #b and i
end

parsers.tilde_infostring
                     = C((parsers.linechar
                        - (parsers.spacechar^1 * parsers.newline))^0)
                     * parsers.optionalspace
                     * (parsers.newline + parsers.eof)

parsers.backtick_infostring
                     = C((parsers.linechar
                        - (parsers.backtick
                          + parsers.spacechar^1 * parsers.newline))^0)
                     * parsers.optionalspace
                     * (parsers.newline + parsers.eof)

local fenceindent
parsers.fencehead    = function(char, infostring)
  return               C(parsers.nonindentspace) / function(s) fenceindent = #s end
                     * Cg(char^3, "fencelength")
                     * parsers.optionalspace * infostring
end

parsers.fencehead_with_attributes
                     = function(char)
  return               C(parsers.nonindentspace) / function(s) fenceindent = #s end
                     * Cg(char^3, "fencelength")
                     * parsers.optionalspace * Ct(parsers.attributes)
                     * parsers.optionalspace * (parsers.newline + parsers.eof)
end

parsers.fencetail    = function(char)
  return               parsers.nonindentspace
                     * Cmt(C(char^3) * Cb("fencelength"), captures_geq_length)
                     * parsers.optionalspace * (parsers.newline + parsers.eof)
                     + parsers.eof
end

parsers.fencedline   = function(char)
  return               C(parsers.line - parsers.fencetail(char))
                     / function(s)
                         local i = 1
                         local remaining = fenceindent
                         while true do
                           local c = s:sub(i, i)
                           if c == " " and remaining > 0 then
                             remaining = remaining - 1
                             i = i + 1
                           elseif c == "\t" and remaining > 3 then
                             remaining = remaining - 4
                             i = i + 1
                           else
                             break
                           end
                         end
                         return s:sub(i)
                       end
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Parsers Used for Markdown Tags and Links
%
% \end{markdown}
%  \begin{macrocode}
parsers.leader      = parsers.space^-3

-- content in balanced brackets, parentheses, or quotes:
parsers.bracketed   = P{ parsers.lbracket
                       * (( parsers.backslash / "" * parsers.rbracket
                          + parsers.any - (parsers.lbracket
                                          + parsers.rbracket
                                          + parsers.blankline^2)
                          ) + V(1))^0
                       * parsers.rbracket }

parsers.inparens    = P{ parsers.lparent
                       * ((parsers.anyescaped - (parsers.lparent
                                                + parsers.rparent
                                                + parsers.blankline^2)
                          ) + V(1))^0
                       * parsers.rparent }

parsers.squoted     = P{ parsers.squote * parsers.alphanumeric
                       * ((parsers.anyescaped - (parsers.squote
                                                + parsers.blankline^2)
                          ) + V(1))^0
                       * parsers.squote }

parsers.dquoted     = P{ parsers.dquote * parsers.alphanumeric
                       * ((parsers.anyescaped - (parsers.dquote
                                                + parsers.blankline^2)
                          ) + V(1))^0
                       * parsers.dquote }

-- bracketed tag for markdown links, allowing nested brackets:
parsers.tag         = parsers.lbracket
                    * Cs((parsers.alphanumeric^1
                         + parsers.bracketed
                         + parsers.inticks
                         + ( parsers.backslash / "" * parsers.rbracket
                           + parsers.any
                           - (parsers.rbracket + parsers.blankline^2)))^0)
                    * parsers.rbracket

-- url for markdown links, allowing nested brackets:
parsers.url         = parsers.less * Cs((parsers.anyescaped
                                        - parsers.more)^0)
                                   * parsers.more
                    + Cs((parsers.inparens + (parsers.anyescaped
                                             - parsers.spacing
                                             - parsers.rparent))^1)

-- quoted text, possibly with nested quotes:
parsers.title_s     = parsers.squote * Cs(((parsers.anyescaped-parsers.squote)
                                           + parsers.squoted)^0)
                                     * parsers.squote

parsers.title_d     = parsers.dquote * Cs(((parsers.anyescaped-parsers.dquote)
                                           + parsers.dquoted)^0)
                                     * parsers.dquote

parsers.title_p     = parsers.lparent
                    * Cs((parsers.inparens + (parsers.anyescaped-parsers.rparent))^0)
                    * parsers.rparent

parsers.title       = parsers.title_d + parsers.title_s + parsers.title_p

parsers.optionaltitle
                    = parsers.spnl * parsers.title * parsers.spacechar^0
                    + Cc("")
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Parsers Used for HTML
%
% \end{markdown}
%  \begin{macrocode}
-- case-insensitive match (we assume s is lowercase). must be single byte encoding
parsers.keyword_exact = function(s)
  local parser = P(0)
  for i=1,#s do
    local c = s:sub(i,i)
    local m = c .. upper(c)
    parser = parser * S(m)
  end
  return parser
end

parsers.block_keyword =
    parsers.keyword_exact("address") + parsers.keyword_exact("blockquote") +
    parsers.keyword_exact("center") + parsers.keyword_exact("del") +
    parsers.keyword_exact("dir") + parsers.keyword_exact("div") +
    parsers.keyword_exact("p") + parsers.keyword_exact("pre") +
    parsers.keyword_exact("li") + parsers.keyword_exact("ol") +
    parsers.keyword_exact("ul") + parsers.keyword_exact("dl") +
    parsers.keyword_exact("dd") + parsers.keyword_exact("form") +
    parsers.keyword_exact("fieldset") + parsers.keyword_exact("isindex") +
    parsers.keyword_exact("ins") + parsers.keyword_exact("menu") +
    parsers.keyword_exact("noframes") + parsers.keyword_exact("frameset") +
    parsers.keyword_exact("h1") + parsers.keyword_exact("h2") +
    parsers.keyword_exact("h3") + parsers.keyword_exact("h4") +
    parsers.keyword_exact("h5") + parsers.keyword_exact("h6") +
    parsers.keyword_exact("hr") + parsers.keyword_exact("script") +
    parsers.keyword_exact("noscript") + parsers.keyword_exact("table") +
    parsers.keyword_exact("tbody") + parsers.keyword_exact("tfoot") +
    parsers.keyword_exact("thead") + parsers.keyword_exact("th") +
    parsers.keyword_exact("td") + parsers.keyword_exact("tr")

-- There is no reason to support bad html, so we expect quoted attributes
parsers.htmlattributevalue
                          = parsers.squote * (parsers.any - (parsers.blankline
                                                            + parsers.squote))^0
                                           * parsers.squote
                          + parsers.dquote * (parsers.any - (parsers.blankline
                                                            + parsers.dquote))^0
                                           * parsers.dquote

parsers.htmlattribute     = parsers.spacing^1
                          * (parsers.alphanumeric + S("_-"))^1
                          * parsers.sp * parsers.equal * parsers.sp
                          * parsers.htmlattributevalue

parsers.htmlcomment       = P("<!--")
                          * parsers.optionalspace
                          * Cs((parsers.any - parsers.optionalspace * P("-->"))^0)
                          * parsers.optionalspace
                          * P("-->")

parsers.htmlinstruction   = P("<?") * (parsers.any - P("?>"))^0 * P("?>")

parsers.openelt_any = parsers.less * parsers.keyword * parsers.htmlattribute^0
                    * parsers.sp * parsers.more

parsers.openelt_exact = function(s)
  return parsers.less * parsers.sp * parsers.keyword_exact(s)
       * parsers.htmlattribute^0 * parsers.sp * parsers.more
end

parsers.openelt_block = parsers.sp * parsers.block_keyword
                      * parsers.htmlattribute^0 * parsers.sp * parsers.more

parsers.closeelt_any = parsers.less * parsers.sp * parsers.slash
                     * parsers.keyword * parsers.sp * parsers.more

parsers.closeelt_exact = function(s)
  return parsers.less * parsers.sp * parsers.slash * parsers.keyword_exact(s)
       * parsers.sp * parsers.more
end

parsers.emptyelt_any = parsers.less * parsers.sp * parsers.keyword
                     * parsers.htmlattribute^0 * parsers.sp * parsers.slash
                     * parsers.more

parsers.emptyelt_block = parsers.less * parsers.sp * parsers.block_keyword
                       * parsers.htmlattribute^0 * parsers.sp * parsers.slash
                       * parsers.more

parsers.displaytext = (parsers.any - parsers.less)^1

-- return content between two matched HTML tags
parsers.in_matched = function(s)
  return { parsers.openelt_exact(s)
         * (V(1) + parsers.displaytext
           + (parsers.less - parsers.closeelt_exact(s)))^0
         * parsers.closeelt_exact(s) }
end

local function parse_matched_tags(s,pos)
  local t = string.lower(lpeg.match(C(parsers.keyword),s,pos))
  return lpeg.match(parsers.in_matched(t),s,pos-1)
end

parsers.in_matched_block_tags = parsers.less
                              * Cmt(#parsers.openelt_block, parse_matched_tags)

%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Parsers Used for HTML Entities
%
% \end{markdown}
%  \begin{macrocode}
parsers.hexentity = parsers.ampersand * parsers.hash * S("Xx")
                  * C(parsers.hexdigit^1) * parsers.semicolon
parsers.decentity = parsers.ampersand * parsers.hash
                  * C(parsers.digit^1) * parsers.semicolon
parsers.tagentity = parsers.ampersand * C(parsers.alphanumeric^1)
                  * parsers.semicolon
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Helpers for References
%
% \end{markdown}
%  \begin{macrocode}
-- parse a reference definition:  [foo]: /bar "title"
parsers.define_reference_parser = parsers.leader * parsers.tag * parsers.colon
                                * parsers.spacechar^0 * parsers.url
                                * parsers.optionaltitle * parsers.blankline^1
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Inline Elements
%
% \end{markdown}
%  \begin{macrocode}
parsers.Inline         = V("Inline")
parsers.IndentedInline = V("IndentedInline")

-- parse many p between starter and ender
parsers.between = function(p, starter, ender)
  local ender2 = B(parsers.nonspacechar) * ender
  return (starter * #parsers.nonspacechar * Ct(p * (p - ender2)^0) * ender2)
end

parsers.urlchar      = parsers.anyescaped - parsers.newline - parsers.more
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Block Elements
%
% \end{markdown}
%  \begin{macrocode}
parsers.TildeFencedCode
       = parsers.fencehead(parsers.tilde,
                           parsers.tilde_infostring)
       * Cs(parsers.fencedline(parsers.tilde)^0)
       * parsers.fencetail(parsers.tilde)

parsers.BacktickFencedCode
       = parsers.fencehead(parsers.backtick,
                           parsers.backtick_infostring)
       * Cs(parsers.fencedline(parsers.backtick)^0)
       * parsers.fencetail(parsers.backtick)

parsers.lineof = function(c)
    return (parsers.leader * (P(c) * parsers.optionalspace)^3
           * (parsers.newline * parsers.blankline^1
             + parsers.newline^-1 * parsers.eof))
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Headings
%
% \end{markdown}
%  \begin{macrocode}
-- parse Atx heading start and return level
parsers.heading_start = #parsers.hash * C(parsers.hash^-6)
                      * -parsers.hash / length

-- parse setext header ending and return level
parsers.heading_level = parsers.equal^1 * Cc(1) + parsers.dash^1 * Cc(2)

local function strip_atx_end(s)
  return s:gsub("[#%s]*\n$","")
end
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Markdown Reader {#markdownreader}
%
% This section documents the \luamref{reader} object, which implements the
% routines for parsing the markdown input. The object corresponds to the
% markdown reader object that was located in the
% `lunamark/reader/markdown.lua` file in the Lunamark Lua module.
%
% The \luamdef{reader.new} method creates and returns a new \TeX{} reader
% object associated with the Lua interface options (see Section
% <#sec:luaoptions>) `options` and with a writer object `writer`. When
% `options` are unspecified, it is assumed that an empty table was passed to
% the method.
%
% The objects produced by the \luamref{reader.new} method expose instance methods
% and variables of their own. As a convention, I will refer to these
% \meta{member}s as `reader->`\meta{member}.
%
% \end{markdown}
%  \begin{macrocode}
M.reader = {}
function M.reader.new(writer, options)
  local self = {}
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Make the `writer` and `options` parameters available as
% \luamdef{reader->writer} and \luamdef{reader->options}, respectively, so
% that they are accessible from extensions.
%
% \end{markdown}
%  \begin{macrocode}
  self.writer = writer
  self.options = options
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Create a \luamdef{reader->parsers} hash table that stores \acro{peg} patterns
% that depend on the received `options`. Make \luamref{reader->parsers} inherit
% from the global \luamref{parsers} table.
%
% \end{markdown}
%  \begin{macrocode}
  self.parsers = {}
  (function(parsers)
    setmetatable(self.parsers, {
      __index = function (_, key)
        return parsers[key]
      end
    })
  end)(parsers)
%    \end{macrocode}
% \begin{markdown}
%
% Make \luamref{reader->parsers} available as a local `parsers` variable that
% will shadow the global \luamref{parsers} table and will make
% \luamref{reader->parsers} easier to type in the rest of the reader code.
%
% \end{markdown}
%  \begin{macrocode}
  local parsers = self.parsers
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Top-Level Helper Functions
% Define \luamdef{reader->normalize_tag} as a function that normalizes a
% markdown reference tag by lowercasing it, and by collapsing any adjacent
% whitespace characters.
%
% \end{markdown}
%  \begin{macrocode}
  function self.normalize_tag(tag)
    return string.lower(
      gsub(util.rope_to_string(tag), "[ \n\r\t]+", " "))
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{iterlines} as a function that iterates over the lines of
% the input string `s`, transforms them using an input function `f`, and
% reassembles them into a new string, which it returns.
%
% \end{markdown}
%  \begin{macrocode}
  local function iterlines(s, f)
    local rope = lpeg.match(Ct((parsers.line / f)^1), s)
    return util.rope_to_string(rope)
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{expandtabs} either as an identity function, when the
% \Opt{preserveTabs} Lua interface option is enabled, or to a function that
% expands tabs into spaces otherwise.
%
% \end{markdown}
%  \begin{macrocode}
  if options.preserveTabs then
    self.expandtabs = function(s) return s end
  else
    self.expandtabs = function(s)
                        if s:find("\t") then
                          return iterlines(s, util.expand_tabs_in_line)
                        else
                          return s
                        end
                      end
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### High-Level Parser Functions
%
% Create a \luamdef{reader->parser_functions} hash table that stores high-level
% parser functions. Define \luamdef{reader->create_parser} as a function that
% will create a high-level parser function \luamdef{reader->parser_functions.name},
% that matches input using grammar `grammar`. If `toplevel` is true, the input
% is expected to come straight from the user, not from a recursive call, and
% will be preprocessed.
%
% \end{markdown}
%  \begin{macrocode}
  self.parser_functions = {}
  self.create_parser = function(name, grammar, toplevel)
    self.parser_functions[name] = function(str)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% If the parser function is top-level and the \Opt{stripIndent} Lua option is
% enabled, we will first expand tabs in the input string `str` into spaces
% and then we will count the minimum indent across all lines, skipping
% blank lines. Next, we will remove the minimum indent from all lines.
%
% \end{markdown}
%  \begin{macrocode}
      if toplevel and options.stripIndent then
          local min_prefix_length, min_prefix = nil, ''
          str = iterlines(str, function(line)
              if lpeg.match(parsers.nonemptyline, line) == nil then
                  return line
              end
              line = util.expand_tabs_in_line(line)
              local prefix = lpeg.match(C(parsers.optionalspace), line)
              local prefix_length = #prefix
              local is_shorter = min_prefix_length == nil
              is_shorter = is_shorter or prefix_length < min_prefix_length
              if is_shorter then
                  min_prefix_length, min_prefix = prefix_length, prefix
              end
              return line
          end)
          str = str:gsub('^' .. min_prefix, '')
      end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% If the parser is top-level and the \Opt{texComments} or \Opt{hybrid} Lua
% options are enabled, we will strip all plain \TeX{} comments from the input
% string `str` together with the trailing newline characters.
%
% \end{markdown}
%  \begin{macrocode}
      if toplevel and (options.texComments or options.hybrid) then
        str = lpeg.match(Ct(parsers.commented_line^1), str)
        str = util.rope_to_string(str)
      end
      local res = lpeg.match(grammar(), str)
      if res == nil then
        error(format("%s failed on:\n%s", name, str:sub(1,20)))
      else
        return res
      end
    end
  end

  self.create_parser("parse_blocks",
                     function()
                       return parsers.blocks
                     end, true)

  self.create_parser("parse_blocks_nested",
                     function()
                       return parsers.blocks_nested
                     end, false)

  self.create_parser("parse_inlines",
                     function()
                       return parsers.inlines
                     end, false)

  self.create_parser("parse_inlines_no_link",
                     function()
                       return parsers.inlines_no_link
                     end, false)

  self.create_parser("parse_inlines_no_inline_note",
                     function()
                       return parsers.inlines_no_inline_note
                     end, false)

  self.create_parser("parse_inlines_no_html",
                     function()
                       return parsers.inlines_no_html
                     end, false)

  self.create_parser("parse_inlines_nbsp",
                     function()
                       return parsers.inlines_nbsp
                     end, false)
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Parsers Used for Markdown Lists (local)
%
% \end{markdown}
%  \begin{macrocode}
  if options.hashEnumerators then
    parsers.dig = parsers.digit + parsers.hash
  else
    parsers.dig = parsers.digit
  end

  parsers.enumerator = C(parsers.dig^3 * parsers.period) * #parsers.spacing
                     + C(parsers.dig^2 * parsers.period) * #parsers.spacing
                                       * (parsers.tab + parsers.space^1)
                     + C(parsers.dig * parsers.period) * #parsers.spacing
                                     * (parsers.tab + parsers.space^-2)
                     + parsers.space * C(parsers.dig^2 * parsers.period)
                                     * #parsers.spacing
                     + parsers.space * C(parsers.dig * parsers.period)
                                     * #parsers.spacing
                                     * (parsers.tab + parsers.space^-1)
                     + parsers.space * parsers.space * C(parsers.dig^1
                                     * parsers.period) * #parsers.spacing
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Parsers Used for Blockquotes (local)
%
% \end{markdown}
%  \begin{macrocode}
  -- strip off leading > and indents, and run through blocks
  parsers.blockquote_body = ((parsers.leader * parsers.more * parsers.space^-1)/""
                             * parsers.linechar^0 * parsers.newline)^1
                            * (-(parsers.leader * parsers.more
                                + parsers.blankline) * parsers.linechar^1
                              * parsers.newline)^0

  if not options.breakableBlockquotes then
    parsers.blockquote_body = parsers.blockquote_body
                            * (parsers.blankline^0 / "")
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Helpers for Links and References (local)
%
% \end{markdown}
%  \begin{macrocode}
  -- List of references defined in the document
  local references

  -- add a reference to the list
  local function register_link(tag,url,title)
      references[self.normalize_tag(tag)] = { url = url, title = title }
      return ""
  end

  -- lookup link reference and return either
  -- the link or nil and fallback text.
  local function lookup_reference(label,sps,tag)
      local tagpart
      if not tag then
          tag = label
          tagpart = ""
      elseif tag == "" then
          tag = label
          tagpart = "[]"
      else
          tagpart = {"[",
            self.parser_functions.parse_inlines(tag),
            "]"}
      end
      if sps then
        tagpart = {sps, tagpart}
      end
      local r = references[self.normalize_tag(tag)]
      if r then
        return r
      else
        return nil, {"[",
          self.parser_functions.parse_inlines(label),
          "]", tagpart}
      end
  end

  -- lookup link reference and return a link, if the reference is found,
  -- or a bracketed label otherwise.
  local function indirect_link(label,sps,tag)
    return writer.defer_call(function()
      local r,fallback = lookup_reference(label,sps,tag)
      if r then
        return writer.link(
          self.parser_functions.parse_inlines_no_link(label),
          r.url, r.title)
      else
        return fallback
      end
    end)
  end

  -- lookup image reference and return an image, if the reference is found,
  -- or a bracketed label otherwise.
  local function indirect_image(label,sps,tag)
    return writer.defer_call(function()
      local r,fallback = lookup_reference(label,sps,tag)
      if r then
        return writer.image(writer.string(label), r.url, r.title)
      else
        return {"!", fallback}
      end
    end)
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Inline Elements (local)
%
% \end{markdown}
%  \begin{macrocode}
  parsers.Str      = (parsers.normalchar * (parsers.normalchar + parsers.at)^0)
                   / writer.string

  parsers.Symbol   = (V("SpecialChar") - parsers.tightblocksep)
                   / writer.string

  parsers.Ellipsis = P("...") / writer.ellipsis

  parsers.Smart    = parsers.Ellipsis

  parsers.Code     = parsers.inticks / writer.code

  if options.blankBeforeBlockquote then
    parsers.bqstart = parsers.fail
  else
    parsers.bqstart = parsers.more
  end

  if options.blankBeforeHeading then
    parsers.headerstart = parsers.fail
  else
    parsers.headerstart = parsers.hash
                        + (parsers.line * (parsers.equal^1 + parsers.dash^1)
                        * parsers.optionalspace * parsers.newline)
  end

  parsers.EndlineExceptions
                     = parsers.blankline -- paragraph break
                     + parsers.tightblocksep  -- nested list
                     + parsers.eof       -- end of document
                     + parsers.bqstart
                     + parsers.headerstart

  parsers.Endline   = parsers.newline
                    * -V("EndlineExceptions")
                    * parsers.spacechar^0
                    / (options.hardLineBreaks and writer.linebreak
                                               or writer.space)

  parsers.OptionalIndent
                     = parsers.spacechar^1 / writer.space

  parsers.Space      = parsers.spacechar^2 * parsers.Endline / writer.linebreak
                     + parsers.spacechar^1 * parsers.Endline^-1 * parsers.eof / ""
                     + parsers.spacechar^1 * parsers.Endline
                                           * parsers.optionalspace
                                           / (options.hardLineBreaks
                                              and writer.linebreak
                                               or writer.space)
                     + parsers.spacechar^1 * parsers.optionalspace
                                           / writer.space

  parsers.NonbreakingEndline
                    = parsers.newline
                    * -V("EndlineExceptions")
                    * parsers.spacechar^0
                    / (options.hardLineBreaks and writer.linebreak
                                               or writer.nbsp)

  parsers.NonbreakingSpace
                  = parsers.spacechar^2 * parsers.Endline / writer.linebreak
                  + parsers.spacechar^1 * parsers.Endline^-1 * parsers.eof / ""
                  + parsers.spacechar^1 * parsers.Endline
                                        * parsers.optionalspace
                                        / (options.hardLineBreaks
                                           and writer.linebreak
                                            or writer.nbsp)
                  + parsers.spacechar^1 * parsers.optionalspace
                                        / writer.nbsp

  if options.underscores then
    parsers.Strong = ( parsers.between(parsers.Inline, parsers.doubleasterisks,
                                       parsers.doubleasterisks)
                     + parsers.between(parsers.Inline, parsers.doubleunderscores,
                                       parsers.doubleunderscores)
                     ) / writer.strong

    parsers.Emph   = ( parsers.between(parsers.Inline, parsers.asterisk,
                                       parsers.asterisk)
                     + parsers.between(parsers.Inline, parsers.underscore,
                                       parsers.underscore)
                     ) / writer.emphasis
  else
    parsers.Strong = ( parsers.between(parsers.Inline, parsers.doubleasterisks,
                                       parsers.doubleasterisks)
                     ) / writer.strong

    parsers.Emph   = ( parsers.between(parsers.Inline, parsers.asterisk,
                                       parsers.asterisk)
                     ) / writer.emphasis
  end

  parsers.AutoLinkUrl    = parsers.less
                         * C(parsers.alphanumeric^1 * P("://") * parsers.urlchar^1)
                         * parsers.more
                         / function(url)
                             return writer.link(writer.escape(url), url)
                           end

  parsers.AutoLinkEmail = parsers.less
                        * C((parsers.alphanumeric + S("-._+"))^1
                        * P("@") * parsers.urlchar^1)
                        * parsers.more
                        / function(email)
                            return writer.link(writer.escape(email),
                                               "mailto:"..email)
                          end

  parsers.AutoLinkRelativeReference
                         = parsers.less
                         * C(parsers.urlchar^1)
                         * parsers.more
                         / function(url)
                             return writer.link(writer.escape(url), url)
                           end

  parsers.DirectLink    = (parsers.tag / self.parser_functions.parse_inlines_no_link)
                        * parsers.spnl
                        * parsers.lparent
                        * (parsers.url + Cc(""))  -- link can be empty [foo]()
                        * parsers.optionaltitle
                        * parsers.rparent
                        / writer.link

  parsers.IndirectLink  = parsers.tag * (C(parsers.spnl) * parsers.tag)^-1
                        / indirect_link

  -- parse a link or image (direct or indirect)
  parsers.Link          = parsers.DirectLink + parsers.IndirectLink

  parsers.DirectImage   = parsers.exclamation
                        * (parsers.tag / self.parser_functions.parse_inlines)
                        * parsers.spnl
                        * parsers.lparent
                        * (parsers.url + Cc(""))  -- link can be empty [foo]()
                        * parsers.optionaltitle
                        * parsers.rparent
                        / writer.image

  parsers.IndirectImage = parsers.exclamation * parsers.tag
                        * (C(parsers.spnl) * parsers.tag)^-1 / indirect_image

  parsers.Image         = parsers.DirectImage + parsers.IndirectImage

  -- avoid parsing long strings of * or _ as emph/strong
  parsers.UlOrStarLine  = parsers.asterisk^4 + parsers.underscore^4
                        / writer.string

  parsers.EscapedChar   = parsers.backslash * C(parsers.escapable) / writer.string
  
  parsers.InlineHtml    = parsers.emptyelt_any / writer.inline_html_tag
                        + (parsers.htmlcomment / self.parser_functions.parse_inlines_no_html)
                        / writer.inline_html_comment
                        + parsers.htmlinstruction
                        + parsers.openelt_any / writer.inline_html_tag
                        + parsers.closeelt_any / writer.inline_html_tag
  
  parsers.HtmlEntity    = parsers.hexentity / entities.hex_entity  / writer.string
                        + parsers.decentity / entities.dec_entity  / writer.string
                        + parsers.tagentity / entities.char_entity / writer.string
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Block Elements (local)
%
% \end{markdown}
%  \begin{macrocode}
  parsers.DisplayHtml  = (parsers.htmlcomment / self.parser_functions.parse_blocks_nested)
                       / writer.block_html_comment
                       + parsers.emptyelt_block / writer.block_html_element
                       + parsers.openelt_exact("hr") / writer.block_html_element
                       + parsers.in_matched_block_tags / writer.block_html_element
                       + parsers.htmlinstruction

  parsers.Verbatim     = Cs( (parsers.blanklines
                           * ((parsers.indentedline - parsers.blankline))^1)^1
                           ) / self.expandtabs / writer.verbatim

  parsers.Blockquote   = Cs(parsers.blockquote_body^1)
                       / self.parser_functions.parse_blocks_nested
                       / writer.blockquote

  parsers.ThematicBreak = ( parsers.lineof(parsers.asterisk)
                          + parsers.lineof(parsers.dash)
                          + parsers.lineof(parsers.underscore)
                          ) / writer.thematic_break

  parsers.Reference    = parsers.define_reference_parser / register_link

  parsers.Paragraph    = parsers.nonindentspace * Ct(parsers.Inline^1)
                       * ( parsers.newline
                       * ( parsers.blankline^1
                         + #parsers.hash
                         + #(parsers.leader * parsers.more * parsers.space^-1)
                         + parsers.eof
                         )
                       + parsers.eof )
                       / writer.paragraph

  parsers.Plain        = parsers.nonindentspace * Ct(parsers.Inline^1)
                       / writer.plain
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Lists (local)
%
% \end{markdown}
%  \begin{macrocode}
  parsers.starter = parsers.bullet + parsers.enumerator

  if options.taskLists then
    parsers.tickbox = ( parsers.ticked_box
                      + parsers.halfticked_box
                      + parsers.unticked_box
                      ) / writer.tickbox
  else
     parsers.tickbox = parsers.fail
  end

  -- we use \001 as a separator between a tight list item and a
  -- nested list under it.
  parsers.NestedList            = Cs((parsers.optionallyindentedline
                                     - parsers.starter)^1)
                                / function(a) return "\001"..a end

  parsers.ListBlockLine         = parsers.optionallyindentedline
                                - parsers.blankline - (parsers.indent^-1
                                                      * parsers.starter)

  parsers.ListBlock             = parsers.line * parsers.ListBlockLine^0

  parsers.ListContinuationBlock = parsers.blanklines * (parsers.indent / "")
                                * parsers.ListBlock

  parsers.TightListItem = function(starter)
      return -parsers.ThematicBreak
             * (Cs(starter / "" * parsers.tickbox^-1 * parsers.ListBlock * parsers.NestedList^-1)
               / self.parser_functions.parse_blocks_nested)
             * -(parsers.blanklines * parsers.indent)
  end

  parsers.LooseListItem = function(starter)
      return -parsers.ThematicBreak
             * Cs( starter / "" * parsers.tickbox^-1 * parsers.ListBlock * Cc("\n")
               * (parsers.NestedList + parsers.ListContinuationBlock^0)
               * (parsers.blanklines / "\n\n")
               ) / self.parser_functions.parse_blocks_nested
  end

  parsers.BulletList = ( Ct(parsers.TightListItem(parsers.bullet)^1) * Cc(true)
                       * parsers.skipblanklines * -parsers.bullet
                       + Ct(parsers.LooseListItem(parsers.bullet)^1) * Cc(false)
                       * parsers.skipblanklines )
                     / writer.bulletlist

  local function ordered_list(items,tight,startnum)
    if options.startNumber then
      startnum = tonumber(startnum) or 1  -- fallback for '#'
      if startnum ~= nil then
        startnum = math.floor(startnum)
      end
    else
      startnum = nil
    end
    return writer.orderedlist(items,tight,startnum)
  end

  parsers.OrderedList = Cg(parsers.enumerator, "listtype") *
                      ( Ct(parsers.TightListItem(Cb("listtype"))
                          * parsers.TightListItem(parsers.enumerator)^0)
                      * Cc(true) * parsers.skipblanklines * -parsers.enumerator
                      + Ct(parsers.LooseListItem(Cb("listtype"))
                          * parsers.LooseListItem(parsers.enumerator)^0)
                      * Cc(false) * parsers.skipblanklines
                      ) * Cb("listtype") / ordered_list
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Blank (local)
%
% \end{markdown}
%  \begin{macrocode}
  parsers.Blank        = parsers.blankline / ""
                       + parsers.Reference
                       + (parsers.tightblocksep / "\n")
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Headings (local)
%
% \end{markdown}
%  \begin{macrocode}
  -- parse atx header
  parsers.AtxHeading = Cg(parsers.heading_start, "level")
                     * parsers.optionalspace
                     * (C(parsers.line)
                       / strip_atx_end
                       / self.parser_functions.parse_inlines)
                     * Cb("level")
                     / writer.heading

  parsers.SetextHeading = #(parsers.line * S("=-"))
                        * Ct(parsers.linechar^1
                            / self.parser_functions.parse_inlines)
                        * parsers.newline
                        * parsers.heading_level
                        * parsers.optionalspace
                        * parsers.newline
                        / writer.heading

  parsers.Heading = parsers.AtxHeading + parsers.SetextHeading
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Syntax Specification
% Define \luamdef{reader->finalize_grammar} as a function that constructs the
% \acro{peg} grammar of markdown, applies syntax extensions `extensions` and
% returns a conversion function that takes a markdown string and turns it into
% a plain \TeX{} output.
%
% \end{markdown}
%  \begin{macrocode}
  function self.finalize_grammar(extensions)
%    \end{macrocode}
% \begin{markdown}
%
% Create a local writable copy of the global read-only
% \luamref{walkable_syntax} hash table. This table can be used by user-defined
% syntax extensions to insert new \acro{peg} patterns into existing rules
% of the \acro{peg} grammar of markdown using
% the \luamref{reader->insert_pattern} method. Furthermore, built-in syntax
% extensions can use this table to override existing rules using the
% \luamref{reader->update_rule} method.
%
% \end{markdown}
%  \begin{macrocode}
    local walkable_syntax = (function(global_walkable_syntax)
      local local_walkable_syntax = {}
      for lhs, rule in pairs(global_walkable_syntax) do
        local_walkable_syntax[lhs] = util.table_copy(rule)
      end
      return local_walkable_syntax
    end)(walkable_syntax)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamref{reader->insert_pattern} method adds a pattern to
% \luamref{walkable_syntax}`[`*left-hand side terminal symbol*`]` before,
% instead of, or after a right-hand-side terminal symbol.
%
% \end{markdown}
%  \begin{macrocode}
    local current_extension_name = nil
    self.insert_pattern = function(selector, pattern, pattern_name)
      assert(pattern_name == nil or type(pattern_name) == "string")
      local _, _, lhs, pos, rhs = selector:find("^(%a+)%s+([%a%s]+%a+)%s+(%a+)$")
      assert(lhs ~= nil,
        [[Expected selector in form "LHS (before|after|instead of) RHS", not "]]
        .. selector .. [["]])
      assert(walkable_syntax[lhs] ~= nil,
        [[Rule ]] .. lhs .. [[ -> ... does not exist in markdown grammar]])
      assert(pos == "before" or pos == "after" or pos == "instead of",
        [[Expected positional specifier "before", "after", or "instead of", not "]]
        .. pos .. [["]])
      local rule = walkable_syntax[lhs]
      local index = nil
      for current_index, current_rhs in ipairs(rule) do
        if type(current_rhs) == "string" and current_rhs == rhs then
          index = current_index
          if pos == "after" then
            index = index + 1
          end
          break
        end
      end
      assert(index ~= nil,
        [[Rule ]] .. lhs .. [[ -> ]] .. rhs
          .. [[ does not exist in markdown grammar]])
      local accountable_pattern
      if current_extension_name then
        accountable_pattern = { pattern, current_extension_name, pattern_name }
      else
        assert(type(pattern) == "string",
          [[reader->insert_pattern() was called outside an extension with ]]
          .. [[a PEG pattern instead of a rule name]])
        accountable_pattern = pattern
      end
      if pos == "instead of" then
        rule[index] = accountable_pattern
      else
        table.insert(rule, index, accountable_pattern)
      end
    end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Create a local \luamdef{syntax} hash table that stores those rules of the
% \acro{peg} grammar of markdown that can't be represented as an ordered choice
% of terminal symbols.
%
% \end{markdown}
%  \begin{macrocode}
    local syntax =
      { "Blocks",

        Blocks                = V("InitializeState")
                              * ( V("ExpectedJekyllData")
                                * (V("Blank")^0 / writer.interblocksep))^-1
                              * V("Blank")^0
                              * V("Block")^-1
                              * ( V("Blank")^0 / writer.interblocksep
                                * V("Block"))^0
                              * V("Blank")^0 * parsers.eof,

        ExpectedJekyllData    = parsers.fail,

        Blank                 = parsers.Blank,

        Blockquote            = parsers.Blockquote,
        Verbatim              = parsers.Verbatim,
        ThematicBreak         = parsers.ThematicBreak,
        BulletList            = parsers.BulletList,
        OrderedList           = parsers.OrderedList,
        Heading               = parsers.Heading,
        DisplayHtml           = parsers.DisplayHtml,
        Paragraph             = parsers.Paragraph,
        Plain                 = parsers.Plain,
        EndlineExceptions     = parsers.EndlineExceptions,

        Str                   = parsers.Str,
        Space                 = parsers.Space,
        OptionalIndent        = parsers.OptionalIndent,
        Endline               = parsers.Endline,
        UlOrStarLine          = parsers.UlOrStarLine,
        Strong                = parsers.Strong,
        Emph                  = parsers.Emph,
        Link                  = parsers.Link,
        Image                 = parsers.Image,
        Code                  = parsers.Code,
        AutoLinkUrl           = parsers.AutoLinkUrl,
        AutoLinkEmail         = parsers.AutoLinkEmail,
        AutoLinkRelativeReference
                              = parsers.AutoLinkRelativeReference,
        InlineHtml            = parsers.InlineHtml,
        HtmlEntity            = parsers.HtmlEntity,
        EscapedChar           = parsers.EscapedChar,
        Smart                 = parsers.Smart,
        Symbol                = parsers.Symbol,
        SpecialChar           = parsers.fail,
        InitializeState       = parsers.succeed,
      }
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamref{reader->update_rule} as a function that receives two
% arguments: a left-hand side terminal symbol and a function that accepts
% the current \acro{peg} pattern in \luamref{walkable_syntax}`[`left-hand side
% terminal symbol`]` if defined or `nil` otherwise and returns a
% \acro{peg} pattern that will (re)define \luamref{walkable_syntax}`[`left-hand
% side terminal symbol`]`.
%
% \end{markdown}
%  \begin{macrocode}
    self.update_rule = function(rule_name, get_pattern)
      assert(current_extension_name ~= nil)
      assert(syntax[rule_name] ~= nil,
        [[Rule ]] .. rule_name .. [[ -> ... does not exist in markdown grammar]])
      local previous_pattern
      local extension_name
      if walkable_syntax[rule_name] then
        local previous_accountable_pattern = walkable_syntax[rule_name][1]
        previous_pattern = previous_accountable_pattern[1]
        extension_name = previous_accountable_pattern[2] .. ", " .. current_extension_name
      else
        previous_pattern = nil
        extension_name = current_extension_name
      end
      local pattern = get_pattern(previous_pattern)
      local accountable_pattern = { pattern, extension_name, rule_name }
      walkable_syntax[rule_name] = { accountable_pattern }
    end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define a hash table of all characters with special meaning and add method
% \luamref{reader->add_special_character} that extends the hash table and
% updates the \acro{peg} grammar of markdown.
%
% \end{markdown}
%  \begin{macrocode}
    local special_characters = {}
    self.add_special_character = function(c)
      table.insert(special_characters, c)
      syntax.SpecialChar = S(table.concat(special_characters, ""))
    end

    self.add_special_character("*")
    self.add_special_character("`")
    self.add_special_character("[")
    self.add_special_character("]")
    self.add_special_character("<")
    self.add_special_character("!")
    self.add_special_character("\\")
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Add method \luamdef{reader->initialize_named_group} that defines named groups
% with a default capture value.
%
% \end{markdown}
%  \begin{macrocode}
    self.initialize_named_group = function(name, value)
      syntax.InitializeState = syntax.InitializeState
                             * Cg(Ct("") / value, name)
    end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Apply syntax extensions.
%
% \end{markdown}
%  \begin{macrocode}
    for _, extension in ipairs(extensions) do
      current_extension_name = extension.name
      extension.extend_writer(writer)
      extension.extend_reader(self)
    end
    current_extension_name = nil
%    \end{macrocode}
% \par
% \begin{markdown}
%
% If the \Opt{debugExtensions} option is enabled, serialize
% \luamref{walkable_syntax} to a \acro{JSON} for debugging purposes.
%
% \end{markdown}
%  \begin{macrocode}
    if options.debugExtensions then
      local sorted_lhs = {}
      for lhs, _ in pairs(walkable_syntax) do
        table.insert(sorted_lhs, lhs)
      end
      table.sort(sorted_lhs)

      local output_lines = {"{"}
      for lhs_index, lhs in ipairs(sorted_lhs) do
        local encoded_lhs = util.encode_json_string(lhs)
        table.insert(output_lines, [[    ]] ..encoded_lhs .. [[: []])
        local rule = walkable_syntax[lhs]
        for rhs_index, rhs in ipairs(rule) do
          local human_readable_rhs
          if type(rhs) == "string" then
            human_readable_rhs = rhs
          else
            local pattern_name
            if rhs[3] then
              pattern_name = rhs[3]
            else
              pattern_name = "Anonymous Pattern"
            end
            local extension_name = rhs[2]
            human_readable_rhs = pattern_name .. [[ (]] .. extension_name .. [[)]]
          end
          local encoded_rhs = util.encode_json_string(human_readable_rhs)
          local output_line = [[        ]] .. encoded_rhs
          if rhs_index < #rule then
            output_line = output_line .. ","
          end
          table.insert(output_lines, output_line)
        end
        local output_line = "    ]"
        if lhs_index < #sorted_lhs then
          output_line = output_line .. ","
        end
        table.insert(output_lines, output_line)
      end
      table.insert(output_lines, "}")

      local output = table.concat(output_lines, "\n")
      local output_filename = options.debugExtensionsFileName
      local output_file = assert(io.open(output_filename, "w"),
        [[Could not open file "]] .. output_filename .. [[" for writing]])
      assert(output_file:write(output))
      assert(output_file:close())
    end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Duplicate the `Inline` rule as `IndentedInline` with the right-hand-side
% terminal symbol `Space` replaced with `OptionalIndent`.
%
% \end{markdown}
%  \begin{macrocode}
    walkable_syntax["IndentedInline"] = util.table_copy(
      walkable_syntax["Inline"])
    self.insert_pattern(
      "IndentedInline instead of Space",
      "OptionalIndent")
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Materialize \luamref{walkable_syntax} and merge it into \luamref{syntax} to
% produce the complete \acro{peg} grammar of markdown. Whenever a rule exists
% in both \luamref{walkable_syntax} and \luamref{syntax}, the rule from
% \luamref{walkable_syntax} overrides the rule from \luamref{syntax}.
%
% \end{markdown}
%  \begin{macrocode}
    for lhs, rule in pairs(walkable_syntax) do
      syntax[lhs] = parsers.fail
      for _, rhs in ipairs(rule) do
        local pattern
%    \end{macrocode}
% \begin{markdown}
%
% Although the interface of the \luamref{reader->insert_pattern} method does
% document this (see Section <#sec:luauserextensions>), we allow the
% \luamref{reader->insert_pattern} and \luamref{reader->update_rule}
% methods to insert not just \acro{peg} patterns, but also rule names that
% reference the \acro{peg} grammar of Markdown.
%
% \end{markdown}
%  \begin{macrocode}
        if type(rhs) == "string" then
          pattern = V(rhs)
        else
          pattern = rhs[1]
          if type(pattern) == "string" then
            pattern = V(pattern)
          end
        end
        syntax[lhs] = syntax[lhs] + pattern
      end
    end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Finalize the parser by reacting to options and by producing special parsers
% for difficult edge cases such as blocks nested in definition lists or
% inline content nested in link, note, and image labels.
%
% \end{markdown}
%  \begin{macrocode}
    if options.underscores then
      self.add_special_character("_")
    end

    if not options.codeSpans then
      syntax.Code = parsers.fail
    end

    if not options.html then
      syntax.DisplayHtml = parsers.fail
      syntax.InlineHtml = parsers.fail
      syntax.HtmlEntity  = parsers.fail
    else
      self.add_special_character("&")
    end

    if options.preserveTabs then
      options.stripIndent = false
    end

    if not options.smartEllipses then
      syntax.Smart = parsers.fail
    else
      self.add_special_character(".")
    end

    if not options.relativeReferences then
      syntax.AutoLinkRelativeReference = parsers.fail
    end

    local blocks_nested_t = util.table_copy(syntax)
    blocks_nested_t.ExpectedJekyllData = parsers.fail
    parsers.blocks_nested = Ct(blocks_nested_t)

    parsers.blocks = Ct(syntax)

    local inlines_t = util.table_copy(syntax)
    inlines_t[1] = "Inlines"
    inlines_t.Inlines = V("InitializeState")
                      * parsers.Inline^0
                      * ( parsers.spacing^0
                        * parsers.eof / "")
    parsers.inlines = Ct(inlines_t)

    local inlines_no_link_t = util.table_copy(inlines_t)
    inlines_no_link_t.Link = parsers.fail
    parsers.inlines_no_link = Ct(inlines_no_link_t)

    local inlines_no_inline_note_t = util.table_copy(inlines_t)
    inlines_no_inline_note_t.InlineNote = parsers.fail
    parsers.inlines_no_inline_note = Ct(inlines_no_inline_note_t)

    local inlines_no_html_t = util.table_copy(inlines_t)
    inlines_no_html_t.DisplayHtml = parsers.fail
    inlines_no_html_t.InlineHtml = parsers.fail
    inlines_no_html_t.HtmlEntity = parsers.fail
    parsers.inlines_no_html = Ct(inlines_no_html_t)

    local inlines_nbsp_t = util.table_copy(inlines_t)
    inlines_nbsp_t.Endline = parsers.NonbreakingEndline
    inlines_nbsp_t.Space = parsers.NonbreakingSpace
    parsers.inlines_nbsp = Ct(inlines_nbsp_t)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Return a function that converts markdown string `input` into a plain \TeX{}
% output and returns it. Note that the converter assumes that the input has
% \acro{unix} line endings.
%
% \end{markdown}
%  \begin{macrocode}
    return function(input)
      references = {}
%    \end{macrocode}
% \begin{markdown}
% When determining the name of the cache file, create salt for the hashing
% function out of the package version and the passed options recognized by the
% Lua interface (see Section <#sec:luaoptions>). The \Opt{cacheDir} option
% is disregarded.
% \end{markdown}
%  \begin{macrocode}
      local opt_string = {}
      for k, _ in pairs(defaultOptions) do
        local v = options[k]
        if type(v) == "table" then
          for _, i in ipairs(v) do
            opt_string[#opt_string+1] = k .. "=" .. tostring(i)
          end
        elseif k ~= "cacheDir" then
          opt_string[#opt_string+1] = k .. "=" .. tostring(v)
        end
      end
      table.sort(opt_string)
      local salt = table.concat(opt_string, ",") .. "," .. metadata.version
      local output
%    \end{macrocode}
% \begin{markdown}
% If we cache markdown documents, produce the cache file and transform its
% filename to plain \TeX{} output via the \luamref{writer->pack} method.
% \end{markdown}
%  \begin{macrocode}
      local function convert(input)
        local document = self.parser_functions.parse_blocks(input)
        return util.rope_to_string(writer.document(document))
      end
      if options.eagerCache or options.finalizeCache then
        local name = util.cache(options.cacheDir, input, salt, convert,
                                ".md" .. writer.suffix)
        output = writer.pack(name)
%    \end{macrocode}
% \begin{markdown}
% Otherwise, return the result of the conversion directly.
% \end{markdown}
%  \begin{macrocode}
      else
        output = convert(input)
      end
%    \end{macrocode}
% \begin{markdown}
% If the \Opt{finalizeCache} option is enabled, populate the frozen cache in
% the file \Opt{frozenCacheFileName} with an entry for markdown document
% number \Opt{frozenCacheCounter}.
% \end{markdown}
%  \begin{macrocode}
      if options.finalizeCache then
        local file, mode
        if options.frozenCacheCounter > 0 then
          mode = "a"
        else
          mode = "w"
        end
        file = assert(io.open(options.frozenCacheFileName, mode),
          [[Could not open file "]] .. options.frozenCacheFileName
          .. [[" for writing]])
        assert(file:write([[\expandafter\global\expandafter\def\csname ]]
          .. [[markdownFrozenCache]] .. options.frozenCacheCounter
          .. [[\endcsname{]] .. output .. [[}]] .. "\n"))
        assert(file:close())
      end
      return output
    end
  end
  return self
end
%    \end{macrocode}
% \begin{markdown}
%
%### Built-In Syntax Extensions {#luabuiltinextensions}
%
% Create \luamref{extensions} hash table that contains built-in syntax
% extensions. Syntax extensions are functions that produce objects with two
% methods: `extend_writer` and `extend_reader`. The `extend_writer` object
% takes a \luamref{writer} object as the only parameter and mutates it.
% Similarly, `extend_reader` takes a \luamref{reader} object as the only
% parameter and mutates it.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions = {}
%    \end{macrocode}
% \begin{markdown}
%
%#### Bracketed Spans
%
% The \luamdef{extensions.bracketed_spans} function implements the Pandoc
% bracketed spans syntax extension.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.bracketed_spans = function()
  return {
    name = "built-in bracketed_spans syntax extension",
    extend_writer = function(self)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->span} as a function that will transform an input
% bracketed span `s` with attributes `attr` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
      function self.span(s, attr)
        return {"\\markdownRendererBracketedSpanAttributeContextBegin",
                self.attributes(attr),
                s,
                "\\markdownRendererBracketedSpanAttributeContextEnd{}"}
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer

      local Span = parsers.between(parsers.Inline,
                                   parsers.lbracket,
                                   parsers.rbracket)
                 * Ct(parsers.attributes)
                 / writer.span

      self.insert_pattern("Inline after Emph",
                          Span, "Span")
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Citations
%
% The \luamdef{extensions.citations} function implements the Pandoc citation
% syntax extension. When the `citation_nbsps` parameter is enabled, the syntax
% extension will replace regular spaces with non-breaking spaces inside the
% prenotes and postnotes of citations.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.citations = function(citation_nbsps)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define table \luamdef{escaped_citation_chars} containing the characters to
% escape in citations.
%
% \end{markdown}
%  \begin{macrocode}
  local escaped_citation_chars = {
    ["{"] = "\\markdownRendererLeftBrace{}",
    ["}"] = "\\markdownRendererRightBrace{}",
    ["%"] = "\\markdownRendererPercentSign{}",
    ["\\"] = "\\markdownRendererBackslash{}",
    ["#"] = "\\markdownRendererHash{}",
  }
  return {
    name = "built-in citations syntax extension",
    extend_writer = function(self)
      local options = self.options

%    \end{macrocode}
% \par
% \begin{markdown}
%
% Use the \luamref{escaped_citation_chars} to create the
% \luamdef{escape_citation} escaper functions.
%
% \end{markdown}
%  \begin{macrocode}
      local escape_citation = util.escaper(
        escaped_citation_chars,
        self.escaped_minimal_strings)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->citation} as a function that will transform an input
% citation name `c` to the output format. If option \Opt{hybrid} is enabled,
% use the \luamref{writer->escape_minimal} function. Otherwise, use the
% \luamref{escape_citation} function.
%
% \end{markdown}
%  \begin{macrocode}
      if options.hybrid then
        self.citation = self.escape_minimal
      else
        self.citation = escape_citation
      end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->citations} as a function that will transform an
% input array of citations `cites` to the output format. If `text_cites`
% is enabled, the citations should be rendered in-text, when applicable.
% The `cites` array contains tables with the following keys and values:
% \begin{itemize}
%   \item`suppress_author` -- If the value of the key is true, then the
%     author of the work should be omitted in the citation, when applicable.
%   \item`prenote` -- The value of the key is either `nil` or a rope
%     that should be inserted before the citation.
%   \item`postnote` -- The value of the key is either `nil` or a rope
%     that should be inserted after the citation.
%   \item`name` -- The value of this key is the citation name.
% \end{itemize}
%
% \end{markdown}
%  \begin{macrocode}
      function self.citations(text_cites, cites)
        local buffer = {"\\markdownRenderer", text_cites and "TextCite" or "Cite",
          "{", #cites, "}"}
        for _,cite in ipairs(cites) do
          buffer[#buffer+1] = {cite.suppress_author and "-" or "+", "{",
            cite.prenote or "", "}{", cite.postnote or "", "}{", cite.name, "}"}
        end
        return buffer
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer

      local citation_chars
                    = parsers.alphanumeric
                    + S("#$%&-+<>~/_")

      local citation_name
                    = Cs(parsers.dash^-1) * parsers.at
                    * Cs(citation_chars
                        * (((citation_chars + parsers.internal_punctuation
                            - parsers.comma - parsers.semicolon)
                           * -#((parsers.internal_punctuation - parsers.comma
                                - parsers.semicolon)^0
                               * -(citation_chars + parsers.internal_punctuation
                                  - parsers.comma - parsers.semicolon)))^0
                          * citation_chars)^-1)

      local citation_body_prenote
                    = Cs((parsers.alphanumeric^1
                         + parsers.bracketed
                         + parsers.inticks
                         + (parsers.anyescaped
                           - (parsers.rbracket + parsers.blankline^2))
                         - (parsers.spnl * parsers.dash^-1 * parsers.at))^0)

      local citation_body_postnote
                    = Cs((parsers.alphanumeric^1
                         + parsers.bracketed
                         + parsers.inticks
                         + (parsers.anyescaped
                           - (parsers.rbracket + parsers.semicolon
                             + parsers.blankline^2))
                         - (parsers.spnl * parsers.rbracket))^0)

      local citation_body_chunk
                    = citation_body_prenote
                    * parsers.spnl * citation_name
                    * (parsers.internal_punctuation - parsers.semicolon)^-1
                    * parsers.spnl * citation_body_postnote

      local citation_body
                    = citation_body_chunk
                    * (parsers.semicolon * parsers.spnl
                      * citation_body_chunk)^0

      local citation_headless_body_postnote
                    = Cs((parsers.alphanumeric^1
                         + parsers.bracketed
                         + parsers.inticks
                         + (parsers.anyescaped
                           - (parsers.rbracket + parsers.at
                             + parsers.semicolon + parsers.blankline^2))
                         - (parsers.spnl * parsers.rbracket))^0)

      local citation_headless_body
                    = citation_headless_body_postnote
                    * (parsers.sp * parsers.semicolon * parsers.spnl
                      * citation_body_chunk)^0

      local citations
                    = function(text_cites, raw_cites)
          local function normalize(str)
              if str == "" then
                  str = nil
              else
                  str = (citation_nbsps and
                    self.parser_functions.parse_inlines_nbsp or
                    self.parser_functions.parse_inlines)(str)
              end
              return str
          end

          local cites = {}
          for i = 1,#raw_cites,4 do
              cites[#cites+1] = {
                  prenote = normalize(raw_cites[i]),
                  suppress_author = raw_cites[i+1] == "-",
                  name = writer.citation(raw_cites[i+2]),
                  postnote = normalize(raw_cites[i+3]),
              }
          end
          return writer.citations(text_cites, cites)
      end

      local TextCitations
                    = Ct((parsers.spnl
                    * Cc("")
                    * citation_name
                    * ((parsers.spnl
                        * parsers.lbracket
                        * citation_headless_body
                        * parsers.rbracket) + Cc("")))^1)
                    / function(raw_cites)
                        return citations(true, raw_cites)
                      end

      local ParenthesizedCitations
                    = Ct((parsers.spnl
                    * parsers.lbracket
                    * citation_body
                    * parsers.rbracket)^1)
                    / function(raw_cites)
                        return citations(false, raw_cites)
                      end

      local Citations = TextCitations + ParenthesizedCitations

      self.insert_pattern("Inline after Emph",
                          Citations, "Citations")

      self.add_special_character("@")
      self.add_special_character("-")
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Content Blocks
%
% The \luamdef{extensions.content_blocks} function implements the iA\,Writer
% content blocks syntax extension. The `language_map` parameter specifies
% the filename of the \acro{JSON} file that maps filename extensions to
% programming language names.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.content_blocks = function(language_map)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \luamdef{languages_json} table maps programming language filename
% extensions to fence infostrings. All `language_map` files located by the
% \pkg{kpathsea} library are loaded into a chain of tables.
% \luamref{languages_json} corresponds to the first table and is chained with
% the rest via Lua metatables.
%
% \end{markdown}
%  \begin{macrocode}
  local languages_json = (function()
    local base, prev, curr
    for _, pathname in ipairs{util.lookup_files(language_map, { all=true })} do
      local file = io.open(pathname, "r")
      if not file then goto continue end
      local input = assert(file:read("*a"))
      assert(file:close())
      local json = input:gsub('("[^\n]-"):','[%1]=')
      curr = load("_ENV = {}; return "..json)()
      if type(curr) == "table" then
        if base == nil then
          base = curr
        else
          setmetatable(prev, { __index = curr })
        end
        prev = curr
      end
      ::continue::
    end
    return base or {}
  end)()

  return {
    name = "built-in content_blocks syntax extension",
    extend_writer = function(self)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->contentblock} as a function that will transform an
% input iA\,Writer content block to the output format, where `src`
% corresponds to the \acro{uri} prefix, `suf` to the \acro{uri} extension,
% `type` to the type of the content block (`localfile` or `onlineimage`),
% and `tit` to the title of the content block.
%
% \end{markdown}
%  \begin{macrocode}
      function self.contentblock(src,suf,type,tit)
        if not self.is_writing then return "" end
        src = src.."."..suf
        suf = suf:lower()
        if type == "onlineimage" then
          return {"\\markdownRendererContentBlockOnlineImage{",suf,"}",
                                 "{",self.string(src),"}",
                                 "{",self.uri(src),"}",
                                 "{",self.string(tit or ""),"}"}
        elseif languages_json[suf] then
          return {"\\markdownRendererContentBlockCode{",suf,"}",
                                 "{",self.string(languages_json[suf]),"}",
                                 "{",self.string(src),"}",
                                 "{",self.uri(src),"}",
                                 "{",self.string(tit or ""),"}"}
        else
          return {"\\markdownRendererContentBlock{",suf,"}",
                                 "{",self.string(src),"}",
                                 "{",self.uri(src),"}",
                                 "{",self.string(tit or ""),"}"}
        end
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer

      local contentblock_tail
                    = parsers.optionaltitle
                    * (parsers.newline + parsers.eof)

      -- case insensitive online image suffix:
      local onlineimagesuffix
                    = (function(...)
                        local parser = nil
                        for _, suffix in ipairs({...}) do
                          local pattern=nil
                          for i=1,#suffix do
                            local char=suffix:sub(i,i)
                            char = S(char:lower()..char:upper())
                            if pattern == nil then
                              pattern = char
                            else
                              pattern = pattern * char
                            end
                          end
                          if parser == nil then
                            parser = pattern
                          else
                            parser = parser + pattern
                          end
                        end
                        return parser
                      end)("png", "jpg", "jpeg", "gif", "tif", "tiff")

      -- online image url for iA Writer content blocks with mandatory suffix,
      -- allowing nested brackets:
      local onlineimageurl
                    = (parsers.less
                      * Cs((parsers.anyescaped
                           - parsers.more
                           - #(parsers.period
                              * onlineimagesuffix
                              * parsers.more
                              * contentblock_tail))^0)
                      * parsers.period
                      * Cs(onlineimagesuffix)
                      * parsers.more
                      + (Cs((parsers.inparens
                            + (parsers.anyescaped
                              - parsers.spacing
                              - parsers.rparent
                              - #(parsers.period
                                 * onlineimagesuffix
                                 * contentblock_tail)))^0)
                        * parsers.period
                        * Cs(onlineimagesuffix))
                      ) * Cc("onlineimage")

      -- filename for iA Writer content blocks with mandatory suffix:
      local localfilepath
                    = parsers.slash
                    * Cs((parsers.anyescaped
                         - parsers.tab
                         - parsers.newline
                         - #(parsers.period
                            * parsers.alphanumeric^1
                            * contentblock_tail))^1)
                    * parsers.period
                    * Cs(parsers.alphanumeric^1)
                    * Cc("localfile")

      local ContentBlock
                    = parsers.leader
                    * (localfilepath + onlineimageurl)
                    * contentblock_tail
                    / writer.contentblock

      self.insert_pattern("Block before Blockquote",
                          ContentBlock, "ContentBlock")
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Definition Lists
%
% The \luamdef{extensions.definition_lists} function implements the Pandoc
% definition list syntax extension. If the `tight_lists` parameter is `true`,
% tight lists will produce special right item renderers.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.definition_lists = function(tight_lists)
  return {
    name = "built-in definition_lists syntax extension",
    extend_writer = function(self)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->definitionlist} as a function that will transform an
% input definition list to the output format, where `items` is an array of
% tables, each of the form `{ term = t, definitions = defs }`, where `t`
% is a term and `defs` is an array of definitions. `tight` specifies,
% whether the list is tight or not.
%
% \end{markdown}
%  \begin{macrocode}
      local function dlitem(term, defs)
        local retVal = {"\\markdownRendererDlItem{",term,"}"}
        for _, def in ipairs(defs) do
          retVal[#retVal+1] = {"\\markdownRendererDlDefinitionBegin ",def,
                               "\\markdownRendererDlDefinitionEnd "}
        end
        retVal[#retVal+1] = "\\markdownRendererDlItemEnd "
        return retVal
      end

      function self.definitionlist(items,tight)
        if not self.is_writing then return "" end
        local buffer = {}
        for _,item in ipairs(items) do
          buffer[#buffer + 1] = dlitem(item.term, item.definitions)
        end
        if tight and tight_lists then
          return {"\\markdownRendererDlBeginTight\n", buffer,
            "\n\\markdownRendererDlEndTight"}
        else
          return {"\\markdownRendererDlBegin\n", buffer,
            "\n\\markdownRendererDlEnd"}
        end
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer

      local defstartchar = S("~:")

      local defstart = ( defstartchar * #parsers.spacing
                                      * (parsers.tab + parsers.space^-3)
                       + parsers.space * defstartchar * #parsers.spacing
                                       * (parsers.tab + parsers.space^-2)
                       + parsers.space * parsers.space * defstartchar
                                       * #parsers.spacing
                                       * (parsers.tab + parsers.space^-1)
                       + parsers.space * parsers.space * parsers.space
                                       * defstartchar * #parsers.spacing
                       )

      local dlchunk = Cs(parsers.line * (parsers.indentedline - parsers.blankline)^0)

      local function definition_list_item(term, defs, _)
        return { term = self.parser_functions.parse_inlines(term),
                 definitions = defs }
      end

      local DefinitionListItemLoose
                    = C(parsers.line) * parsers.skipblanklines
                    * Ct((defstart
                         * parsers.indented_blocks(dlchunk)
                         / self.parser_functions.parse_blocks_nested)^1)
                    * Cc(false) / definition_list_item

      local DefinitionListItemTight
                    = C(parsers.line)
                    * Ct((defstart * dlchunk
                         / self.parser_functions.parse_blocks_nested)^1)
                    * Cc(true) / definition_list_item

      local DefinitionList
                    = ( Ct(DefinitionListItemLoose^1) * Cc(false)
                      + Ct(DefinitionListItemTight^1)
                      * (parsers.skipblanklines
                        * -DefinitionListItemLoose * Cc(true))
                      ) / writer.definitionlist

      self.insert_pattern("Block after Heading",
                          DefinitionList, "DefinitionList")
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Fancy Lists
%
% The \luamdef{extensions.fancy_lists} function implements the Pandoc fancy
% list syntax extension.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.fancy_lists = function()
  return {
    name = "built-in fancy_lists syntax extension",
    extend_writer = function(self)
      local options = self.options

%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->fancylist} as a function that will transform an
% input ordered list to the output format, where:
%
%- `items` is an array of the list items,
%- `tight` specifies, whether the list is tight or not,
%- `startnum` is the number of the first list item,
%- `numstyle` is the style of the list item labels from among the following:
%    - `Decimal` -- decimal arabic numbers,
%    - `LowerRoman` -- lower roman numbers,
%    - `UpperRoman` -- upper roman numbers,
%    - `LowerAlpha` -- lower ASCII alphabetic characters, and
%    - `UpperAlpha` -- upper ASCII alphabetic characters, and
%- `numdelim` is the style of delimiters between list item labels and
%  texts from among the following:
%    - `Default` -- default style,
%    - `OneParen` -- parentheses, and
%    - `Period` -- periods.
%
% \end{markdown}
%  \begin{macrocode}
      function self.fancylist(items,tight,startnum,numstyle,numdelim)
        if not self.is_writing then return "" end
        local buffer = {}
        local num = startnum
        for _,item in ipairs(items) do
          buffer[#buffer + 1] = self.fancyitem(item,num)
          if num ~= nil then
            num = num + 1
          end
        end
        local contents = util.intersperse(buffer,"\n")
        if tight and options.tightLists then
          return {"\\markdownRendererFancyOlBeginTight{",
                  numstyle,"}{",numdelim,"}",contents,
                  "\n\\markdownRendererFancyOlEndTight "}
        else
          return {"\\markdownRendererFancyOlBegin{",
                  numstyle,"}{",numdelim,"}",contents,
                  "\n\\markdownRendererFancyOlEnd "}
        end
      end
%    \end{macrocode}
% \begin{markdown}
%
% Define \luamdef{writer->fancyitem} as a function that will transform an
% input fancy ordered list item to the output format, where `s` is the text of
% the list item. If the optional parameter `num` is present, it is the number
% of the list item.
%
% \end{markdown}
%  \begin{macrocode}
      function self.fancyitem(s,num)
        if num ~= nil then
          return {"\\markdownRendererFancyOlItemWithNumber{",num,"}",s,
                  "\\markdownRendererFancyOlItemEnd "}
        else
          return {"\\markdownRendererFancyOlItem ",s,"\\markdownRendererFancyOlItemEnd "}
        end
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local options = self.options
      local writer = self.writer

      local label = parsers.dig + parsers.letter
      local numdelim = parsers.period + parsers.rparent
      local enumerator = C(label^3 * numdelim) * #parsers.spacing
                       + C(label^2 * numdelim) * #parsers.spacing
                                         * (parsers.tab + parsers.space^1)
                       + C(label * numdelim) * #parsers.spacing
                                       * (parsers.tab + parsers.space^-2)
                       + parsers.space * C(label^2 * numdelim)
                                       * #parsers.spacing
                       + parsers.space * C(label * numdelim)
                                       * #parsers.spacing
                                       * (parsers.tab + parsers.space^-1)
                       + parsers.space * parsers.space * C(label^1
                                       * numdelim) * #parsers.spacing
      local starter = parsers.bullet + enumerator

      local NestedList = Cs((parsers.optionallyindentedline
                            - starter)^1)
                       / function(a) return "\001"..a end

      local ListBlockLine  = parsers.optionallyindentedline
                           - parsers.blankline - (parsers.indent^-1
                                                 * starter)

      local ListBlock = parsers.line * ListBlockLine^0

      local ListContinuationBlock = parsers.blanklines * (parsers.indent / "")
                                  * ListBlock

      local TightListItem = function(starter)
          return -parsers.ThematicBreak
                 * (Cs(starter / "" * parsers.tickbox^-1 * ListBlock * NestedList^-1)
                   / self.parser_functions.parse_blocks_nested)
                 * -(parsers.blanklines * parsers.indent)
      end

      local LooseListItem = function(starter)
          return -parsers.ThematicBreak
                 * Cs( starter / "" * parsers.tickbox^-1 * ListBlock * Cc("\n")
                   * (NestedList + ListContinuationBlock^0)
                   * (parsers.blanklines / "\n\n")
                   ) / self.parser_functions.parse_blocks_nested
      end

      local function roman2number(roman)
        local romans = { ["L"] = 50, ["X"] = 10, ["V"] = 5, ["I"] = 1 }
        local numeral = 0

        local i = 1
        local len = string.len(roman)
        while i < len do
          local z1, z2 = romans[ string.sub(roman, i, i) ], romans[ string.sub(roman, i+1, i+1) ]
          if z1 < z2 then
              numeral = numeral + (z2 - z1)
              i = i + 2
          else
              numeral = numeral + z1
              i = i + 1
          end
        end
        if i <= len then numeral = numeral + romans[ string.sub(roman,i,i) ] end
        return numeral
      end

      local function sniffstyle(itemprefix)
        local numstr, delimend = itemprefix:match("^([A-Za-z0-9]*)([.)]*)")
        local numdelim
        if delimend == ")" then
          numdelim = "OneParen"
        elseif delimend == "." then
          numdelim = "Period"
        else
          numdelim = "Default"
        end
        numstr = numstr or itemprefix

        local num
        num = numstr:match("^([IVXL]+)")
        if num then
          return roman2number(num), "UpperRoman", numdelim
        end
        num = numstr:match("^([ivxl]+)")
        if num then
          return roman2number(string.upper(num)), "LowerRoman", numdelim
        end
        num = numstr:match("^([A-Z])")
        if num then
          return string.byte(num) - string.byte("A") + 1, "UpperAlpha", numdelim
        end
        num = numstr:match("^([a-z])")
        if num then
          return string.byte(num) - string.byte("a") + 1, "LowerAlpha", numdelim
        end
        return math.floor(tonumber(numstr) or 1), "Decimal", numdelim
      end

      local function fancylist(items,tight,start)
        local startnum, numstyle, numdelim = sniffstyle(start)
        return writer.fancylist(items,tight,
                                options.startNumber and startnum,
                                numstyle or "Decimal",
                                numdelim or "Default")
      end

      local FancyList = Cg(enumerator, "listtype") *
                      ( Ct(TightListItem(Cb("listtype"))
                          * TightListItem(enumerator)^0)
                      * Cc(true) * parsers.skipblanklines * -enumerator
                      + Ct(LooseListItem(Cb("listtype"))
                          * LooseListItem(enumerator)^0)
                      * Cc(false) * parsers.skipblanklines
                      ) * Cb("listtype") / fancylist

      self.update_rule("OrderedList", function() return FancyList end)
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Fenced Code
%
% The \luamdef{extensions.fenced_code} function implements the commonmark
% fenced code block syntax extension. When the `blank_before_code_fence`
% parameter is `true`, the syntax extension requires a blank line between a
% paragraph and the following fenced code block.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.fenced_code = function(blank_before_code_fence)
  return {
    name = "built-in fenced_code syntax extension",
    extend_writer = function(self)
      local options = self.options

%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->fencedCode} as a function that will transform an
% input fenced code block `s` with the infostring `i` to the output
% format.
%
% \end{markdown}
%  \begin{macrocode}
      function self.fencedCode(s, i)
        if not self.is_writing then return "" end
        local name = util.cache_verbatim(options.cacheDir, s)
        return {"\\markdownRendererInputFencedCode{",
                name,"}{",self.string(i),"}"}
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer

      local FencedCode = (parsers.TildeFencedCode
                         + parsers.BacktickFencedCode)
                       / function(infostring, code)
                           local expanded_code = self.expandtabs(code)
                           return writer.fencedCode(expanded_code,
                                                    infostring)
                         end

      self.insert_pattern("Block after Verbatim",
                          FencedCode, "FencedCode")

      local fencestart
      if blank_before_code_fence then
        fencestart = parsers.fail
      else
        fencestart = parsers.fencehead(parsers.backtick,
                                       parsers.backtick_infostring)
                   + parsers.fencehead(parsers.tilde,
                                       parsers.tilde_infostring)
      end

      self.update_rule("EndlineExceptions", function(previous_pattern)
        if previous_pattern == nil then
          previous_pattern = parsers.EndlineExceptions
        end
        return previous_pattern + fencestart
      end)

      self.add_special_character("~")
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Fenced Divs
%
% The \luamdef{extensions.fenced_divs} function implements the Pandoc fenced
% divs syntax extension. When the `blank_before_div_fence` parameter is `true`,
% the syntax extension requires a blank line between a paragraph and the
% following fenced code block.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.fenced_divs = function(blank_before_div_fence)
  return {
    name = "built-in fenced_divs syntax extension",
    extend_writer = function(self)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->div} as a function that will transform an input
% fenced div with content `c` and with attributes `attr` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
      function self.div(c, attr)
        return {"\\markdownRendererFencedDivAttributeContextBegin",
                self.attributes(attr),
                c,
                "\\markdownRendererFencedDivAttributeContextEnd"}
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define basic patterns for matching the opening and the closing tag of a div.
%
% \end{markdown}
%  \begin{macrocode}
      local fenced_div_infostring
                             = C((parsers.linechar
                                - ( parsers.spacechar^1
                                  * parsers.colon^1))^1)

      local fenced_div_begin = parsers.nonindentspace
                             * parsers.colon^3
                             * parsers.optionalspace
                             * fenced_div_infostring
                             * ( parsers.spacechar^1
                               * parsers.colon^1)^0
                             * parsers.optionalspace
                             * (parsers.newline + parsers.eof)

      local fenced_div_end = parsers.nonindentspace
                           * parsers.colon^3
                           * parsers.optionalspace
                           * (parsers.newline + parsers.eof)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Initialize a named group named `div_level` for tracking how deep we are
% nested in divs.
%
% \end{markdown}
%  \begin{macrocode}
      self.initialize_named_group("div_level", "0")

      local function increment_div_level(increment)
        local function update_div_level(s, i, current_level) -- luacheck: ignore s i
          current_level = tonumber(current_level)
          local next_level = tostring(current_level + increment)
          return true, next_level
        end

        return Cg( Cmt(Cb("div_level"), update_div_level)
                 , "div_level")
      end

      local FencedDiv = fenced_div_begin * increment_div_level(1)
                      * parsers.skipblanklines
                      * Ct( (V("Block") - fenced_div_end)^-1
                          * ( parsers.blanklines
                            / function()
                                return writer.interblocksep
                              end
                            * (V("Block") - fenced_div_end))^0)
                      * parsers.skipblanklines
                      * fenced_div_end * increment_div_level(-1)
                      / function (infostring, div)
                          local attr = lpeg.match(Ct(parsers.attributes), infostring)
                          if attr == nil then
                            attr = {"." .. infostring}
                          end
                          return div, attr
                        end
                      / writer.div

      self.insert_pattern("Block after Verbatim",
                          FencedDiv, "FencedDiv")

      self.add_special_character(":")
%    \end{macrocode}
% \par
% \begin{markdown}
%
% If the `blank_before_div_fence` parameter is `false`, we will have the
% closing div at the beginning of a line break the current paragraph if
% we are currently nested in a div.
%
% \end{markdown}
%  \begin{macrocode}
      if not blank_before_div_fence then
        local function check_div_level(s, i, current_level) -- luacheck: ignore s i
          current_level = tonumber(current_level)
          return current_level > 0
        end

        local is_inside_div = Cmt(Cb("div_level"), check_div_level)
        local fencestart = is_inside_div * fenced_div_end
        self.update_rule("EndlineExceptions", function(previous_pattern)
          if previous_pattern == nil then
            previous_pattern = parsers.EndlineExceptions
          end
          return previous_pattern + fencestart
        end)
      end
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Header Attributes
%
% The \luamdef{extensions.header_attributes} function implements the Pandoc
% header attributes syntax extension.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.header_attributes = function()
  return {
    name = "built-in header_attributes syntax extension",
    extend_writer = function()
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer

      local AtxHeading = Cg(parsers.heading_start, "level")
                       * parsers.optionalspace
                       * (C(((parsers.linechar
                             - ((parsers.hash^1
                                * parsers.optionalspace
                                * parsers.attributes^-1
                                + parsers.attributes)
                               * parsers.optionalspace
                               * parsers.newline))
                            * (parsers.linechar
                              - parsers.hash
                              - parsers.lbrace)^0)^1)
                           / self.parser_functions.parse_inlines)
                       * Cg(Ct(parsers.newline
                              + (parsers.hash^1
                                * parsers.optionalspace
                                * parsers.attributes^-1
                                + parsers.attributes)
                              * parsers.optionalspace
                              * parsers.newline), "attributes")
                       * Cb("level")
                       * Cb("attributes")
                       / writer.heading

      local SetextHeading = #(parsers.line * S("=-"))
                          * (C(((parsers.linechar
                                - (parsers.attributes
                                  * parsers.optionalspace
                                  * parsers.newline))
                               * (parsers.linechar
                                 - parsers.lbrace)^0)^1)
                              / self.parser_functions.parse_inlines)
                          * Cg(Ct(parsers.newline
                                 + (parsers.attributes
                                   * parsers.optionalspace
                                   * parsers.newline)), "attributes")
                          * parsers.heading_level
                          * Cb("attributes")
                          * parsers.optionalspace
                          * parsers.newline
                          / writer.heading

      local Heading = AtxHeading + SetextHeading
      self.update_rule("Heading", function() return Heading end)
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Notes
%
% The \luamdef{extensions.notes} function implements the Pandoc note
% and inline note syntax extensions. When the `note` parameter is
% `true`, the Pandoc note syntax extension will be enabled.  When the
% `inline_notes` parameter is `true`, the Pandoc inline note syntax
% extension will be enabled.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.notes = function(notes, inline_notes)
  assert(notes or inline_notes)
  return {
    name = "built-in notes syntax extension",
    extend_writer = function(self)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->note} as a function that will transform an
% input note `s` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
      function self.note(s)
        return {"\\markdownRendererNote{",s,"}"}
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer

      if inline_notes then
        local InlineNote
                    = parsers.circumflex
                    * (parsers.tag / self.parser_functions.parse_inlines_no_inline_note)
                    / writer.note

        self.insert_pattern("Inline after Emph",
                            InlineNote, "InlineNote")
      end
      if notes then
        local function strip_first_char(s)
          return s:sub(2)
        end

        local RawNoteRef
                      = #(parsers.lbracket * parsers.circumflex)
                      * parsers.tag / strip_first_char

        local rawnotes = {}

        -- like indirect_link
        local function lookup_note(ref)
          return writer.defer_call(function()
            local found = rawnotes[self.normalize_tag(ref)]
            if found then
              return writer.note(
                self.parser_functions.parse_blocks_nested(found))
            else
              return {"[",
                self.parser_functions.parse_inlines("^" .. ref), "]"}
            end
          end)
        end

        local function register_note(ref,rawnote)
          rawnotes[self.normalize_tag(ref)] = rawnote
          return ""
        end

        local NoteRef = RawNoteRef / lookup_note

        local NoteBlock
                    = parsers.leader * RawNoteRef * parsers.colon
                    * parsers.spnl * parsers.indented_blocks(parsers.chunk)
                    / register_note

        local Blank = NoteBlock + parsers.Blank
        self.update_rule("Blank", function() return Blank end)

        self.insert_pattern("Inline after Emph",
                            NoteRef, "NoteRef")
      end

      self.add_special_character("^")
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Pipe Tables
%
% The \luamdef{extensions.pipe_table} function implements the \acro{PHP}
% Markdown table syntax extension (also known as pipe tables in Pandoc). When
% the `table_captions` parameter is `true`, the function also implements the
% Pandoc `table_captions` syntax extension for table captions.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.pipe_tables = function(table_captions)

  local function make_pipe_table_rectangular(rows)
    local num_columns = #rows[2]
    local rectangular_rows = {}
    for i = 1, #rows do
      local row = rows[i]
      local rectangular_row = {}
      for j = 1, num_columns do
        rectangular_row[j] = row[j] or ""
      end
      table.insert(rectangular_rows, rectangular_row)
    end
    return rectangular_rows
  end

  local function pipe_table_row(allow_empty_first_column
                               , nonempty_column
                               , column_separator
                               , column)
    local row_beginning
    if allow_empty_first_column then
      row_beginning = -- empty first column
                      #(parsers.spacechar^4
                       * column_separator)
                    * parsers.optionalspace
                    * column
                    * parsers.optionalspace
                    -- non-empty first column
                    + parsers.nonindentspace
                    * nonempty_column^-1
                    * parsers.optionalspace
    else
      row_beginning = parsers.nonindentspace
                    * nonempty_column^-1
                    * parsers.optionalspace
    end

    return Ct(row_beginning
             * (-- single column with no leading pipes
                #(column_separator
                 * parsers.optionalspace
                 * parsers.newline)
               * column_separator
               * parsers.optionalspace
               -- single column with leading pipes or
               -- more than a single column
               + (column_separator
                 * parsers.optionalspace
                 * column
                 * parsers.optionalspace)^1
               * (column_separator
                 * parsers.optionalspace)^-1))
  end

  return {
    name = "built-in pipe_tables syntax extension",
    extend_writer = function(self)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->table} as a function that will transform an input
% table to the output format, where `rows` is a sequence of columns and a
% column is a sequence of cell texts.
%
% \end{markdown}
%  \begin{macrocode}
      function self.table(rows, caption)
        if not self.is_writing then return "" end
        local buffer = {"\\markdownRendererTable{",
          caption or "", "}{", #rows - 1, "}{", #rows[1], "}"}
        local temp = rows[2] -- put alignments on the first row
        rows[2] = rows[1]
        rows[1] = temp
        for i, row in ipairs(rows) do
          table.insert(buffer, "{")
          for _, column in ipairs(row) do
            if i > 1 then -- do not use braces for alignments
              table.insert(buffer, "{")
            end
            table.insert(buffer, column)
            if i > 1 then
              table.insert(buffer, "}")
            end
          end
          table.insert(buffer, "}")
        end
        return buffer
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer

      local table_hline_separator = parsers.pipe + parsers.plus

      local table_hline_column = (parsers.dash
                                 - #(parsers.dash
                                    * (parsers.spacechar
                                      + table_hline_separator
                                      + parsers.newline)))^1
                               * (parsers.colon * Cc("r")
                                 + parsers.dash * Cc("d"))
                               + parsers.colon
                               * (parsers.dash
                                 - #(parsers.dash
                                    * (parsers.spacechar
                                      + table_hline_separator
                                      + parsers.newline)))^1
                               * (parsers.colon * Cc("c")
                                 + parsers.dash * Cc("l"))

      local table_hline = pipe_table_row(false
                                        , table_hline_column
                                        , table_hline_separator
                                        , table_hline_column)

      local table_caption_beginning = parsers.skipblanklines
                                    * parsers.nonindentspace
                                    * (P("Table")^-1 * parsers.colon)
                                    * parsers.optionalspace

      local table_row = pipe_table_row(true
                                      , (C((parsers.linechar - parsers.pipe)^1)
                                        / self.parser_functions.parse_inlines)
                                      , parsers.pipe
                                      , (C((parsers.linechar - parsers.pipe)^0)
                                        / self.parser_functions.parse_inlines))

      local table_caption
      if table_captions then
        table_caption = #table_caption_beginning
                      * table_caption_beginning
                      * Ct(parsers.IndentedInline^1)
                      * parsers.newline
      else
        table_caption = parsers.fail
      end

      local PipeTable = Ct(table_row * parsers.newline
                        * table_hline
                        * (parsers.newline * table_row)^0)
                      / make_pipe_table_rectangular
                      * table_caption^-1
                      / writer.table

      self.insert_pattern("Block after Blockquote",
                          PipeTable, "PipeTable")
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Raw Attributes
%
% The \luamdef{extensions.raw_attribute} function implements the Pandoc
% raw attribute syntax extension.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.raw_attribute = function()
  return {
    name = "built-in raw_attribute syntax extension",
    extend_writer = function(self)
      local options = self.options

%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->rawInline} as a function that will transform an
% input inline raw span `s` with the raw attribute `attr` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
      function self.rawInline(s, attr)
        if not self.is_writing then return "" end
        local name = util.cache_verbatim(options.cacheDir, s)
        return {"\\markdownRendererInputRawInline{",
                name,"}{", self.string(attr),"}"}
      end

      if options.fencedCode then
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->rawBlock} as a function that will transform an
% input raw block `s` with the raw attribute `attr` to the output format.
%
% \end{markdown}
%  \begin{macrocode}
        function self.rawBlock(s, attr)
          if not self.is_writing then return "" end
          local name = util.cache_verbatim(options.cacheDir, s)
          return {"\\markdownRendererInputRawBlock{",
                  name,"}{", self.string(attr),"}"}
        end
      end
    end, extend_reader = function(self)
      local options = self.options
      local writer = self.writer

      local raw_attribute = parsers.lbrace
                          * parsers.optionalspace
                          * parsers.equal
                          * C(parsers.attribute_key)
                          * parsers.optionalspace
                          * parsers.rbrace

      local RawInline = parsers.inticks
                      * raw_attribute
                      / writer.rawInline

      self.insert_pattern("Inline before Code",
                          RawInline, "RawInline")

      if options.fencedCode then
        local RawBlock = (parsers.TildeFencedCode
                         + parsers.BacktickFencedCode)
                       / function(infostring, code)
                           local expanded_code = self.expandtabs(code)
                           local attr = lpeg.match(raw_attribute, infostring)
                           if attr then
                             return writer.rawBlock(expanded_code, attr)
                           else
                             return writer.fencedCode(expanded_code,
                                                      infostring)
                           end
                         end

        self.insert_pattern("Block after Verbatim",
                            RawBlock, "RawBlock")
      end
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Strike-Through
%
% The \luamdef{extensions.strike_through} function implements the Pandoc
% strike-through syntax extension.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.strike_through = function()
  return {
    name = "built-in strike_through syntax extension",
    extend_writer = function(self)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->strike_through} as a function that will transform
% a strike-through span `s` of input text to the output format.
%
% \end{markdown}
%  \begin{macrocode}
      function self.strike_through(s)
        return {"\\markdownRendererStrikeThrough{",s,"}"}
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer

      local StrikeThrough = (
        parsers.between(parsers.Inline, parsers.doubletildes,
                        parsers.doubletildes)
      ) / writer.strike_through

      self.insert_pattern("Inline after Emph",
                          StrikeThrough, "StrikeThrough")

      self.add_special_character("~")
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Subscripts
%
% The \luamdef{extensions.subscripts} function implements the Pandoc
% subscript syntax extension.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.subscripts = function()
  return {
    name = "built-in subscripts syntax extension",
    extend_writer = function(self)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->subscript} as a function that will transform
% a subscript span `s` of input text to the output format.
%
% \end{markdown}
%  \begin{macrocode}
      function self.subscript(s)
        return {"\\markdownRendererSubscript{",s,"}"}
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer

      local Subscript = (
        parsers.between(parsers.Str, parsers.tilde, parsers.tilde)
      ) / writer.subscript

      self.insert_pattern("Inline after Emph",
                          Subscript, "Subscript")

      self.add_special_character("~")
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### Superscripts
%
% The \luamdef{extensions.superscripts} function implements the Pandoc
% superscript syntax extension.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.superscripts = function()
  return {
    name = "built-in superscripts syntax extension",
    extend_writer = function(self)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->superscript} as a function that will transform
% a superscript span `s` of input text to the output format.
%
% \end{markdown}
%  \begin{macrocode}
      function self.superscript(s)
        return {"\\markdownRendererSuperscript{",s,"}"}
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer

      local Superscript = (
        parsers.between(parsers.Str, parsers.circumflex, parsers.circumflex)
      ) / writer.superscript

      self.insert_pattern("Inline after Emph",
                          Superscript, "Superscript")

      self.add_special_character("^")
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%#### YAML Metadata
%
% The \luamdef{extensions.jekyll_data} function implements the Pandoc
% `yaml_metadata_block` syntax extension. When the `expect_jekyll_data`
% parameter is `true`, then a markdown document may begin directly with
% \acro{yaml} metadata and may contain nothing but \acro{yaml} metadata.
%
% \end{markdown}
%  \begin{macrocode}
M.extensions.jekyll_data = function(expect_jekyll_data)
  return {
    name = "built-in jekyll_data syntax extension",
    extend_writer = function(self)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Define \luamdef{writer->jekyllData} as a function that will transform an
% input \acro{yaml} table `d` to the output format. The table is the value for
% the key `p` in the parent table; if `p` is nil, then the table has no parent.
% All scalar keys and values encountered in the table will be cast to a string
% following \acro{yaml} serialization rules. String values will also be
% transformed using the function `t`.
%
% \end{markdown}
%  \begin{macrocode}
      function self.jekyllData(d, t, p)
        if not self.is_writing then return "" end

        local buf = {}

        local keys = {}
        for k, _ in pairs(d) do
          table.insert(keys, k)
        end
        table.sort(keys)

        if not p then
          table.insert(buf, "\\markdownRendererJekyllDataBegin")
        end

        if #d > 0 then
            table.insert(buf, "\\markdownRendererJekyllDataSequenceBegin{")
            table.insert(buf, self.uri(p or "null"))
            table.insert(buf, "}{")
            table.insert(buf, #keys)
            table.insert(buf, "}")
        else
            table.insert(buf, "\\markdownRendererJekyllDataMappingBegin{")
            table.insert(buf, self.uri(p or "null"))
            table.insert(buf, "}{")
            table.insert(buf, #keys)
            table.insert(buf, "}")
        end

        for _, k in ipairs(keys) do
          local v = d[k]
          local typ = type(v)
          k = tostring(k or "null")
          if typ == "table" and next(v) ~= nil then
            table.insert(
              buf,
              self.jekyllData(v, t, k)
            )
          else
            k = self.uri(k)
            v = tostring(v)
            if typ == "boolean" then
              table.insert(buf, "\\markdownRendererJekyllDataBoolean{")
              table.insert(buf, k)
              table.insert(buf, "}{")
              table.insert(buf, v)
              table.insert(buf, "}")
            elseif typ == "number" then
              table.insert(buf, "\\markdownRendererJekyllDataNumber{")
              table.insert(buf, k)
              table.insert(buf, "}{")
              table.insert(buf, v)
              table.insert(buf, "}")
            elseif typ == "string" then
              table.insert(buf, "\\markdownRendererJekyllDataString{")
              table.insert(buf, k)
              table.insert(buf, "}{")
              table.insert(buf, t(v))
              table.insert(buf, "}")
            elseif typ == "table" then
              table.insert(buf, "\\markdownRendererJekyllDataEmpty{")
              table.insert(buf, k)
              table.insert(buf, "}")
            else
              error(format("Unexpected type %s for value of " ..
                           "YAML key %s", typ, k))
            end
          end
        end

        if #d > 0 then
          table.insert(buf, "\\markdownRendererJekyllDataSequenceEnd")
        else
          table.insert(buf, "\\markdownRendererJekyllDataMappingEnd")
        end

        if not p then
          table.insert(buf, "\\markdownRendererJekyllDataEnd")
        end

        return buf
      end
    end, extend_reader = function(self)
      local parsers = self.parsers
      local writer = self.writer

      local JekyllData
                    = Cmt( C((parsers.line - P("---") - P("..."))^0)
                         , function(s, i, text) -- luacheck: ignore s i
                             local data
                             local ran_ok, _ = pcall(function()
                               local tinyyaml = require("markdown-tinyyaml")
                               data = tinyyaml.parse(text, {timestamps=false})
                             end)
                             if ran_ok and data ~= nil then
                               return true, writer.jekyllData(data, function(s)
                                 return self.parser_functions.parse_blocks_nested(s)
                               end, nil)
                             else
                               return false
                             end
                           end
                         )

      local UnexpectedJekyllData
                    = P("---")
                    * parsers.blankline / 0
                    * #(-parsers.blankline)  -- if followed by blank, it's thematic break
                    * JekyllData
                    * (P("---") + P("..."))

      local ExpectedJekyllData
                    = ( P("---")
                      * parsers.blankline / 0
                      * #(-parsers.blankline)  -- if followed by blank, it's thematic break
                      )^-1
                    * JekyllData
                    * (P("---") + P("..."))^-1

      self.insert_pattern("Block before Blockquote",
                          UnexpectedJekyllData, "UnexpectedJekyllData")
      if expect_jekyll_data then
        self.update_rule("ExpectedJekyllData", function() return ExpectedJekyllData end)
      end
    end
  }
end
%    \end{macrocode}
% \begin{markdown}
%
%### Conversion from Markdown to Plain \TeX{}
%
% The \luamref{new} function returns a conversion function that takes a
% markdown string and turns it into a plain \TeX{} output. See Section
% <#sec:luaconversion>.
%
% \end{markdown}
%  \begin{macrocode}
function M.new(options)
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Make the `options` table inherit from the \luamref{defaultOptions} table.
%
% \end{markdown}
%  \begin{macrocode}
  options = options or {}
  setmetatable(options, { __index = function (_, key)
    return defaultOptions[key] end })
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Apply built-in syntax extensions based on `options`.
%
% \end{markdown}
%  \begin{macrocode}
  local extensions = {}

  if options.bracketedSpans then
    local bracketed_spans_extension = M.extensions.bracketed_spans()
    table.insert(extensions, bracketed_spans_extension)
  end

  if options.contentBlocks then
    local content_blocks_extension = M.extensions.content_blocks(
      options.contentBlocksLanguageMap)
    table.insert(extensions, content_blocks_extension)
  end

  if options.definitionLists then
    local definition_lists_extension = M.extensions.definition_lists(
      options.tightLists)
    table.insert(extensions, definition_lists_extension)
  end

  if options.fencedCode then
    local fenced_code_extension = M.extensions.fenced_code(
      options.blankBeforeCodeFence)
    table.insert(extensions, fenced_code_extension)
  end

  if options.fencedDivs then
    local fenced_div_extension = M.extensions.fenced_divs(
      options.blankBeforeDivFence)
    table.insert(extensions, fenced_div_extension)
  end

  if options.headerAttributes then
    local header_attributes_extension = M.extensions.header_attributes()
    table.insert(extensions, header_attributes_extension)
  end

  if options.jekyllData then
    local jekyll_data_extension = M.extensions.jekyll_data(
      options.expectJekyllData)
    table.insert(extensions, jekyll_data_extension)
  end

  if options.pipeTables then
    local pipe_tables_extension = M.extensions.pipe_tables(
      options.tableCaptions)
    table.insert(extensions, pipe_tables_extension)
  end

  if options.rawAttribute then
    local raw_attribute_extension = M.extensions.raw_attribute()
    table.insert(extensions, raw_attribute_extension)
  end

  if options.strikeThrough then
    local strike_through_extension = M.extensions.strike_through()
    table.insert(extensions, strike_through_extension)
  end

  if options.subscripts then
    local subscript_extension = M.extensions.subscripts()
    table.insert(extensions, subscript_extension)
  end

  if options.superscripts then
    local superscript_extension = M.extensions.superscripts()
    table.insert(extensions, superscript_extension)
  end

%    \end{macrocode}
% \begin{markdown}
%
% The footnotes and inlineFootnotes option has been deprecated and will be
% removed in Markdown 3.0.0.
%
% \end{markdown}
%  \begin{macrocode}
  if options.footnotes or options.inlineFootnotes or
     options.notes or options.inlineNotes then
    local notes_extension = M.extensions.notes(
      options.footnotes or options.notes,
      options.inlineFootnotes or options.inlineNotes)
    table.insert(extensions, notes_extension)
  end

  if options.citations then
    local citations_extension = M.extensions.citations(options.citationNbsps)
    table.insert(extensions, citations_extension)
  end

  if options.fancyLists then
    local fancy_lists_extension = M.extensions.fancy_lists()
    table.insert(extensions, fancy_lists_extension)
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Apply user-defined syntax extensions based on `options.extensions`.
%
% \end{markdown}
%  \begin{macrocode}
  for _, user_extension_filename in ipairs(options.extensions) do
    local user_extension = (function(filename)
%    \end{macrocode}
% \begin{markdown}
%
% First, load and compile the contents of the user-defined syntax extension.
%
% \end{markdown}
%  \begin{macrocode}
      local pathname = util.lookup_files(filename)
      local input_file = assert(io.open(pathname, "r"),
        [[Could not open user-defined syntax extension "]]
        .. pathname .. [[" for reading]])
      local input = assert(input_file:read("*a"))
      assert(input_file:close())
      local user_extension, err = load([[
        local sandbox = {}
        setmetatable(sandbox, {__index = _G})
        _ENV = sandbox
      ]] .. input)()
      assert(user_extension,
        [[Failed to compile user-defined syntax extension "]]
        .. pathname .. [[": ]] .. (err or [[]]))
%    \end{macrocode}
% \begin{markdown}
%
% Then, validate the user-defined syntax extension.
%
% \end{markdown}
%  \begin{macrocode}
      assert(user_extension.api_version ~= nil,
        [[User-defined syntax extension "]] .. pathname
        .. [[" does not specify mandatory field "api_version"]])
      assert(type(user_extension.api_version) == "number",
        [[User-defined syntax extension "]] .. pathname
        .. [[" specifies field "api_version" of type "]]
        .. type(user_extension.api_version)
        .. [[" but "number" was expected]])
      assert(user_extension.api_version > 0
         and user_extension.api_version <= metadata.user_extension_api_version,
        [[User-defined syntax extension "]] .. pathname
        .. [[" uses syntax extension API version "]]
        .. user_extension.api_version .. [[ but markdown.lua ]]
        .. metadata.version .. [[ uses API version ]]
        .. metadata.user_extension_api_version
        .. [[, which is incompatible]])

      assert(user_extension.grammar_version ~= nil,
        [[User-defined syntax extension "]] .. pathname
        .. [[" does not specify mandatory field "grammar_version"]])
      assert(type(user_extension.grammar_version) == "number",
        [[User-defined syntax extension "]] .. pathname
        .. [[" specifies field "grammar_version" of type "]]
        .. type(user_extension.grammar_version)
        .. [[" but "number" was expected]])
      assert(user_extension.grammar_version == metadata.grammar_version,
        [[User-defined syntax extension "]] .. pathname
        .. [[" uses grammar version "]] .. user_extension.grammar_version
        .. [[ but markdown.lua ]] .. metadata.version
        .. [[ uses grammar version ]] .. metadata.grammar_version
        .. [[, which is incompatible]])

      assert(user_extension.finalize_grammar ~= nil,
        [[User-defined syntax extension "]] .. pathname
        .. [[" does not specify mandatory "finalize_grammar" field]])
      assert(type(user_extension.finalize_grammar) == "function",
        [[User-defined syntax extension "]] .. pathname
        .. [[" specifies field "finalize_grammar" of type "]]
        .. type(user_extension.finalize_grammar)
        .. [[" but "function" was expected]])
%    \end{macrocode}
% \begin{markdown}
%
% Finally, cast the user-defined syntax extension to the internal format
% of user extensions used by the Markdown package (see Section
% <#sec:luabuiltinextensions>.)
%
% \end{markdown}
%  \begin{macrocode}
      local extension = {
        name = [[user-defined "]] .. pathname .. [[" syntax extension]],
        extend_reader = user_extension.finalize_grammar,
        extend_writer = function() end,
      }
      return extension
    end)(user_extension_filename)
    table.insert(extensions, user_extension)
  end
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Produce and return a conversion function from markdown to plain \TeX.
%
% \end{markdown}
%  \begin{macrocode}
  local writer = M.writer.new(options)
  local reader = M.reader.new(writer, options)
  local convert = reader.finalize_grammar(extensions)

  return convert
end

return M
%    \end{macrocode}
% \iffalse
%</lua>
%<*lua-cli>
% \fi
% \par
% \begin{markdown}
%
%### Command-Line Implementation {#lua-cli-implementation}
%
% The command-line implementation provides the actual conversion routine for
% the command-line interface described in Section <#sec:lua-cli-interface>.
%
% \end{markdown}
%  \begin{macrocode}

local input
if input_filename then
  local input_file = assert(io.open(input_filename, "r"),
    [[Could not open file "]] .. input_filename .. [[" for reading]])
  input = assert(input_file:read("*a"))
  assert(input_file:close())
else
  input = assert(io.read("*a"))
end

%    \end{macrocode}
% \begin{markdown}
% First, ensure that the `options.cacheDir` directory exists.
% \end{markdown}
%  \begin{macrocode}
local lfs = require("lfs")
if options.cacheDir and not lfs.isdir(options.cacheDir) then
  assert(lfs.mkdir(options["cacheDir"]))
end

local ran_ok, kpse = pcall(require, "kpse")
if ran_ok then kpse.set_program_name("luatex") end
local md = require("markdown")
%    \end{macrocode}
% \begin{markdown}
% Since we are loading the rest of the Lua implementation dynamically,
% check that both the `markdown` module and the command line implementation
% are the same version.
% \end{markdown}
%  \begin{macrocode}
if metadata.version ~= md.metadata.version then
  warn("markdown-cli.lua " .. metadata.version .. " used with " ..
       "markdown.lua " .. md.metadata.version .. ".")
end
local convert = md.new(options)
%    \end{macrocode}
% \begin{markdown}
% Since the Lua converter expects \acro{unix} line endings, normalize the
% input. Also add a line ending at the end of the file in case the input file
% has none.
% \end{markdown}
%  \begin{macrocode}
local output = convert(input:gsub("\r\n?", "\n") .. "\n")

if output_filename then
  local output_file = assert(io.open(output_filename, "w"),
    [[Could not open file "]] .. output_filename .. [[" for writing]])
  assert(output_file:write(output))
  assert(output_file:close())
else
  assert(io.write(output))
end
%    \end{macrocode}
% \iffalse
%</lua-cli>
%<*tex>
% \fi
% \par
% \begin{markdown}
%
% Plain \TeX{} Implementation {#teximplementation}
%-----------------------------
%
% The plain \TeX{} implementation provides macros for the interfacing between
% \TeX{} and Lua and for the buffering of input text. These macros are then
% used to implement the macros for the conversion from markdown to plain \TeX{}
% exposed by the plain \TeX{} interface (see Section <#sec:texinterface>).
%
%### Logging Facilities {#texinterfacelogging}
%
% \end{markdown}
%  \begin{macrocode}
\ifx\markdownInfo\undefined
  \def\markdownInfo#1{%
    \immediate\write-1{(l.\the\inputlineno) markdown.tex info: #1.}}%
\fi
\ifx\markdownWarning\undefined
  \def\markdownWarning#1{%
    \immediate\write16{(l.\the\inputlineno) markdown.tex warning: #1}}%
\fi
\ifx\markdownError\undefined
  \def\markdownError#1#2{%
    \errhelp{#2.}%
    \errmessage{(l.\the\inputlineno) markdown.tex error: #1}}%
\fi
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Token Renderer Prototypes {#textokenrendererprototypes}
%
% The following definitions should be considered placeholder.
%
% \end{markdown}
%  \begin{macrocode}
\def\markdownRendererInterblockSeparatorPrototype{\par}%
\def\markdownRendererLineBreakPrototype{\hfil\break}%
\let\markdownRendererEllipsisPrototype\dots
\def\markdownRendererNbspPrototype{~}%
\def\markdownRendererLeftBracePrototype{\char`\{}%
\def\markdownRendererRightBracePrototype{\char`\}}%
\def\markdownRendererDollarSignPrototype{\char`$}%
\def\markdownRendererPercentSignPrototype{\char`\%}%
\def\markdownRendererAmpersandPrototype{\&}%
\def\markdownRendererUnderscorePrototype{\char`_}%
\def\markdownRendererHashPrototype{\char`\#}%
\def\markdownRendererCircumflexPrototype{\char`^}%
\def\markdownRendererBackslashPrototype{\char`\\}%
\def\markdownRendererTildePrototype{\char`~}%
\def\markdownRendererPipePrototype{|}%
\def\markdownRendererCodeSpanPrototype#1{{\tt#1}}%
\def\markdownRendererLinkPrototype#1#2#3#4{#2}%
\def\markdownRendererContentBlockPrototype#1#2#3#4{%
  \markdownInput{#3}}%
\def\markdownRendererContentBlockOnlineImagePrototype{%
  \markdownRendererImage}%
\def\markdownRendererContentBlockCodePrototype#1#2#3#4#5{%
  \markdownRendererInputFencedCode{#3}{#2}}%
\def\markdownRendererImagePrototype#1#2#3#4{#2}%
\def\markdownRendererUlBeginPrototype{}%
\def\markdownRendererUlBeginTightPrototype{}%
\def\markdownRendererUlItemPrototype{}%
\def\markdownRendererUlItemEndPrototype{}%
\def\markdownRendererUlEndPrototype{}%
\def\markdownRendererUlEndTightPrototype{}%
\def\markdownRendererOlBeginPrototype{}%
\def\markdownRendererOlBeginTightPrototype{}%
\def\markdownRendererFancyOlBeginPrototype#1#2{\markdownRendererOlBegin}%
\def\markdownRendererFancyOlBeginTightPrototype#1#2{\markdownRendererOlBeginTight}%
\def\markdownRendererOlItemPrototype{}%
\def\markdownRendererOlItemWithNumberPrototype#1{}%
\def\markdownRendererOlItemEndPrototype{}%
\def\markdownRendererFancyOlItemPrototype{\markdownRendererOlItem}%
\def\markdownRendererFancyOlItemWithNumberPrototype{\markdownRendererOlItemWithNumber}%
\def\markdownRendererFancyOlItemEndPrototype{}%
\def\markdownRendererOlEndPrototype{}%
\def\markdownRendererOlEndTightPrototype{}%
\def\markdownRendererFancyOlEndPrototype{\markdownRendererOlEnd}%
\def\markdownRendererFancyOlEndTightPrototype{\markdownRendererOlEndTight}%
\def\markdownRendererDlBeginPrototype{}%
\def\markdownRendererDlBeginTightPrototype{}%
\def\markdownRendererDlItemPrototype#1{#1}%
\def\markdownRendererDlItemEndPrototype{}%
\def\markdownRendererDlDefinitionBeginPrototype{}%
\def\markdownRendererDlDefinitionEndPrototype{\par}%
\def\markdownRendererDlEndPrototype{}%
\def\markdownRendererDlEndTightPrototype{}%
\def\markdownRendererEmphasisPrototype#1{{\it#1}}%
\def\markdownRendererStrongEmphasisPrototype#1{{\bf#1}}%
\def\markdownRendererBlockQuoteBeginPrototype{\par\begingroup\it}%
\def\markdownRendererBlockQuoteEndPrototype{\endgroup\par}%
\def\markdownRendererInputVerbatimPrototype#1{%
  \par{\tt\input#1\relax{}}\par}%
\def\markdownRendererInputFencedCodePrototype#1#2{%
  \markdownRendererInputVerbatimPrototype{#1}}%
\def\markdownRendererHeadingOnePrototype#1{#1}%
\def\markdownRendererHeadingTwoPrototype#1{#1}%
\def\markdownRendererHeadingThreePrototype#1{#1}%
\def\markdownRendererHeadingFourPrototype#1{#1}%
\def\markdownRendererHeadingFivePrototype#1{#1}%
\def\markdownRendererHeadingSixPrototype#1{#1}%
\def\markdownRendererThematicBreakPrototype{}%
\def\markdownRendererNotePrototype#1{#1}%
\def\markdownRendererCitePrototype#1{}%
\def\markdownRendererTextCitePrototype#1{}%
\def\markdownRendererTickedBoxPrototype{[X]}%
\def\markdownRendererHalfTickedBoxPrototype{[/]}%
\def\markdownRendererUntickedBoxPrototype{[ ]}%
\def\markdownRendererStrikeThroughPrototype#1{#1}%
\def\markdownRendererSuperscriptPrototype#1{#1}%
\def\markdownRendererSubscriptPrototype#1{#1}%
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Raw Attribute Renderer Prototypes
%
% In the raw block and inline raw span renderer prototypes, execute the content
% with TeX when the raw attribute is `tex`, display the content as markdown when
% the raw attribute is `md`, and ignore the content otherwise.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_gset:Npn
  \markdownRendererInputRawInlinePrototype#1#2
  {
    \str_case:nn
      { #2 }
      {
        { tex } { \markdownEscape{#1} }
        { md  } { \markdownInput{#1}  }
      }
  }
\cs_gset_eq:NN
  \markdownRendererInputRawBlockPrototype
  \markdownRendererInputRawInlinePrototype
\ExplSyntaxOff
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### YAML Metadata Renderer Prototypes {#expl3yamlmetadataimplementation}
%
% To keep track of the current type of structure we inhabit when we are
% traversing a \acro{yaml} document, we will maintain the
% \mdef{g_\@\@_jekyll_data_datatypes_seq} stack. At every step of the traversal,
% the stack will contain one of the following constants at any position $p$:
%
% \mdef{c_\@\@_jekyll_data_sequence_tl}
%
%:    The currently traversed branch of the \acro{yaml} document contains a sequence
%     at depth $p$.
%
% \mdef{c_\@\@_jekyll_data_mapping_tl}
%
%:    The currently traversed branch of the \acro{yaml} document contains a mapping
%     at depth $p$.
%
% \mdef{c_\@\@_jekyll_data_scalar_tl}
%
%:    The currently traversed branch of the \acro{yaml} document contains a scalar
%     value at depth $p$.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\seq_new:N   \g_@@_jekyll_data_datatypes_seq
\tl_const:Nn \c_@@_jekyll_data_sequence_tl   { sequence }
\tl_const:Nn \c_@@_jekyll_data_mapping_tl    { mapping  }
\tl_const:Nn \c_@@_jekyll_data_scalar_tl     { scalar   }
%    \end{macrocode}
% \par
% \begin{markdown}
%
% To keep track of our current place when we are traversing a \acro{yaml}
% document, we will maintain the
% \mdef{g_\@\@_jekyll_data_wildcard_absolute_address_seq} stack of keys using
% the \mdef{markdown_jekyll_data_push_address_segment:n} macro.
%
% \end{markdown}
%  \begin{macrocode}
\seq_new:N \g_@@_jekyll_data_wildcard_absolute_address_seq
\cs_new:Nn \markdown_jekyll_data_push_address_segment:n
  {
    \seq_if_empty:NF
      \g_@@_jekyll_data_datatypes_seq
      {
        \seq_get_right:NN
          \g_@@_jekyll_data_datatypes_seq
          \l_tmpa_tl
%    \end{macrocode}
% \begin{markdown}
%
% If we are currently in a sequence, we will put an asterisk (`*`) instead of
% a key into \mref{g_\@\@_jekyll_data_wildcard_absolute_address_seq} to make
% it represent a *wildcard*. Keeping a wildcard instead of a precise address
% makes it easy for the users to react to *any* item of a sequence regardless
% of how many there are, which can often be useful.
%
% \end{markdown}
%  \begin{macrocode}
      \str_if_eq:NNTF
        \l_tmpa_tl
        \c_@@_jekyll_data_sequence_tl
        {
          \seq_put_right:Nn
            \g_@@_jekyll_data_wildcard_absolute_address_seq
            { *  }
        }
        {
          \seq_put_right:Nn
            \g_@@_jekyll_data_wildcard_absolute_address_seq
            { #1 }
        }
      }
  }
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Out of \mref{g_\@\@_jekyll_data_wildcard_absolute_address_seq}, we will
% construct the following two token lists:
%
% \mdef{g_\@\@_jekyll_data_wildcard_absolute_address_tl}
%
%:    An *absolute wildcard*: The wildcard from the root of the document
%     prefixed with a slash (`/`) with individual keys and asterisks also
%     delimited by slashes. Allows the users to react to complex
%     context-sensitive structures with ease.
%
%:    For example, the `name` key in the following \acro{yaml} document
%     would correspond to the `/*/person/name` absolute wildcard:
%     ``` yaml
%     [{person: {name: Elon, surname: Musk}}]
%     ```
%
% \mdef{g_\@\@_jekyll_data_wildcard_relative_address_tl}
%
%:    A *relative wildcard*: The rightmost segment of the wildcard. Allows the
%     users to react to simple context-free structures.
%
%:    For example, the `name` key in the following \acro{yaml} document
%     would correspond to the `name` relative wildcard:
%     ``` yaml
%     [{person: {name: Elon, surname: Musk}}]
%     ```
%
% We will construct \mref{g_\@\@_jekyll_data_wildcard_absolute_address_tl}
% using the \mdef{markdown_jekyll_data_concatenate_address:NN} macro and
% we will construct both token lists using the
% \mdef{markdown_jekyll_data_update_address_tls:} macro.
%
% \end{markdown}
%  \begin{macrocode}
\tl_new:N  \g_@@_jekyll_data_wildcard_absolute_address_tl
\tl_new:N  \g_@@_jekyll_data_wildcard_relative_address_tl
\cs_new:Nn \markdown_jekyll_data_concatenate_address:NN
  {
    \seq_pop_left:NN #1 \l_tmpa_tl
    \tl_set:Nx #2 { / \seq_use:Nn #1 { / } }
    \seq_put_left:NV #1 \l_tmpa_tl
  }
\cs_new:Nn \markdown_jekyll_data_update_address_tls:
  {
    \markdown_jekyll_data_concatenate_address:NN
      \g_@@_jekyll_data_wildcard_absolute_address_seq
      \g_@@_jekyll_data_wildcard_absolute_address_tl
    \seq_get_right:NN
      \g_@@_jekyll_data_wildcard_absolute_address_seq
      \g_@@_jekyll_data_wildcard_relative_address_tl
  }
%    \end{macrocode}
% \par
% \begin{markdown}
%
% To make sure that the stacks and token lists stay in sync, we will use the
% \mdef{markdown_jekyll_data_push:nN} and \mdef{markdown_jekyll_data_pop:}
% macros.
%
% \end{markdown}
%  \begin{macrocode}
\cs_new:Nn \markdown_jekyll_data_push:nN
  {
    \markdown_jekyll_data_push_address_segment:n
      { #1 }
    \seq_put_right:NV
     \g_@@_jekyll_data_datatypes_seq
     #2
    \markdown_jekyll_data_update_address_tls:
  }
\cs_new:Nn \markdown_jekyll_data_pop:
  {
    \seq_pop_right:NN
      \g_@@_jekyll_data_wildcard_absolute_address_seq
      \l_tmpa_tl
    \seq_pop_right:NN
      \g_@@_jekyll_data_datatypes_seq
      \l_tmpa_tl
    \markdown_jekyll_data_update_address_tls:
  }
%    \end{macrocode}
% \par
% \begin{markdown}
%
% To set a single key--value, we will use the
% \mdef{markdown_jekyll_data_set_keyval:Nn} macro, ignoring unknown keys.
% To set key--values for both absolute and relative wildcards, we will use the
% \mdef{markdown_jekyll_data_set_keyvals:nn} macro.
%
% \end{markdown}
%  \begin{macrocode}
\cs_new:Nn \markdown_jekyll_data_set_keyval:nn
  {
    \keys_set_known:nn
      { markdown/jekyllData }
      { { #1 } = { #2 } }
  }
\cs_generate_variant:Nn
  \markdown_jekyll_data_set_keyval:nn
  { Vn }
\cs_new:Nn \markdown_jekyll_data_set_keyvals:nn
  {
    \markdown_jekyll_data_push:nN
      { #1 }
      \c_@@_jekyll_data_scalar_tl
    \markdown_jekyll_data_set_keyval:Vn
      \g_@@_jekyll_data_wildcard_absolute_address_tl
      { #2 }
    \markdown_jekyll_data_set_keyval:Vn
      \g_@@_jekyll_data_wildcard_relative_address_tl
      { #2 }
    \markdown_jekyll_data_pop:
  }
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Finally, we will register our macros as token renderer prototypes
% to be able to react to the traversal of a \acro{yaml} document.
%
% \end{markdown}
%  \begin{macrocode}
\def\markdownRendererJekyllDataSequenceBeginPrototype#1#2{
  \markdown_jekyll_data_push:nN
    { #1 }
    \c_@@_jekyll_data_sequence_tl
}
\def\markdownRendererJekyllDataMappingBeginPrototype#1#2{
  \markdown_jekyll_data_push:nN
    { #1 }
    \c_@@_jekyll_data_mapping_tl
}
\def\markdownRendererJekyllDataSequenceEndPrototype{
  \markdown_jekyll_data_pop:
}
\def\markdownRendererJekyllDataMappingEndPrototype{
  \markdown_jekyll_data_pop:
}
\def\markdownRendererJekyllDataBooleanPrototype#1#2{
  \markdown_jekyll_data_set_keyvals:nn
    { #1 }
    { #2 }
}
\def\markdownRendererJekyllDataEmptyPrototype#1{}
\def\markdownRendererJekyllDataNumberPrototype#1#2{
  \markdown_jekyll_data_set_keyvals:nn
    { #1 }
    { #2 }
}
\def\markdownRendererJekyllDataStringPrototype#1#2{
  \markdown_jekyll_data_set_keyvals:nn
    { #1 }
    { #2 }
}
\ExplSyntaxOff
%    \end{macrocode}
% \begin{markdown}
%
%### Lua Snippets
% After the \mdef{markdownPrepareLuaOptions} macro has been fully expanded,
% the \mdef{markdownLuaOptions} macro will expands to a Lua table that
% contains the plain \TeX{} options (see Section <#sec:texoptions>) in a
% format recognized by Lua (see Section <#sec:luaoptions>).
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\tl_new:N \g_@@_formatted_lua_options_tl
\cs_new:Nn \@@_format_lua_options:
  {
    \tl_gclear:N
      \g_@@_formatted_lua_options_tl
    \seq_map_function:NN
      \g_@@_lua_options_seq
      \@@_format_lua_option:n
  }
\cs_new:Nn \@@_format_lua_option:n
  {
    \@@_typecheck_option:n
      { #1 }
    \@@_get_option_type:nN
      { #1 }
      \l_tmpa_tl
    \bool_case_true:nF
      {
        {
          \str_if_eq_p:VV
            \l_tmpa_tl
            \c_@@_option_type_boolean_tl ||
          \str_if_eq_p:VV
            \l_tmpa_tl
            \c_@@_option_type_number_tl ||
          \str_if_eq_p:VV
            \l_tmpa_tl
            \c_@@_option_type_counter_tl
        }
          {
            \@@_get_option_value:nN
              { #1 }
              \l_tmpa_tl
            \tl_gput_right:Nx
              \g_@@_formatted_lua_options_tl
              { #1~=~  \l_tmpa_tl   ,~ }
          }
        {
          \str_if_eq_p:VV
            \l_tmpa_tl
            \c_@@_option_type_clist_tl
        }
          {
            \@@_get_option_value:nN
              { #1 }
              \l_tmpa_tl
            \tl_gput_right:Nx
              \g_@@_formatted_lua_options_tl
              { #1~=~\c_left_brace_str }
            \clist_map_inline:Vn
              \l_tmpa_tl
              {
                \tl_gput_right:Nx
                  \g_@@_formatted_lua_options_tl
                  { "##1" ,~ }
              }
            \tl_gput_right:Nx
              \g_@@_formatted_lua_options_tl
              { \c_right_brace_str ,~ }
          }
      }
      {
        \@@_get_option_value:nN
          { #1 }
          \l_tmpa_tl
        \tl_gput_right:Nx
          \g_@@_formatted_lua_options_tl
          { #1~=~ " \l_tmpa_tl " ,~ }
      }
  }
\cs_generate_variant:Nn
  \clist_map_inline:nn
  { Vn }
\let\markdownPrepareLuaOptions=\@@_format_lua_options:
\def\markdownLuaOptions{{ \g_@@_formatted_lua_options_tl }}
\ExplSyntaxOff
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \mdef{markdownPrepare} macro contains the Lua code that is executed prior
% to any conversion from markdown to plain \TeX{}. It exposes the
% `convert` function for the use by any further Lua code.
%
% \end{markdown}
%  \begin{macrocode}
\def\markdownPrepare{%
%    \end{macrocode}
% \begin{markdown}
% First, ensure that the \Opt{cacheDir} directory exists.
% \end{markdown}
%  \begin{macrocode}
  local lfs = require("lfs")
  local cacheDir = "\markdownOptionCacheDir"
  if not lfs.isdir(cacheDir) then
    assert(lfs.mkdir(cacheDir))
  end
%    \end{macrocode}
% \begin{markdown}
% Next, load the `markdown` module and create a converter function using
% the plain \TeX{} options, which were serialized to a Lua table via the
% \mref{markdownLuaOptions} macro.
% \end{markdown}
%  \begin{macrocode}
  local md = require("markdown")
  local convert = md.new(\markdownLuaOptions)
}%
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Buffering Markdown Input {#buffering}
%
% The
% \mdef{markdownIfOption}`{`\meta{name}`}{`\meta{iftrue}`}{`\meta{iffalse}`}`
% macro is provided for testing, whether the value of
% `\markdownOption`\meta{name} is `true`. If the value is `true`, then
% \meta{iftrue} is expanded, otherwise \meta{iffalse} is expanded.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_new:Nn
  \@@_if_option:nTF
  {
    \@@_get_option_type:nN
      { #1 }
      \l_tmpa_tl
    \str_if_eq:NNF
      \l_tmpa_tl
      \c_@@_option_type_boolean_tl
      {
        \msg_error:nnxx
          { @@ }
          { expected-boolean-option }
          { #1 }
          { \l_tmpa_tl }
      }
    \@@_get_option_value:nN
      { #1 }
      \l_tmpa_tl
    \str_if_eq:NNTF
      \l_tmpa_tl
      \c_@@_option_value_true_tl
      { #2 }
      { #3 }
  }
\msg_new:nnn
  { @@ }
  { expected-boolean-option }
  {
    Option~#1~has~type~#2,~
    but~a~boolean~was~expected.
  }
\let\markdownIfOption=\@@_if_option:nTF
\ExplSyntaxOff
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The macros \mdef{markdownInputFileStream} and \mdef{markdownOutputFileStream}
% contain the number of the input and output file streams that will be used for
% the IO operations of the package.
%
% \end{markdown}
%  \begin{macrocode}
\csname newread\endcsname\markdownInputFileStream
\csname newwrite\endcsname\markdownOutputFileStream
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \mdef{markdownReadAndConvertTab} macro contains the tab character literal.
%
% \end{markdown}
%  \begin{macrocode}
\begingroup
  \catcode`\^^I=12%
  \gdef\markdownReadAndConvertTab{^^I}%
\endgroup
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \mref{markdownReadAndConvert} macro is largely a rewrite of the
% \Hologo{LaTeX2e} `\filecontents` macro to plain \TeX{}.
%
% \end{markdown}
%  \begin{macrocode}
\begingroup
%    \end{macrocode}
% \begin{markdown}
% Make the newline and tab characters active and swap the character codes of
% the backslash symbol (`\`) and the pipe symbol (`|`), so that we can use the
% backslash as an ordinary character inside the macro definition.  Likewise,
% swap the character codes of the percent sign (`\%`) and the ampersand (`@`),
% so that we can remove percent signs from the beginning of lines when
% \Opt{stripPercentSigns} is enabled.
% \end{markdown}
%  \begin{macrocode}
  \catcode`\^^M=13%
  \catcode`\^^I=13%
  \catcode`|=0%
  \catcode`\\=12%
  |catcode`@=14%
  |catcode`|%=12@
  |gdef|markdownReadAndConvert#1#2{@
    |begingroup@
%    \end{macrocode}
% \begin{markdown}
% If we are not reading markdown documents from the frozen cache,
% open the \Opt{inputTempFileName} file for writing.
% \end{markdown}
%  \begin{macrocode}
    |markdownIfOption{frozenCache}{}{@
      |immediate|openout|markdownOutputFileStream@
        |markdownOptionInputTempFileName|relax@
      |markdownInfo{Buffering markdown input into the temporary @
        input file "|markdownOptionInputTempFileName" and scanning @
        for the closing token sequence "#1"}@
    }@
%    \end{macrocode}
% \begin{markdown}
% Locally change the category of the special plain \TeX{} characters to
% *other* in order to prevent unwanted interpretation of the input.  Change
% also the category of the space character, so that we can retrieve it
% unaltered.
% \end{markdown}
%  \begin{macrocode}
    |def|do##1{|catcode`##1=12}|dospecials@
    |catcode`| =12@
    |markdownMakeOther@
%    \end{macrocode}
% \begin{markdown}
% The \mdef{markdownReadAndConvertStripPercentSigns} macro will process the
% individual lines of output, stipping away leading percent signs (`\%`) when
% \Opt{stripPercentSigns} is enabled.
% Notice the use of the comments (`@`) to ensure that the entire macro is at
% a single line and therefore no (active) newline symbols
% (`^^M`) are produced.
% \end{markdown}
%  \begin{macrocode}
    |def|markdownReadAndConvertStripPercentSign##1{@
      |markdownIfOption{stripPercentSigns}{@
        |if##1%@
          |expandafter|expandafter|expandafter@
            |markdownReadAndConvertProcessLine@
        |else@
          |expandafter|expandafter|expandafter@
            |markdownReadAndConvertProcessLine@
            |expandafter|expandafter|expandafter##1@
        |fi@
      }{@
        |expandafter@
          |markdownReadAndConvertProcessLine@
          |expandafter##1@
      }@
    }@
%    \end{macrocode}
% \begin{markdown}
% The \mdef{markdownReadAndConvertProcessLine} macro will process the individual
% lines of output.
% Notice the use of the comments (`@`) to ensure that the entire macro is at
% a single line and therefore no (active) newline symbols
% (`^^M`) are produced.
% \end{markdown}
%  \begin{macrocode}
    |def|markdownReadAndConvertProcessLine##1#1##2#1##3|relax{@
%    \end{macrocode}
% \begin{markdown}
% If we are not reading markdown documents from the frozen cache and the ending
% token sequence does not appear in the line, store the line in the
% \Opt{inputTempFileName} file.
% If we are reading markdown documents from the frozen cache and the
% ending token sequence does not appear in the line, gobble the line.
% \end{markdown}
%  \begin{macrocode}
      |ifx|relax##3|relax@
        |markdownIfOption{frozenCache}{}{@
          |immediate|write|markdownOutputFileStream{##1}@
        }@
      |else@
%    \end{macrocode}
% \begin{markdown}
% When the ending token sequence appears in the line, make the next newline
% character close the \Opt{inputTempFileName} file, return the
% character categories back to the former state, convert the
% \Opt{inputTempFileName} file from markdown to plain \TeX{},
% `\input` the result of the conversion, and expand the ending control
% sequence.
% \end{markdown}
%  \begin{macrocode}
        |def^^M{@
          |markdownInfo{The ending token sequence was found}@
          |markdownIfOption{frozenCache}{}{@
            |immediate|closeout|markdownOutputFileStream@
          }@
          |endgroup@
          |markdownInput{@
            |markdownOptionOutputDir@
            /|markdownOptionInputTempFileName@
          }@
          #2}@
      |fi@
%    \end{macrocode}
% \begin{markdown}
% Repeat with the next line.
% \end{markdown}
%  \begin{macrocode}
      ^^M}@
%    \end{macrocode}
% \begin{markdown}
% Make the tab character active at expansion time and make it expand to a
% literal tab character.
% \end{markdown}
%  \begin{macrocode}
    |catcode`|^^I=13@
    |def^^I{|markdownReadAndConvertTab}@
%    \end{macrocode}
% \begin{markdown}
% Make the newline character active at expansion time and make it consume the
% rest of the line on expansion. Throw away the rest of the first line and
% pass the second line to the \mref{markdownReadAndConvertProcessLine} macro.
% \end{markdown}
%  \begin{macrocode}
    |catcode`|^^M=13@
    |def^^M##1^^M{@
      |def^^M####1^^M{@
        |markdownReadAndConvertStripPercentSign####1#1#1|relax}@
      ^^M}@
    ^^M}@
%    \end{macrocode}
% \begin{markdown}
% Reset the character categories back to the former state.
% \end{markdown}
%  \begin{macrocode}
|endgroup
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The following two sections of the implementation have been deprecated and
% will be removed in Markdown 3.0.0. The code that corresponds to
% \mref{markdownMode} value of `3` will be the only implementation.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\int_compare:nT
  { \markdownMode = 3 }
  {
    \markdownInfo{Using~mode~3:~The~lt3luabridge~package}
    \file_input:n { lt3luabridge.tex }
    \cs_new:Npn
      \markdownLuaExecute
      { \luabridgeExecute }
  }
\ExplSyntaxOff
%    \end{macrocode}
% \begin{markdown}
%
%### Lua Shell Escape Bridge {#luabridge}
%
% The following \TeX{} code is intended for \TeX{} engines that do not provide
% direct access to Lua, but expose the shell of the operating system. This
% corresponds to the \mref{markdownMode} values of `0` and `1`.
%
% The \mref{markdownLuaExecute} macro defined here and in Section
% <#sec:directlua> are meant to be indistinguishable to the remaining code.
%
% The package assumes that although the user is not using the Lua\TeX{} engine,
% their \TeX{} distribution contains it, and uses shell access to produce and
% execute Lua scripts using the \TeX{}Lua interpreter~[@luatex21, Section
% 4.1.1].
%
% \end{markdown}
%  \begin{macrocode}
\ifnum\markdownMode<2\relax
\ifnum\markdownMode=0\relax
  \markdownWarning{Using mode 0: Shell escape via write18
                   (deprecated, to be removed in Markdown 3.0.0)}%
\else
  \markdownWarning{Using mode 1: Shell escape via os.execute
                   (deprecated, to be removed in Markdown 3.0.0)}%
\fi
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \mdef{markdownExecuteShellEscape} macro contains the numeric value indicating
% whether the shell access is enabled (`1`), disabled (`0`), or restricted
% (`2`).
%
% Inherit the value of the the `\pdfshellescape` (Lua\TeX{}, \Hologo{pdfTeX})
% or the `\shellescape` (\Hologo{XeTeX}) commands. If neither of these
% commands is defined and Lua is available, attempt to access the
% `status.shell_escape` configuration item.
%
% If you cannot detect, whether the shell access is enabled, act as if it were.
%
% \end{markdown}
%  \begin{macrocode}
\ifx\pdfshellescape\undefined
  \ifx\shellescape\undefined
    \ifnum\markdownMode=0\relax
      \def\markdownExecuteShellEscape{1}%
    \else
      \def\markdownExecuteShellEscape{%
        \directlua{tex.sprint(status.shell_escape or "1")}}%
    \fi
  \else
    \let\markdownExecuteShellEscape\shellescape
  \fi
\else
  \let\markdownExecuteShellEscape\pdfshellescape
\fi
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \mdef{markdownExecuteDirect} macro executes the code it has received as
% its first argument by writing it to the output file stream 18, if Lua is
% unavailable, or by using the Lua `os.execute` method otherwise.
%
% \end{markdown}
%  \begin{macrocode}
\ifnum\markdownMode=0\relax
  \def\markdownExecuteDirect#1{\immediate\write18{#1}}%
\else
  \def\markdownExecuteDirect#1{%
    \directlua{os.execute("\luaescapestring{#1}")}}%
\fi
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \mdef{markdownExecute} macro is a wrapper on top of
% \mref{markdownExecuteDirect} that checks the value of
% \mref{markdownExecuteShellEscape} and prints an error message if the shell is
% inaccessible.
%
% \end{markdown}
%  \begin{macrocode}
\def\markdownExecute#1{%
  \ifnum\markdownExecuteShellEscape=1\relax
    \markdownExecuteDirect{#1}%
  \else
    \markdownError{I can not access the shell}{Either run the TeX
      compiler with the --shell-escape or the --enable-write18 flag,
      or set shell_escape=t in the texmf.cnf file}%
  \fi}%
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \mdef{markdownLuaExecute} macro executes the Lua code it has received as
% its first argument. The Lua code may not directly interact with the \TeX{}
% engine, but it can use the `print` function in the same manner it
% would use the `tex.print` method.
%
% \end{markdown}
%  \begin{macrocode}
\begingroup
%    \end{macrocode}
% \begin{markdown}
% Swap the category code of the backslash symbol and the pipe symbol, so that
% we may use the backslash symbol freely inside the Lua code.
% \end{markdown}
%  \begin{macrocode}
  \catcode`|=0%
  \catcode`\\=12%
  |gdef|markdownLuaExecute#1{%
%    \end{macrocode}
% \begin{markdown}
% Create the file \Opt{helperScriptFileName} and fill it with the
% input Lua code prepended with \pkg{kpathsea} initialization, so that Lua
% modules from the \TeX{} distribution are available.
% \end{markdown}
%  \begin{macrocode}
    |immediate|openout|markdownOutputFileStream=%
      |markdownOptionHelperScriptFileName
    |markdownInfo{Writing a helper Lua script to the file
      "|markdownOptionHelperScriptFileName"}%
    |immediate|write|markdownOutputFileStream{%
      local ran_ok, error = pcall(function()
        local ran_ok, kpse = pcall(require, "kpse")
        if ran_ok then kpse.set_program_name("luatex") end
        #1
      end)
%    \end{macrocode}
% \begin{markdown}
% If there was an error, use the file \Opt{errorTempFileName} to
% store the error message.
% \end{markdown}
%  \begin{macrocode}
      if not ran_ok then
        local file = io.open("%
          |markdownOptionOutputDir
          /|markdownOptionErrorTempFileName", "w")
        if file then
          file:write(error .. "\n")
          file:close()
        end
        print('\\markdownError{An error was encountered while executing
               Lua code}{For further clues, examine the file
               "|markdownOptionOutputDir
               /|markdownOptionErrorTempFileName"}')
      end}%
    |immediate|closeout|markdownOutputFileStream
%    \end{macrocode}
% \begin{markdown}
% Execute the generated \Opt{helperScriptFileName} Lua script using
% the \TeX{}Lua binary and store the output in the
% \Opt{outputTempFileName} file.
% \end{markdown}
%  \begin{macrocode}
    |markdownInfo{Executing a helper Lua script from the file
      "|markdownOptionHelperScriptFileName" and storing the result in the
      file "|markdownOptionOutputTempFileName"}%
    |markdownExecute{texlua "|markdownOptionOutputDir
      /|markdownOptionHelperScriptFileName" > %
      "|markdownOptionOutputDir
      /|markdownOptionOutputTempFileName"}%
%    \end{macrocode}
% \begin{markdown}
% `\input` the generated \Opt{outputTempFileName} file.
% \end{markdown}
%  \begin{macrocode}
    |input|markdownOptionOutputTempFileName|relax}%
|endgroup
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Direct Lua Access {#directlua}
%
% The following \TeX{} code is intended for \TeX{} engines that provide
% direct access to Lua (Lua\TeX{}). The macro \mref{markdownLuaExecute} defined
% here and in Section <#sec:luabridge> are meant to be indistinguishable to
% the remaining code. This corresponds to the \mref{markdownMode} value of `2`.
%
% \end{markdown}
%  \begin{macrocode}
\fi
\ifnum\markdownMode=2\relax
  \markdownWarning{Using mode 2: Direct Lua access
                   (deprecated, to be removed in Markdown 3.0.0)}%
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The direct Lua access version of the \mref{markdownLuaExecute} macro is defined
% in terms of the `\directlua` primitive. The `print` function is set as
% an alias to the `tex.print` method in order to mimic the behaviour of the
% \mref{markdownLuaExecute} definition from Section <#sec:luabridge>,
%
% \end{markdown}
%  \begin{macrocode}
\begingroup
%    \end{macrocode}
% \begin{markdown}
% Swap the category code of the backslash symbol and the pipe symbol, so that
% we may use the backslash symbol freely inside the Lua code.
% \end{markdown}
%  \begin{macrocode}
  \catcode`|=0%
  \catcode`\\=12%
  |gdef|markdownLuaExecute#1{%
    |directlua{%
      local function print(input)
        local output = {}
        for line in input:gmatch("[^\r\n]+") do
          table.insert(output, line)
        end
        tex.print(output)
      end
      #1
    }%
  }%
|endgroup
\fi
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Typesetting Markdown
%
% The \mref{markdownInput} macro uses an implementation of the
% \mref{markdownLuaExecute} macro to convert the contents of the file whose
% filename it has received as its single argument from markdown to plain
% \TeX{}.
%
% \end{markdown}
%  \begin{macrocode}
\begingroup
%    \end{macrocode}
% \begin{markdown}
% Swap the category code of the backslash symbol and the pipe symbol, so that
% we may use the backslash symbol freely inside the Lua code. Furthermore,
% use the ampersand symbol to specify parameters.
% \end{markdown}
%  \begin{macrocode}
  \catcode`|=0%
  \catcode`\\=12%
  \catcode`|&=6%
  |gdef|markdownInput#1{%
%    \end{macrocode}
% \begin{markdown}
% Change the category code of the percent sign (`\%`) to other, so that a user
% of the \Opt{hybrid} Lua option or a malevolent actor can't produce TeX
% comments in the plain TeX output of the Markdown package.
% \end{markdown}
%  \begin{macrocode}
    |begingroup
    |catcode`|%=12
%    \end{macrocode}
% \begin{markdown}
% Furthermore, also change the category code of the hash sign (`#`) to other,
% so that it's safe to tokenize the plain TeX output without mistaking hash
% signs with TeX's parameter numbers.
% \end{markdown}
%  \begin{macrocode}
    |catcode`|#=12
%    \end{macrocode}
% \begin{markdown}
% If we are reading from the frozen cache, input it, expand the corresponding
% `\markdownFrozenCache`\meta{number} macro, and increment
% \Opt{frozenCacheCounter}.
% \end{markdown}
%  \begin{macrocode}
    |markdownIfOption{frozenCache}{%
      |ifnum|markdownOptionFrozenCacheCounter=0|relax
        |markdownInfo{Reading frozen cache from
          "|markdownOptionFrozenCacheFileName"}%
        |input|markdownOptionFrozenCacheFileName|relax
      |fi
      |markdownInfo{Including markdown document number
        "|the|markdownOptionFrozenCacheCounter" from frozen cache}%
      |csname markdownFrozenCache|the|markdownOptionFrozenCacheCounter|endcsname
      |global|advance|markdownOptionFrozenCacheCounter by 1|relax
    }{%
      |markdownInfo{Including markdown document "&1"}%
%    \end{macrocode}
% \begin{markdown}
% Attempt to open the markdown document to record it in the `.log` and
% `.fls` files. This allows external programs such as \LaTeX Mk to track
% changes to the markdown document.
% \end{markdown}
%  \begin{macrocode}
      |openin|markdownInputFileStream&1
      |closein|markdownInputFileStream
      |markdownPrepareLuaOptions
      |markdownLuaExecute{%
        |markdownPrepare
        local file = assert(io.open("&1", "r"),
          [[Could not open file "&1" for reading]])
        local input = assert(file:read("*a"))
        assert(file:close())
%    \end{macrocode}
% \begin{markdown}
% Since the Lua converter expects \acro{unix} line endings, normalize the
% input. Also add a line ending at the end of the file in case the input file
% has none.
% \end{markdown}
%  \begin{macrocode}
        print(convert(input:gsub("\r\n?", "\n") .. "\n"))}%
%    \end{macrocode}
% \begin{markdown}
% In case we were finalizing the frozen cache, increment \Opt{frozenCacheCounter}.
% \end{markdown}
%  \begin{macrocode}
      |global|advance|markdownOptionFrozenCacheCounter by 1|relax
    }%
    |endgroup
  }%
|endgroup
%    \end{macrocode}
% \par
% \begin{markdown}
% The \mref{markdownEscape} macro resets the category codes of the percent sign
% and the hash sign back to comment and parameter, respectively, before using
% the `\input` built-in of \TeX{} to execute a \TeX{} document in the middle of
% a markdown document fragment.
% \end{markdown}
%  \begin{macrocode}
\gdef\markdownEscape#1{%
  \catcode`\%=14\relax
  \catcode`\#=6\relax
  \input #1\relax
  \catcode`\%=12\relax
  \catcode`\#=12\relax
}%
%    \end{macrocode}
% \iffalse
%</tex>
%<*latex>
% \fi
% \par
% \begin{markdown}
%
% \LaTeX{} Implementation {#lateximplementation}
%-------------------------
%
% The \LaTeX{} implemenation makes use of the fact that, apart from some subtle
% differences, \LaTeX{} implements the majority of the plain \TeX{}
% format~[@latex17, Section 9]. As a consequence, we can directly reuse the
% existing plain \TeX{} implementation.
%
% \end{markdown}
%  \begin{macrocode}
\def\markdownVersionSpace{ }%
\ProvidesPackage{markdown}[\markdownLastModified\markdownVersionSpace v%
  \markdownVersion\markdownVersionSpace markdown renderer]%
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Use reflection to define the `renderers` and `rendererPrototypes` keys of
% \mref{markdownSetup} as well as the keys that correspond to Lua options.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\@@_latex_define_renderers:
\@@_latex_define_renderer_prototypes:
\ExplSyntaxOff
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Logging Facilities
% The \LaTeX{} implementation redefines the plain \TeX{} logging macros (see
% Section <#sec:texinterfacelogging>) to use the \LaTeX{} `\PackageInfo`,
% `\PackageWarning`, and `\PackageError` macros.
%
% \end{markdown}
%  \begin{macrocode}
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Typesetting Markdown
% The \mdef{markdownInputPlainTeX} macro is used to store the original plain
% \TeX{} implementation of the \mref{markdownInput} macro. The \mref{markdownInput}
% is then redefined to accept an optional argument with options recognized by
% the \LaTeX{} interface (see Section <#sec:latexoptions>).
%
% \end{markdown}
%  \begin{macrocode}
\let\markdownInputPlainTeX\markdownInput
\renewcommand\markdownInput[2][]{%
  \begingroup
    \markdownSetup{#1}%
    \markdownInputPlainTeX{#2}%
  \endgroup}%
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \envmref{markdown}, and \envmref{markdown*} \LaTeX{} environments are
% implemented using the \mref{markdownReadAndConvert} macro.
%
% \end{markdown}
%  \begin{macrocode}
\renewenvironment{markdown}{%
  \markdownReadAndConvert@markdown{}}{%
  \markdownEnd}%
\renewenvironment{markdown*}[1]{%
  \markdownSetup{#1}%
  \markdownReadAndConvert@markdown*}{%
  \markdownEnd}%
\begingroup
%    \end{macrocode}
% \begin{markdown}
% Locally swap the category code of the backslash symbol with the pipe symbol,
% and of the left (`{`) and right brace (`}`) with the less-than (`<`)
% and greater-than (`>`) signs. This is required in order that all the
% special symbols that appear in the first argument of the
% `markdownReadAndConvert` macro have the category code *other*.
% \end{markdown}
%  \begin{macrocode}
  \catcode`\|=0\catcode`\<=1\catcode`\>=2%
  \catcode`\\=12|catcode`|{=12|catcode`|}=12%
  |gdef|markdownReadAndConvert@markdown#1<%
    |markdownReadAndConvert<\end{markdown#1}>%
                           <|end<markdown#1>>>%
|endgroup
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### \LaTeX{} Themes {#latexthemesimplementation}
%
% This section implements the theme-loading mechanism and the example themes
% provided with the Markdown package.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
%    \end{macrocode}
% \begin{markdown}
%
% To keep track of our current place when packages themes have been nested,
% we will maintain the \mdef{g_\@\@_latex_themes_seq} stack of theme names.
%
% \end{markdown}
%  \begin{macrocode}
\newcommand\markdownLaTeXThemeName{}
\seq_new:N \g_@@_latex_themes_seq
\seq_gput_right:NV
  \g_@@_latex_themes_seq
  \markdownLaTeXThemeName
\newcommand\markdownLaTeXThemeLoad[2]{
  \def\@tempa{%
    \def\markdownLaTeXThemeName{#2}
    \seq_gput_right:NV
      \g_@@_latex_themes_seq
      \markdownLaTeXThemeName
    \RequirePackage{#1}
    \seq_pop_right:NN
      \g_@@_latex_themes_seq
      \l_tmpa_tl
    \seq_get_right:NN
      \g_@@_latex_themes_seq
      \l_tmpa_tl
    \exp_args:NNV
      \def
      \markdownLaTeXThemeName
      \l_tmpa_tl}
  \ifmarkdownLaTeXLoaded
    \@tempa
  \else
    \exp_args:No
      \AtEndOfPackage
      { \@tempa }
  \fi}
\ExplSyntaxOff
%    \end{macrocode}
% \begin{markdown}
%
% The `witiko/dot` theme enables the \Opt{fencedCode} Lua option:
%
% \end{markdown}
% \iffalse
%</latex>
%<*latex-themes-witiko-dot>
% \fi
%  \begin{macrocode}
\markdownSetup{fencedCode}%
%    \end{macrocode}
% \begin{markdown}
%
% We load the \pkg{ifthen} and \pkg{grffile} packages, see also
% Section <#sec:latexprerequisites>:
%
% \end{markdown}
%  \begin{macrocode}
\RequirePackage{ifthen,grffile}
%    \end{macrocode}
% \begin{markdown}
%
% We store the previous definition of the fenced code token renderer prototype:
%
% \end{markdown}
%  \begin{macrocode}
\let\markdown@witiko@dot@oldRendererInputFencedCodePrototype
  \markdownRendererInputFencedCodePrototype
%    \end{macrocode}
% \begin{markdown}
%
% If the infostring starts with `dot …`, we redefine the fenced code block
% token renderer prototype, so that it typesets the code block via Graphviz
% tools if and only if the \Opt{frozenCache} plain \TeX{} option is
% disabled and the code block has not been previously typeset:
%
% \end{markdown}
%  \begin{macrocode}
\renewcommand\markdownRendererInputFencedCode[2]{%
  \def\next##1 ##2\relax{%
    \ifthenelse{\equal{##1}{dot}}{%
      \markdownIfOption{frozenCache}{}{%
        \immediate\write18{%
          if ! test -e #1.pdf.source || ! diff #1 #1.pdf.source;
          then
            dot -Tpdf -o #1.pdf #1;
            cp #1 #1.pdf.source;
          fi}}%
%    \end{macrocode}
% \begin{markdown}
%
% We include the typeset image using the image token renderer:
%
% \end{markdown}
%  \begin{macrocode}
      \markdownRendererImage{Graphviz image}{#1.pdf}{#1.pdf}{##2}%
%    \end{macrocode}
% \begin{markdown}
%
% If the infostring does not start with `dot …`, we use the previous definition
% of the fenced code token renderer prototype:
%
% \end{markdown}
%  \begin{macrocode}
    }{%
      \markdown@witiko@dot@oldRendererInputFencedCodePrototype{#1}{#2}%
    }%
  }%
  \next#2 \relax}%
%    \end{macrocode}
% \iffalse
%</latex-themes-witiko-dot>
%<*latex-themes-witiko-graphicx-http>
% \fi
% \par
% \begin{markdown}
%
% The `witiko/graphicx/http` theme stores the previous definition of the image
% token renderer prototype:
%
% \end{markdown}
%  \begin{macrocode}
\let\markdown@witiko@graphicx@http@oldRendererImagePrototype
  \markdownRendererImagePrototype
%    \end{macrocode}
% \begin{markdown}
%
% We load the \pkg{catchfile} and \pkg{grffile} packages, see also
% Section <#sec:latexprerequisites>:
%
% \end{markdown}
%  \begin{macrocode}
\RequirePackage{catchfile,grffile}
%    \end{macrocode}
% \begin{markdown}
%
% We define the \mdef{markdown@witiko@graphicx@http@counter} counter to enumerate
% the images for caching and the \mdef{markdown@witiko@graphicx@http@filename}
% command, which will store the pathname of the file containing the pathname
% of the downloaded image file.
%
% \end{markdown}
%  \begin{macrocode}
\newcount\markdown@witiko@graphicx@http@counter
\markdown@witiko@graphicx@http@counter=0
\newcommand\markdown@witiko@graphicx@http@filename{%
  \markdownOptionCacheDir/witiko_graphicx_http%
  .\the\markdown@witiko@graphicx@http@counter}%
%    \end{macrocode}
% \begin{markdown}
%
% We define the \mdef{markdown@witiko@graphicx@http@download} command, which will
% receive two arguments that correspond to the URL of the online image and to
% the pathname, where the online image should be downloaded. The command will
% produce a shell command that tries to downloads the online image to the
% pathname.
%
% \end{markdown}
%  \begin{macrocode}
\newcommand\markdown@witiko@graphicx@http@download[2]{%
  wget -O #2 #1 || curl --location -o #2 #1 || rm -f #2}
%    \end{macrocode}
% \begin{markdown}
%
% We locally swap the category code of the percentage sign with the line feed
% control character, so that we can use percentage signs in the shell code:
%
% \end{markdown}
%  \begin{macrocode}
\begingroup
\catcode`\%=12
\catcode`\^^A=14
%    \end{macrocode}
% \begin{markdown}
%
% We redefine the image token renderer prototype, so that it tries to download
% an online image.
%
% \end{markdown}
%  \begin{macrocode}
\global\def\markdownRendererImagePrototype#1#2#3#4{^^A
  \begingroup
    \edef\filename{\markdown@witiko@graphicx@http@filename}^^A
%    \end{macrocode}
% \begin{markdown}
%
% The image will be downloaded only if the image URL has the http or https
% protocols and the \Opt{frozenCache} plain \TeX{} option is disabled:
%
% \end{markdown}
%  \begin{macrocode}
    \markdownIfOption{frozenCache}{}{^^A
      \immediate\write18{^^A
        mkdir -p "\markdownOptionCacheDir";
        if printf '%s' "#3" | grep -q -E '^https?:';
        then
%    \end{macrocode}
% \begin{markdown}
%
% The image will be downloaded to the pathname \Opt{cacheDir}<!--
% -->`/`\meta{the MD5 digest of the image URL}`.`\meta{the suffix of the
% image URL}:
%
% \end{markdown}
%  \begin{macrocode}
          OUTPUT_PREFIX="\markdownOptionCacheDir";
          OUTPUT_BODY="$(printf '%s' '#3' | md5sum | cut -d' ' -f1)";
          OUTPUT_SUFFIX="$(printf '%s' '#3' | sed 's/.*[.]//')";
          OUTPUT="$OUTPUT_PREFIX/$OUTPUT_BODY.$OUTPUT_SUFFIX";
%    \end{macrocode}
% \begin{markdown}
%
% The image will be downloaded only if it has not already been downloaded:
%
% \end{markdown}
%  \begin{macrocode}
          if ! [ -e "$OUTPUT" ];
          then
            \markdown@witiko@graphicx@http@download{'#3'}{"$OUTPUT"};
            printf '%s' "$OUTPUT" > "\filename";
          fi;
%    \end{macrocode}
% \begin{markdown}
%
% If the image does not have the http or https protocols or the image has
% already been downloaded, the URL will be stored as-is:
%
% \end{markdown}
%  \begin{macrocode}
        else
          printf '%s' '#3' > "\filename";
        fi}}^^A
%    \end{macrocode}
% \begin{markdown}
%
% We load the pathname of the downloaded image and we typeset the image using
% the previous definition of the image renderer prototype:
%
% \end{markdown}
%  \begin{macrocode}
    \CatchFileDef{\filename}{\filename}{\endlinechar=-1}^^A
    \markdown@witiko@graphicx@http@oldRendererImagePrototype^^A
      {#1}{#2}{\filename}{#4}^^A
  \endgroup
  \global\advance\markdown@witiko@graphicx@http@counter by 1\relax}^^A
\endgroup
%    \end{macrocode}
% \iffalse
%</latex-themes-witiko-graphicx-http>
%<*latex-themes-witiko-tilde>
% \fi
% \par
% \begin{markdown}
%
% The `witiko/tilde` theme redefines the tilde token renderer prototype,
% so that it expands to a non-breaking space:
%
% \end{markdown}
%  \begin{macrocode}
\renewcommand\markdownRendererTildePrototype{~}%
%    \end{macrocode}
% \iffalse
%</latex-themes-witiko-tilde>
%<*latex>
% \fi
% \par
% \begin{markdown}
%
%### Options
% The supplied package options are processed using the \mref{markdownSetup} macro.
%
% \end{markdown}
%  \begin{macrocode}
\DeclareOption*{%
  \expandafter\markdownSetup\expandafter{\CurrentOption}}%
\ProcessOptions\relax
%    \end{macrocode}
% \begin{markdown}
%
% After processing the options, activate the `jekyllDataRenderes`, `renderers`,
% `rendererPrototypes`, and `code` keys.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\keys_define:nn
  { markdown/latex-options }
  {
    renderers .code:n = {
      \keys_set:nn
        { markdown/latex-options/renderers }
        { #1 }
    },
  }
\@@_with_various_cases:nn
  { rendererPrototypes }
  {
    \keys_define:nn
      { markdown/latex-options }
      {
        #1 .code:n = {
          \keys_set:nn
            { markdown/latex-options/renderer-prototypes }
            { ##1 }
        },
      }
  }
%    \end{macrocode}
% \begin{markdown}
%
% The `code` key is used to immediately expand and execute code, which can be
% especially useful in \LaTeX{} setup snippets.
%
% \end{markdown}
%  \begin{macrocode}
\keys_define:nn
  { markdown/latex-options }
  {
    code .code:n = { #1 },
  }
%    \end{macrocode}
% \begin{markdown}
%
% The `jekyllDataRenderers` key can be used as a syntactic sugar for setting
% the `markdown/jekyllData` key--values (see Section <#sec:expl3yamlmetadata>)
% without using the expl3 language.
%
% \end{markdown}
%  \begin{macrocode}
\@@_with_various_cases:nn
  { jekyllDataRenderers }
  {
    \keys_define:nn
      { markdown/latex-options }
      {
        #1 .code:n = {
          \tl_set:Nn
            \l_tmpa_tl
            { ##1 }
%    \end{macrocode}
% \begin{markdown}
%
% To ensure that keys containing forward slashes get passed correctly, we
% replace all forward slashes in the nput with backslash tokens with category
% code letter and then undo the replacement. This means that if any unbraced
% backslash tokens with category code letter exist in the input, they will be
% replaced with forward slashes. However, this should be extremely rare.
%
% \end{markdown}
%  \begin{macrocode}
          \tl_replace_all:NnV
            \l_tmpa_tl
            { / }
            \c_backslash_str
          \keys_set:nV
            { markdown/latex-options/jekyll-data-renderers }
            \l_tmpa_tl
        },
      }
  }
\keys_define:nn
  { markdown/latex-options/jekyll-data-renderers }
  {
    unknown .code:n = {
      \tl_set_eq:NN
        \l_tmpa_tl
        \l_keys_key_str
      \tl_replace_all:NVn
        \l_tmpa_tl
        \c_backslash_str
        { / }
      \tl_put_right:Nn
        \l_tmpa_tl
        {
          .code:n = { #1 }
        }
      \keys_define:nV
        { markdown/jekyllData }
        \l_tmpa_tl
    }
  }
\cs_generate_variant:Nn
  \keys_define:nn
  { nV }
\cs_generate_variant:Nn
  \tl_replace_all:Nnn
  { NVn }
\cs_generate_variant:Nn
  \tl_replace_all:Nnn
  { NnV }
\ExplSyntaxOff
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Token Renderer Prototypes {#latexdefaultrendererprototypes}
%
% The following configuration should be considered placeholder. If the `plain`
% package option has been enabled (see Section <#sec:latexplain>), none of
% it will take effect.
% \end{markdown}
%  \begin{macrocode}
\markdownIfOption{plain}{\iffalse}{\iftrue}
%    \end{macrocode}
% \par
% \begin{markdown}%
% If the \Opt{tightLists} Lua option is disabled or the current document class
% is \pkg{beamer}, do not load the \pkg{paralist} package.
%
% \end{markdown}
%  \begin{macrocode}
\markdownIfOption{tightLists}{
  \@ifclassloaded{beamer}{}{\RequirePackage{paralist}}%
}{}
%    \end{macrocode}
% \par
% \begin{markdown}
%
% If we loaded the \pkg{paralist} package, define the respective renderer
% prototypes to make use of the capabilities of the package. Otherwise,
% define the renderer prototypes to fall back on the corresponding renderers
% for the non-tight lists.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\@ifpackageloaded{paralist}{
  \tl_new:N
    \l_@@_latex_fancy_list_item_label_number_style_tl
  \tl_new:N
    \l_@@_latex_fancy_list_item_label_delimiter_style_tl
  \cs_new:Nn
    \@@_latex_fancy_list_item_label_number:nn
    {
      \str_case:nn
        { #1 }
        {
          { Decimal } { #2 }
          { LowerRoman } { \int_to_roman:n { #2 } }
          { UpperRoman } { \int_to_Roman:n { #2 } }
          { LowerAlpha } { \int_to_alph:n { #2 } }
          { UpperAlpha } { \int_to_alph:n { #2 } }
        }
    }
  \cs_new:Nn
    \@@_latex_fancy_list_item_label_delimiter:n
    {
      \str_case:nn
        { #1 }
        {
          { Default } { . }
          { OneParen } { ) }
          { Period } { . }
        }
    }
  \cs_new:Nn
    \@@_latex_fancy_list_item_label:nnn
    {
      \@@_latex_fancy_list_item_label_number:nn
        { #1 }
        { #3 }
      \@@_latex_fancy_list_item_label_delimiter:n
        { #2 }
    }
  \cs_new:Nn
    \@@_latex_paralist_style:nn
    {
      \str_case:nn
        { #1 }
        {
          { Decimal } { 1 }
          { LowerRoman } { i }
          { UpperRoman } { I }
          { LowerAlpha } { a }
          { UpperAlpha } { A }
        }
      \@@_latex_fancy_list_item_label_delimiter:n
        { #2 }
    }
  \markdownSetup{rendererPrototypes={
    ulBeginTight = {\begin{compactitem}},
    ulEndTight = {\end{compactitem}},
    fancyOlBegin = {
      \group_begin:
      \tl_set:Nn
        \l_@@_latex_fancy_list_item_label_number_style_tl
        { #1 }
      \tl_set:Nn
        \l_@@_latex_fancy_list_item_label_delimiter_style_tl
        { #2 }
      \tl_set:Nn
        \l_tmpa_tl
        { \begin{enumerate}[ }
      \tl_put_right:Nx
        \l_tmpa_tl
        { \@@_latex_paralist_style:nn { #1 } { #2 } }
      \tl_put_right:Nn
        \l_tmpa_tl
        { ] }
      \l_tmpa_tl
    },
    fancyOlEnd = {
      \end{enumerate}
      \group_end:
    },
    olBeginTight = {\begin{compactenum}},
    olEndTight = {\end{compactenum}},
    fancyOlBeginTight = {
      \group_begin:
      \tl_set:Nn
        \l_@@_latex_fancy_list_item_label_number_style_tl
        { #1 }
      \tl_set:Nn
        \l_@@_latex_fancy_list_item_label_delimiter_style_tl
        { #2 }
      \tl_set:Nn
        \l_tmpa_tl
        { \begin{compactenum}[ }
      \tl_put_right:Nx
        \l_tmpa_tl
        { \@@_latex_paralist_style:nn { #1 } { #2 } }
      \tl_put_right:Nn
        \l_tmpa_tl
        { ] }
      \l_tmpa_tl
    },
    fancyOlEndTight = {
      \end{compactenum}
      \group_end:
    },
    fancyOlItemWithNumber = {
      \item
        [
          \@@_latex_fancy_list_item_label:VVn
            \l_@@_latex_fancy_list_item_label_number_style_tl
            \l_@@_latex_fancy_list_item_label_delimiter_style_tl
            { #1 }
        ]
    },
    dlBeginTight = {\begin{compactdesc}},
    dlEndTight = {\end{compactdesc}}}}
  \cs_generate_variant:Nn
    \@@_latex_fancy_list_item_label:nnn
    { VVn }
}{
  \markdownSetup{rendererPrototypes={
    ulBeginTight = {\markdownRendererUlBegin},
    ulEndTight = {\markdownRendererUlEnd},
    fancyOlBegin = {\markdownRendererOlBegin},
    fancyOlEnd = {\markdownRendererOlEnd},
    olBeginTight = {\markdownRendererOlBegin},
    olEndTight = {\markdownRendererOlEnd},
    fancyOlBeginTight = {\markdownRendererOlBegin},
    fancyOlEndTight = {\markdownRendererOlEnd},
    dlBeginTight = {\markdownRendererDlBegin},
    dlEndTight = {\markdownRendererDlEnd}}}
}
\ExplSyntaxOff
\RequirePackage{amsmath}
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Unless the \pkg{unicode-math} package has been loaded, load the \pkg{amssymb}
% package with symbols to be used for tickboxes.
%
% \end{markdown}
%  \begin{macrocode}
\@ifpackageloaded{unicode-math}{
  \markdownSetup{rendererPrototypes={
    untickedBox = {$\mdlgwhtsquare$},
  }}
}{
  \RequirePackage{amssymb}
  \markdownSetup{rendererPrototypes={
    untickedBox = {$\square$},
  }}
}
\RequirePackage{csvsimple}
\RequirePackage{fancyvrb}
\RequirePackage{graphicx}
\markdownSetup{rendererPrototypes={
  lineBreak = {\\},
  leftBrace = {\textbraceleft},
  rightBrace = {\textbraceright},
  dollarSign = {\textdollar},
  underscore = {\textunderscore},
  circumflex = {\textasciicircum},
  backslash = {\textbackslash},
  tilde = {\textasciitilde},
  pipe = {\textbar},
%    \end{macrocode}
% \par
% \begin{markdown}
%
% We can capitalize on the fact that the expansion of renderers is performed by
% \TeX{} during the typesetting. Therefore, even if we don't know whether a
% span of text is part of math formula or not when we are parsing markdown,%
% ^[This property may actually be undecidable. Suppose a span of text is a part
% of a macro definition.  Then, whether the span of text is part of a math
% formula or not depends on where the macro is later used, which may easily
% be *both* inside and outside a math formula.] we can reliably detect math
% mode inside the renderer.
%
% Here, we will redefine the code span renderer prototype to typeset upright
% text in math formulae and typewriter text outside math formulae.
%
% \end{markdown}
%  \begin{macrocode}
  codeSpan = {%
    \ifmmode
      \text{#1}%
    \else
      \texttt{#1}%
    \fi
  }}}
\ExplSyntaxOn
\markdownSetup{
  rendererPrototypes = {
    contentBlock = {
      \str_case:nnF
        { #1 }
        {
          { csv }
            {
              \begin{table}
                \begin{center}
                  \csvautotabular{#3}
                \end{center}
                \tl_if_empty:nF
                  { #4 }
                  { \caption{#4} }
              \end{table}
            }
          { tex } { \markdownEscape{#3} }
        }
        { \markdownInput{#3} }
    },
  },
}
\ExplSyntaxOff
\markdownSetup{rendererPrototypes={
  image = {%
    \begin{figure}%
      \begin{center}%
        \includegraphics{#3}%
      \end{center}%
      \ifx\empty#4\empty\else
        \caption{#4}%
      \fi
    \end{figure}},
  ulBegin = {\begin{itemize}},
  ulEnd = {\end{itemize}},
  olBegin = {\begin{enumerate}},
  olItem = {\item{}},
  olItemWithNumber = {\item[#1.]},
  olEnd = {\end{enumerate}},
  dlBegin = {\begin{description}},
  dlItem = {\item[#1]},
  dlEnd = {\end{description}},
  emphasis = {\emph{#1}},
  tickedBox = {$\boxtimes$},
  halfTickedBox = {$\boxdot$},
%    \end{macrocode}
% \par
% \begin{markdown}
%
% If identifier attributes appear at the beginning of a section, we make the
% next heading produce the `\label` macro.
%
% \end{markdown}
%  \begin{macrocode}
  headerAttributeContextBegin = {
    \markdownSetup{
      rendererPrototypes = {
        attributeIdentifier = {%
          \begingroup
          \def\next####1{%
            \def####1########1{%
              \endgroup
              ####1{########1}%
              \label{##1}%
            }%
          }%
          \next\markdownRendererHeadingOne
          \next\markdownRendererHeadingTwo
          \next\markdownRendererHeadingThree
          \next\markdownRendererHeadingFour
          \next\markdownRendererHeadingFive
          \next\markdownRendererHeadingSix
        },
      },
    }%
  },
  superscript = {\textsuperscript{#1}},
  subscript = {\textsubscript{#1}},
  blockQuoteBegin = {\begin{quotation}},
  blockQuoteEnd = {\end{quotation}},
  inputVerbatim = {\VerbatimInput{#1}},
  inputFencedCode = {%
    \ifx\relax#2\relax
      \VerbatimInput{#1}%
    \else
      \@ifundefined{minted@code}{%
        \@ifundefined{lst@version}{%
          \markdownRendererInputFencedCode{#1}{}%
%    \end{macrocode}
% \par
% \begin{markdown}
%
% When the \pkg{listings} package is loaded, use it for syntax highlighting.
%
% \end{markdown}
%  \begin{macrocode}
        }{%
          \lstinputlisting[language=#2]{#1}%
        }%
%    \end{macrocode}
% \par
% \begin{markdown}
%
% When the \pkg{minted} package is loaded, use it for syntax highlighting.
% The \pkg{minted} package is preferred over \pkg{listings}.
%
% \end{markdown}
%  \begin{macrocode}
      }{%
        \catcode`\#=6\relax
        \inputminted{#2}{#1}%
        \catcode`\#=12\relax
      }%
    \fi},
  thematicBreak = {\noindent\rule[0.5ex]{\linewidth}{1pt}},
  note = {\footnote{#1}}}}
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Support the nesting of strong emphasis.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\def\markdownLATEXStrongEmphasis#1{%
  \str_if_in:NnTF
    \f@series
    { b }
    { \textnormal{#1} }
    { \textbf{#1} }
}
\ExplSyntaxOff
\markdownSetup{rendererPrototypes={strongEmphasis={%
  \protect\markdownLATEXStrongEmphasis{#1}}}}
%    \end{macrocode}
% \par
% \begin{markdown}
%
% Support \LaTeX{} document classes that do not provide chapters.
%
% \end{markdown}
%  \begin{macrocode}
\@ifundefined{chapter}{%
  \markdownSetup{rendererPrototypes = {
    headingOne = {\section{#1}},
    headingTwo = {\subsection{#1}},
    headingThree = {\subsubsection{#1}},
    headingFour = {\paragraph{#1}\leavevmode},
    headingFive = {\subparagraph{#1}\leavevmode}}}
}{%
  \markdownSetup{rendererPrototypes = {
    headingOne = {\chapter{#1}},
    headingTwo = {\section{#1}},
    headingThree = {\subsection{#1}},
    headingFour = {\subsubsection{#1}},
    headingFive = {\paragraph{#1}\leavevmode},
    headingSix = {\subparagraph{#1}\leavevmode}}}
}%
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Tickboxes
% If the \Opt{taskLists} option is enabled, we will hide bullets in unordered
% list items with tickboxes.
%
% \end{markdown}
%  \begin{macrocode}
\markdownSetup{
  rendererPrototypes = {
    ulItem = {%
      \futurelet\markdownLaTeXCheckbox\markdownLaTeXUlItem
    },
  },
}
\def\markdownLaTeXUlItem{%
  \ifx\markdownLaTeXCheckbox\markdownRendererTickedBox
    \item[\markdownLaTeXCheckbox]%
    \expandafter\@gobble
  \else
    \ifx\markdownLaTeXCheckbox\markdownRendererHalfTickedBox
      \item[\markdownLaTeXCheckbox]%
      \expandafter\expandafter\expandafter\@gobble
    \else
      \ifx\markdownLaTeXCheckbox\markdownRendererUntickedBox
        \item[\markdownLaTeXCheckbox]%
        \expandafter\expandafter\expandafter\expandafter
          \expandafter\expandafter\expandafter\@gobble
      \else
        \item{}%
      \fi
    \fi
  \fi
}
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### HTML elements
% If the \Opt{html} option is enabled and we are using [\TeX{}4ht][1], we will
% pass HTML elements to the output HTML document unchanged.
%
%  [1]: https://tug.org/tex4ht/
%
% \end{markdown}
%  \begin{macrocode}
\@ifundefined{HCode}{}{
  \markdownSetup{
    rendererPrototypes = {
      inlineHtmlTag = {%
        \ifvmode
          \IgnorePar
          \EndP
        \fi
        \HCode{#1}%
      },
      inputBlockHtmlElement = {%
        \ifvmode
          \IgnorePar
        \fi
        \EndP
        \special{t4ht*<#1}%
        \par
        \ShowPar
      },
    },
  }
}
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Citations
% Here is a basic implementation for citations that uses the \LaTeX{} `\cite`
% macro. There are also implementations that use the \pkg{natbib} `\citep`,
% and `\citet` macros, and the Bib\LaTeX{} `\autocites` and `\textcites`
% macros. These implementations will be used, when the respective packages are
% loaded.
%
% \end{markdown}
%  \begin{macrocode}
\newcount\markdownLaTeXCitationsCounter

% Basic implementation
\RequirePackage{gobble}
\def\markdownLaTeXBasicCitations#1#2#3#4#5#6{%
  \advance\markdownLaTeXCitationsCounter by 1\relax
  \ifx\relax#4\relax
    \ifx\relax#5\relax
      \ifnum\markdownLaTeXCitationsCounter>\markdownLaTeXCitationsTotal\relax
        \cite{#1#2#6}%  Without prenotes and postnotes, just accumulate cites
        \expandafter\expandafter\expandafter
        \expandafter\expandafter\expandafter\expandafter
        \@gobblethree
      \fi
    \else%  Before a postnote (#5), dump the accumulator
      \ifx\relax#1\relax\else
        \cite{#1}%
      \fi
      \cite[#5]{#6}%
      \ifnum\markdownLaTeXCitationsCounter>\markdownLaTeXCitationsTotal\relax
      \else
        \expandafter\expandafter\expandafter
        \expandafter\expandafter\expandafter\expandafter
        \expandafter\expandafter\expandafter
        \expandafter\expandafter\expandafter\expandafter
        \markdownLaTeXBasicCitations
      \fi
      \expandafter\expandafter\expandafter
      \expandafter\expandafter\expandafter\expandafter{%
      \expandafter\expandafter\expandafter
      \expandafter\expandafter\expandafter\expandafter}%
      \expandafter\expandafter\expandafter
      \expandafter\expandafter\expandafter\expandafter{%
      \expandafter\expandafter\expandafter
      \expandafter\expandafter\expandafter\expandafter}%
      \expandafter\expandafter\expandafter
      \@gobblethree
    \fi
  \else%  Before a prenote (#4), dump the accumulator
    \ifx\relax#1\relax\else
      \cite{#1}%
    \fi
    \ifnum\markdownLaTeXCitationsCounter>1\relax
      \space  % Insert a space before the prenote in later citations
    \fi
    #4~\expandafter\cite\ifx\relax#5\relax{#6}\else[#5]{#6}\fi
    \ifnum\markdownLaTeXCitationsCounter>\markdownLaTeXCitationsTotal\relax
    \else
      \expandafter\expandafter\expandafter
      \expandafter\expandafter\expandafter\expandafter
      \markdownLaTeXBasicCitations
    \fi
    \expandafter\expandafter\expandafter{%
    \expandafter\expandafter\expandafter}%
    \expandafter\expandafter\expandafter{%
    \expandafter\expandafter\expandafter}%
    \expandafter
    \@gobblethree
  \fi\markdownLaTeXBasicCitations{#1#2#6},}
\let\markdownLaTeXBasicTextCitations\markdownLaTeXBasicCitations

% Natbib implementation
\def\markdownLaTeXNatbibCitations#1#2#3#4#5{%
  \advance\markdownLaTeXCitationsCounter by 1\relax
  \ifx\relax#3\relax
    \ifx\relax#4\relax
      \ifnum\markdownLaTeXCitationsCounter>\markdownLaTeXCitationsTotal\relax
        \citep{#1,#5}%  Without prenotes and postnotes, just accumulate cites
        \expandafter\expandafter\expandafter
        \expandafter\expandafter\expandafter\expandafter
        \@gobbletwo
      \fi
    \else%  Before a postnote (#4), dump the accumulator
      \ifx\relax#1\relax\else
        \citep{#1}%
      \fi
      \citep[][#4]{#5}%
      \ifnum\markdownLaTeXCitationsCounter>\markdownLaTeXCitationsTotal\relax
      \else
        \expandafter\expandafter\expandafter
        \expandafter\expandafter\expandafter\expandafter
        \expandafter\expandafter\expandafter
        \expandafter\expandafter\expandafter\expandafter
        \markdownLaTeXNatbibCitations
      \fi
      \expandafter\expandafter\expandafter
      \expandafter\expandafter\expandafter\expandafter{%
      \expandafter\expandafter\expandafter
      \expandafter\expandafter\expandafter\expandafter}%
      \expandafter\expandafter\expandafter
      \@gobbletwo
    \fi
  \else%  Before a prenote (#3), dump the accumulator
    \ifx\relax#1\relax\relax\else
      \citep{#1}%
    \fi
    \citep[#3][#4]{#5}%
    \ifnum\markdownLaTeXCitationsCounter>\markdownLaTeXCitationsTotal\relax
    \else
      \expandafter\expandafter\expandafter
      \expandafter\expandafter\expandafter\expandafter
      \markdownLaTeXNatbibCitations
    \fi
    \expandafter\expandafter\expandafter{%
    \expandafter\expandafter\expandafter}%
    \expandafter
    \@gobbletwo
  \fi\markdownLaTeXNatbibCitations{#1,#5}}
\def\markdownLaTeXNatbibTextCitations#1#2#3#4#5{%
  \advance\markdownLaTeXCitationsCounter by 1\relax
  \ifx\relax#3\relax
    \ifx\relax#4\relax
      \ifnum\markdownLaTeXCitationsCounter>\markdownLaTeXCitationsTotal\relax
        \citet{#1,#5}%  Without prenotes and postnotes, just accumulate cites
        \expandafter\expandafter\expandafter
        \expandafter\expandafter\expandafter\expandafter
        \@gobbletwo
      \fi
    \else%  After a prenote or a postnote, dump the accumulator
      \ifx\relax#1\relax\else
        \citet{#1}%
      \fi
      , \citet[#3][#4]{#5}%
      \ifnum\markdownLaTeXCitationsCounter<\markdownLaTeXCitationsTotal\relax
        ,
      \else
        \ifnum\markdownLaTeXCitationsCounter=\markdownLaTeXCitationsTotal\relax
          ,
        \fi
      \fi
      \expandafter\expandafter\expandafter
      \expandafter\expandafter\expandafter\expandafter
      \markdownLaTeXNatbibTextCitations
      \expandafter\expandafter\expandafter
      \expandafter\expandafter\expandafter\expandafter{%
      \expandafter\expandafter\expandafter
      \expandafter\expandafter\expandafter\expandafter}%
      \expandafter\expandafter\expandafter
      \@gobbletwo
    \fi
  \else%  After a prenote or a postnote, dump the accumulator
    \ifx\relax#1\relax\relax\else
      \citet{#1}%
    \fi
    , \citet[#3][#4]{#5}%
    \ifnum\markdownLaTeXCitationsCounter<\markdownLaTeXCitationsTotal\relax
      ,
    \else
      \ifnum\markdownLaTeXCitationsCounter=\markdownLaTeXCitationsTotal\relax
        ,
      \fi
    \fi
    \expandafter\expandafter\expandafter
    \markdownLaTeXNatbibTextCitations
    \expandafter\expandafter\expandafter{%
    \expandafter\expandafter\expandafter}%
    \expandafter
    \@gobbletwo
  \fi\markdownLaTeXNatbibTextCitations{#1,#5}}

% BibLaTeX implementation
\def\markdownLaTeXBibLaTeXCitations#1#2#3#4#5{%
  \advance\markdownLaTeXCitationsCounter by 1\relax
  \ifnum\markdownLaTeXCitationsCounter>\markdownLaTeXCitationsTotal\relax
    \autocites#1[#3][#4]{#5}%
    \expandafter\@gobbletwo
  \fi\markdownLaTeXBibLaTeXCitations{#1[#3][#4]{#5}}}
\def\markdownLaTeXBibLaTeXTextCitations#1#2#3#4#5{%
  \advance\markdownLaTeXCitationsCounter by 1\relax
  \ifnum\markdownLaTeXCitationsCounter>\markdownLaTeXCitationsTotal\relax
    \textcites#1[#3][#4]{#5}%
    \expandafter\@gobbletwo
  \fi\markdownLaTeXBibLaTeXTextCitations{#1[#3][#4]{#5}}}

\markdownSetup{rendererPrototypes = {
  cite = {%
    \markdownLaTeXCitationsCounter=1%
    \def\markdownLaTeXCitationsTotal{#1}%
    \@ifundefined{autocites}{%
      \@ifundefined{citep}{%
        \expandafter\expandafter\expandafter
        \markdownLaTeXBasicCitations
        \expandafter\expandafter\expandafter{%
        \expandafter\expandafter\expandafter}%
        \expandafter\expandafter\expandafter{%
        \expandafter\expandafter\expandafter}%
      }{%
        \expandafter\expandafter\expandafter
        \markdownLaTeXNatbibCitations
        \expandafter\expandafter\expandafter{%
        \expandafter\expandafter\expandafter}%
      }%
    }{%
      \expandafter\expandafter\expandafter
      \markdownLaTeXBibLaTeXCitations
      \expandafter{\expandafter}%
    }},
  textCite = {%
    \markdownLaTeXCitationsCounter=1%
    \def\markdownLaTeXCitationsTotal{#1}%
    \@ifundefined{autocites}{%
      \@ifundefined{citep}{%
        \expandafter\expandafter\expandafter
        \markdownLaTeXBasicTextCitations
        \expandafter\expandafter\expandafter{%
        \expandafter\expandafter\expandafter}%
        \expandafter\expandafter\expandafter{%
        \expandafter\expandafter\expandafter}%
      }{%
        \expandafter\expandafter\expandafter
        \markdownLaTeXNatbibTextCitations
        \expandafter\expandafter\expandafter{%
        \expandafter\expandafter\expandafter}%
      }%
    }{%
      \expandafter\expandafter\expandafter
      \markdownLaTeXBibLaTeXTextCitations
      \expandafter{\expandafter}%
    }}}}
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Links
% Before consuming the parameters for the hyperlink renderer, we change the
% category code of the hash sign (`#`) to other, so that it cannot be
% mistaken for a parameter character.
% \end{markdown}
%  \begin{macrocode}
\RequirePackage{url}
\RequirePackage{expl3}
\ExplSyntaxOn
\def\markdownRendererLinkPrototype#1#2#3#4{
  \tl_set:Nn \l_tmpa_tl { #1 }
  \tl_set:Nn \l_tmpb_tl { #2 }
  \bool_set:Nn
    \l_tmpa_bool
    {
      \tl_if_eq_p:NN
        \l_tmpa_tl
        \l_tmpb_tl
    }
  \tl_set:Nn \l_tmpa_tl { #4 }
  \bool_set:Nn
    \l_tmpb_bool
    {
      \tl_if_empty_p:N
        \l_tmpa_tl
    }
%    \end{macrocode}
% \begin{markdown}
% If the label and the fully-escaped URI are equivalent and the title is
% empty, assume that the link is an autolink. Otherwise, assume that the
% link is either direct or indirect.
% \end{markdown}
%  \begin{macrocode}
  \bool_if:nTF
    {
      \l_tmpa_bool && \l_tmpb_bool
    }
    {
      \markdownLaTeXRendererAutolink { #2 } { #3 }
    }{
      \markdownLaTeXRendererDirectOrIndirectLink { #1 } { #2 } { #3 } { #4 }
    }
}
\def\markdownLaTeXRendererAutolink#1#2{%
%    \end{macrocode}
% \begin{markdown}
% If the URL begins with a hash sign, then we assume that it is a relative
% reference. Otherwise, we assume that it is an absolute URL.
% \end{markdown}
%  \begin{macrocode}
  \tl_set:Nn
    \l_tmpa_tl
    { #2 }
  \tl_trim_spaces:N
    \l_tmpa_tl
  \tl_set:Nx
    \l_tmpb_tl
    {
      \tl_range:Nnn
        \l_tmpa_tl
        { 1 }
        { 1 }
    }
  \str_if_eq:NNTF
    \l_tmpb_tl
    \c_hash_str
    {
      \tl_set:Nx
        \l_tmpb_tl
        {
          \tl_range:Nnn
            \l_tmpa_tl
            { 2 }
            { -1 }
        }
      \exp_args:NV
        \ref
        \l_tmpb_tl
    }{
      \url { #2 }
    }
}
\ExplSyntaxOff
\def\markdownLaTeXRendererDirectOrIndirectLink#1#2#3#4{%
  #1\footnote{\ifx\empty#4\empty\else#4: \fi\url{#3}}}
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Tables
% Here is a basic implementation of tables. If the \pkg{booktabs} package is
% loaded, then it is used to produce horizontal lines.
%
% \end{markdown}
%  \begin{macrocode}
\newcount\markdownLaTeXRowCounter
\newcount\markdownLaTeXRowTotal
\newcount\markdownLaTeXColumnCounter
\newcount\markdownLaTeXColumnTotal
\newtoks\markdownLaTeXTable
\newtoks\markdownLaTeXTableAlignment
\newtoks\markdownLaTeXTableEnd
\AtBeginDocument{%
  \@ifpackageloaded{booktabs}{%
    \def\markdownLaTeXTopRule{\toprule}%
    \def\markdownLaTeXMidRule{\midrule}%
    \def\markdownLaTeXBottomRule{\bottomrule}%
  }{%
    \def\markdownLaTeXTopRule{\hline}%
    \def\markdownLaTeXMidRule{\hline}%
    \def\markdownLaTeXBottomRule{\hline}%
  }%
}
\markdownSetup{rendererPrototypes={
  table = {%
    \markdownLaTeXTable={}%
    \markdownLaTeXTableAlignment={}%
    \markdownLaTeXTableEnd={%
      \markdownLaTeXBottomRule
      \end{tabular}}%
    \ifx\empty#1\empty\else
      \addto@hook\markdownLaTeXTable{%
        \begin{table}
        \centering}%
      \addto@hook\markdownLaTeXTableEnd{%
        \caption{#1}
        \end{table}}%
    \fi
    \addto@hook\markdownLaTeXTable{\begin{tabular}}%
    \markdownLaTeXRowCounter=0%
    \markdownLaTeXRowTotal=#2%
    \markdownLaTeXColumnTotal=#3%
    \markdownLaTeXRenderTableRow
  }
}}
\def\markdownLaTeXRenderTableRow#1{%
  \markdownLaTeXColumnCounter=0%
  \ifnum\markdownLaTeXRowCounter=0\relax
    \markdownLaTeXReadAlignments#1%
    \markdownLaTeXTable=\expandafter\expandafter\expandafter{%
      \expandafter\the\expandafter\markdownLaTeXTable\expandafter{%
        \the\markdownLaTeXTableAlignment}}%
    \addto@hook\markdownLaTeXTable{\markdownLaTeXTopRule}%
  \else
    \markdownLaTeXRenderTableCell#1%
  \fi
  \ifnum\markdownLaTeXRowCounter=1\relax
    \addto@hook\markdownLaTeXTable\markdownLaTeXMidRule
  \fi
  \advance\markdownLaTeXRowCounter by 1\relax
  \ifnum\markdownLaTeXRowCounter>\markdownLaTeXRowTotal\relax
    \the\markdownLaTeXTable
    \the\markdownLaTeXTableEnd
    \expandafter\@gobble
  \fi\markdownLaTeXRenderTableRow}
\def\markdownLaTeXReadAlignments#1{%
  \advance\markdownLaTeXColumnCounter by 1\relax
  \if#1d%
    \addto@hook\markdownLaTeXTableAlignment{l}%
  \else
    \addto@hook\markdownLaTeXTableAlignment{#1}%
  \fi
  \ifnum\markdownLaTeXColumnCounter<\markdownLaTeXColumnTotal\relax\else
    \expandafter\@gobble
  \fi\markdownLaTeXReadAlignments}
\def\markdownLaTeXRenderTableCell#1{%
  \advance\markdownLaTeXColumnCounter by 1\relax
  \ifnum\markdownLaTeXColumnCounter<\markdownLaTeXColumnTotal\relax
    \addto@hook\markdownLaTeXTable{#1&}%
  \else
    \addto@hook\markdownLaTeXTable{#1\\}%
    \expandafter\@gobble
  \fi\markdownLaTeXRenderTableCell}
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### YAML Metadata {#latexyamlmetadata}
%
% The default setup of \acro{yaml} metadata will invoke the `\title`,
% `\author`, and `\date` macros when scalar values for keys that
% correspond to the `title`, `author`, and `date` relative wildcards are
% encountered, respectively.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\keys_define:nn
  { markdown/jekyllData }
  {
    author  .code:n = { \author{#1} },
    date    .code:n = { \date{#1}   },
    title   .code:n = { \title{#1}  },
  }
%    \end{macrocode}
% \begin{markdown}
%
% To complement the default setup of our key--values, we will use
% the `\maketitle` macro to typeset the title page of a document
% at the end of \acro{yaml} metadata. If we are in the preamble, we will wait
% macro until after the beginning of the document. Otherwise, we will use
% the `\maketitle` macro straight away.
%
% \end{markdown}
%  \begin{macrocode}
% TODO: Remove the command definition in TeX Live 2021.
\providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
\markdownSetup{
  rendererPrototypes = {
    jekyllDataEnd = {
%     TODO: Remove the else branch in TeX Live 2021.
      \IfFormatAtLeastTF
        { 2020-10-01 }
        { \AddToHook{begindocument/end}{\maketitle} }
        {
          \ifx\@onlypreamble\@notprerr
            % We are in the document
            \maketitle
          \else
            % We are in the preamble
            \RequirePackage{etoolbox}
            \AfterEndPreamble{\maketitle}
          \fi
        }
    },
  },
}
\ExplSyntaxOff
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Strike-Through
% If the \Opt{strikeThrough} option is enabled, we will load the
% \pkg{soulutf8} package and use it to implement strike-throughs.
%
% \end{markdown}
%  \begin{macrocode}
\markdownIfOption{strikeThrough}{%
  \RequirePackage{soulutf8}%
  \markdownSetup{
    rendererPrototypes = {
      strikeThrough = {%
        \st{#1}%
      },
    }
  }
}{}
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Raw Attribute Renderer Prototypes
%
% In the raw block and inline raw span renderer prototypes, execute the content
% with TeX when the raw attribute is `tex` or `latex`, display the content as
% markdown when the raw attribute is `md`, and ignore the content otherwise.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_gset:Npn
  \markdownRendererInputRawInlinePrototype#1#2
  {
    \str_case:nn
      { #2 }
      {
        { tex   } { \markdownEscape{#1} }
        { latex } { \markdownEscape{#1} }
        { md    } { \markdownInput{#1}  }
      }
  }
\cs_gset_eq:NN
  \markdownRendererInputRawBlockPrototype
  \markdownRendererInputRawInlinePrototype
\ExplSyntaxOff
\fi % Closes `\markdownIfOption{Plain}{\iffalse}{iftrue}`
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Miscellanea
% When buffering user input, we should disable the bytes with the high bit set,
% since these are made active by the \pkg{inputenc} package. We will do this by
% redefining the \mref{markdownMakeOther} macro accordingly. The code is courtesy
% of Scott Pakin, the creator of the \pkg{filecontents} package.
%
% \end{markdown}
%  \begin{macrocode}
\newcommand\markdownMakeOther{%
  \count0=128\relax
  \loop
    \catcode\count0=11\relax
    \advance\count0 by 1\relax
  \ifnum\count0<256\repeat}%
%    \end{macrocode}
% \iffalse
%</latex>
%<*context>
% \fi
% \par
% \begin{markdown}
%
% \Hologo{ConTeXt} Implementation {#contextimplementation}
%---------------------------------
%
% The \Hologo{ConTeXt} implementation makes use of the fact that, apart from
% some subtle differences, the Mark II and Mark IV \Hologo{ConTeXt} formats
% *seem* to implement (the documentation is scarce) the majority of the
% plain \TeX{} format required by the plain \TeX{} implementation.  As a
% consequence, we can directly reuse the existing plain \TeX{} implementation
% after supplying the missing plain \TeX{} macros.
%
% When buffering user input, we should disable the bytes with the high bit set,
% since these are made active by the `\enableregime` macro. We will do this
% by redefining the \mref{markdownMakeOther} macro accordingly. The code is
% courtesy of Scott Pakin, the creator of the \pkg{filecontents} \LaTeX{}
% package.
%
% \end{markdown}
%  \begin{macrocode}
\def\markdownMakeOther{%
  \count0=128\relax
  \loop
    \catcode\count0=11\relax
    \advance\count0 by 1\relax
  \ifnum\count0<256\repeat
%    \end{macrocode}
% \par
% \begin{markdown}
%
% On top of that, make the pipe character (`|`) inactive during the scanning.
% This is necessary, since the character is active in \Hologo{ConTeXt}.
%
% \end{markdown}
%  \begin{macrocode}
  \catcode`|=12}%
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Typesetting Markdown
% The \mref{inputmarkdown} is defined to accept an optional argument with
% options recognized by the \Hologo{ConTeXt} interface (see Section
% <#sec:contextoptions>).
%
% \end{markdown}
%  \begin{macrocode}
\long\def\inputmarkdown{%
  \dosingleempty
  \doinputmarkdown}%
\long\def\doinputmarkdown[#1]#2{%
  \begingroup
    \iffirstargument
      \setupmarkdown{#1}%
    \fi
    \markdownInput{#2}%
  \endgroup}%
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The \mref{startmarkdown} and \mref{stopmarkdown} macros are implemented using the
% \mref{markdownReadAndConvert} macro.
%
% In Knuth's \TeX, trailing spaces are removed very early on when a line is
% being put to the input buffer.~[@knuth86b, sec. 31].  According to
% @eijkhout92 [sec. 2.2], this is because ``these spaces are hard to see in
% an editor''. At the moment, there is no option to suppress this behavior in
% (Lua)\TeX, but \Hologo{ConTeXt} MkIV funnels all input through its own input
% handler. This makes it possible to suppress the removal of trailing spaces
% in \Hologo{ConTeXt} MkIV and therefore to insert hard line breaks into
% markdown text.
%
% \end{markdown}
%  \begin{macrocode}
\ifx\startluacode\undefined  % MkII
  \begingroup
    \catcode`\|=0%
    \catcode`\\=12%
    |gdef|startmarkdown{%
      |markdownReadAndConvert{\stopmarkdown}%
                             {|stopmarkdown}}%
    |gdef|stopmarkdown{%
      |markdownEnd}%
  |endgroup
\else  % MkIV
  \startluacode
    document.markdown_buffering = false
    local function preserve_trailing_spaces(line)
      if document.markdown_buffering then
        line = line:gsub("[ \t][ \t]$", "\t\t")
      end
      return line
    end
    resolvers.installinputlinehandler(preserve_trailing_spaces)
  \stopluacode
  \begingroup
    \catcode`\|=0%
    \catcode`\\=12%
    |gdef|startmarkdown{%
      |ctxlua{document.markdown_buffering = true}%
      |markdownReadAndConvert{\stopmarkdown}%
                             {|stopmarkdown}}%
    |gdef|stopmarkdown{%
      |ctxlua{document.markdown_buffering = false}%
      |markdownEnd}%
  |endgroup
\fi
%    \end{macrocode}
% \par
% \begin{markdown}
%
%### Token Renderer Prototypes
% The following configuration should be considered placeholder.
%
% \end{markdown}
%  \begin{macrocode}
\def\markdownRendererLineBreakPrototype{\blank}%
\def\markdownRendererLeftBracePrototype{\textbraceleft}%
\def\markdownRendererRightBracePrototype{\textbraceright}%
\def\markdownRendererDollarSignPrototype{\textdollar}%
\def\markdownRendererPercentSignPrototype{\percent}%
\def\markdownRendererUnderscorePrototype{\textunderscore}%
\def\markdownRendererCircumflexPrototype{\textcircumflex}%
\def\markdownRendererBackslashPrototype{\textbackslash}%
\def\markdownRendererTildePrototype{\textasciitilde}%
\def\markdownRendererPipePrototype{\char`|}%
\def\markdownRendererLinkPrototype#1#2#3#4{%
  \useURL[#1][#3][][#4]#1\footnote[#1]{\ifx\empty#4\empty\else#4:
  \fi\tt<\hyphenatedurl{#3}>}}%
\usemodule[database]
\defineseparatedlist
  [MarkdownConTeXtCSV]
  [separator={,},
   before=\bTABLE,after=\eTABLE,
   first=\bTR,last=\eTR,
   left=\bTD,right=\eTD]
\def\markdownConTeXtCSV{csv}
\def\markdownRendererContentBlockPrototype#1#2#3#4{%
  \def\markdownConTeXtCSV@arg{#1}%
  \ifx\markdownConTeXtCSV@arg\markdownConTeXtCSV
    \placetable[][tab:#1]{#4}{%
      \processseparatedfile[MarkdownConTeXtCSV][#3]}%
  \else
    \markdownInput{#3}%
  \fi}%
\def\markdownRendererImagePrototype#1#2#3#4{%
  \placefigure[][]{#4}{\externalfigure[#3]}}%
\def\markdownRendererUlBeginPrototype{\startitemize}%
\def\markdownRendererUlBeginTightPrototype{\startitemize[packed]}%
\def\markdownRendererUlItemPrototype{\item}%
\def\markdownRendererUlEndPrototype{\stopitemize}%
\def\markdownRendererUlEndTightPrototype{\stopitemize}%
\def\markdownRendererOlBeginPrototype{\startitemize[n]}%
\def\markdownRendererOlBeginTightPrototype{\startitemize[packed,n]}%
\def\markdownRendererOlItemPrototype{\item}%
\def\markdownRendererOlItemWithNumberPrototype#1{\sym{#1.}}%
\def\markdownRendererOlEndPrototype{\stopitemize}%
\def\markdownRendererOlEndTightPrototype{\stopitemize}%
\definedescription
  [MarkdownConTeXtDlItemPrototype]
  [location=hanging,
   margin=standard,
   headstyle=bold]%
\definestartstop
  [MarkdownConTeXtDlPrototype]
  [before=\blank,
   after=\blank]%
\definestartstop
  [MarkdownConTeXtDlTightPrototype]
  [before=\blank\startpacked,
   after=\stoppacked\blank]%
\def\markdownRendererDlBeginPrototype{%
  \startMarkdownConTeXtDlPrototype}%
\def\markdownRendererDlBeginTightPrototype{%
  \startMarkdownConTeXtDlTightPrototype}%
\def\markdownRendererDlItemPrototype#1{%
  \startMarkdownConTeXtDlItemPrototype{#1}}%
\def\markdownRendererDlItemEndPrototype{%
  \stopMarkdownConTeXtDlItemPrototype}%
\def\markdownRendererDlEndPrototype{%
  \stopMarkdownConTeXtDlPrototype}%
\def\markdownRendererDlEndTightPrototype{%
  \stopMarkdownConTeXtDlTightPrototype}%
\def\markdownRendererEmphasisPrototype#1{{\em#1}}%
\def\markdownRendererStrongEmphasisPrototype#1{{\bf#1}}%
\def\markdownRendererBlockQuoteBeginPrototype{\startquotation}%
\def\markdownRendererBlockQuoteEndPrototype{\stopquotation}%
\def\markdownRendererInputVerbatimPrototype#1{\typefile{#1}}%
\def\markdownRendererInputFencedCodePrototype#1#2{%
  \ifx\relax#2\relax
    \typefile{#1}%
  \else
%    \end{macrocode}
% \par
% \begin{markdown}
%
% The code fence infostring is used as a name from the \Hologo{ConTeXt}
% `\definetyping` macro. This allows the user to set up code highlighting
% mapping as follows:
% ````` tex
% % Map the `TEX` syntax highlighter to the `latex` infostring.
% \definetyping [latex]
% \setuptyping  [latex] [option=TEX]
%
% \starttext
%   \startmarkdown
% ~~~ latex
% \documentclass{article}
% \begin{document}
%   Hello world!
% \end{document}
% ~~~
%   \stopmarkdown
% \stoptext
% `````````
%
% \end{markdown}
%  \begin{macrocode}
    \typefile[#2][]{#1}%
  \fi}%
\def\markdownRendererHeadingOnePrototype#1{\chapter{#1}}%
\def\markdownRendererHeadingTwoPrototype#1{\section{#1}}%
\def\markdownRendererHeadingThreePrototype#1{\subsection{#1}}%
\def\markdownRendererHeadingFourPrototype#1{\subsubsection{#1}}%
\def\markdownRendererHeadingFivePrototype#1{\subsubsubsection{#1}}%
\def\markdownRendererHeadingSixPrototype#1{\subsubsubsubsection{#1}}%
\def\markdownRendererThematicBreakPrototype{%
  \blackrule[height=1pt, width=\hsize]}%
\def\markdownRendererNotePrototype#1{\footnote{#1}}%
\def\markdownRendererTickedBoxPrototype{$\boxtimes$}
\def\markdownRendererHalfTickedBoxPrototype{$\boxdot$}
\def\markdownRendererUntickedBoxPrototype{$\square$}
\def\markdownRendererStrikeThroughPrototype#1{\overstrikes{#1}}
\def\markdownRendererSuperscriptPrototype#1{\high{#1}}
\def\markdownRendererSubscriptPrototype#1{\low{#1}}
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Tables
% There is a basic implementation of tables.
%
% \end{markdown}
%  \begin{macrocode}
\newcount\markdownConTeXtRowCounter
\newcount\markdownConTeXtRowTotal
\newcount\markdownConTeXtColumnCounter
\newcount\markdownConTeXtColumnTotal
\newtoks\markdownConTeXtTable
\newtoks\markdownConTeXtTableFloat
\def\markdownRendererTablePrototype#1#2#3{%
  \markdownConTeXtTable={}%
  \ifx\empty#1\empty
    \markdownConTeXtTableFloat={%
      \the\markdownConTeXtTable}%
  \else
    \markdownConTeXtTableFloat={%
      \placetable{#1}{\the\markdownConTeXtTable}}%
  \fi
  \begingroup
  \setupTABLE[r][each][topframe=off, bottomframe=off, leftframe=off, rightframe=off]
  \setupTABLE[c][each][topframe=off, bottomframe=off, leftframe=off, rightframe=off]
  \setupTABLE[r][1][topframe=on, bottomframe=on]
  \setupTABLE[r][#1][bottomframe=on]
  \markdownConTeXtRowCounter=0%
  \markdownConTeXtRowTotal=#2%
  \markdownConTeXtColumnTotal=#3%
  \markdownConTeXtRenderTableRow}
\def\markdownConTeXtRenderTableRow#1{%
  \markdownConTeXtColumnCounter=0%
  \ifnum\markdownConTeXtRowCounter=0\relax
    \markdownConTeXtReadAlignments#1%
    \markdownConTeXtTable={\bTABLE}%
  \else
    \markdownConTeXtTable=\expandafter{%
      \the\markdownConTeXtTable\bTR}%
    \markdownConTeXtRenderTableCell#1%
    \markdownConTeXtTable=\expandafter{%
      \the\markdownConTeXtTable\eTR}%
  \fi
  \advance\markdownConTeXtRowCounter by 1\relax
  \ifnum\markdownConTeXtRowCounter>\markdownConTeXtRowTotal\relax
    \markdownConTeXtTable=\expandafter{%
      \the\markdownConTeXtTable\eTABLE}%
    \the\markdownConTeXtTableFloat
    \endgroup
    \expandafter\gobbleoneargument
  \fi\markdownConTeXtRenderTableRow}
\def\markdownConTeXtReadAlignments#1{%
  \advance\markdownConTeXtColumnCounter by 1\relax
  \if#1d%
    \setupTABLE[c][\the\markdownConTeXtColumnCounter][align=right]
  \fi\if#1l%
    \setupTABLE[c][\the\markdownConTeXtColumnCounter][align=right]
  \fi\if#1c%
    \setupTABLE[c][\the\markdownConTeXtColumnCounter][align=middle]
  \fi\if#1r%
    \setupTABLE[c][\the\markdownConTeXtColumnCounter][align=left]
  \fi
  \ifnum\markdownConTeXtColumnCounter<\markdownConTeXtColumnTotal\relax\else
    \expandafter\gobbleoneargument
  \fi\markdownConTeXtReadAlignments}
\def\markdownConTeXtRenderTableCell#1{%
  \advance\markdownConTeXtColumnCounter by 1\relax
  \markdownConTeXtTable=\expandafter{%
    \the\markdownConTeXtTable\bTD#1\eTD}%
  \ifnum\markdownConTeXtColumnCounter<\markdownConTeXtColumnTotal\relax\else
    \expandafter\gobbleoneargument
  \fi\markdownConTeXtRenderTableCell}
%    \end{macrocode}
% \par
% \begin{markdown}
%
%#### Raw Attribute Renderer Prototypes
%
% In the raw block and inline raw span renderer prototypes, execute the content
% with TeX when the raw attribute is `tex` or `context`, display the content as
% markdown when the raw attribute is `md`, and ignore the content otherwise.
%
% \end{markdown}
%  \begin{macrocode}
\ExplSyntaxOn
\cs_gset:Npn
  \markdownRendererInputRawInlinePrototype#1#2
  {
    \str_case:nn
      { #2 }
      {
        { tex     } { \markdownEscape{#1} }
        { context } { \markdownEscape{#1} }
        { md      } { \markdownInput{#1}  }
      }
  }
\cs_gset_eq:NN
  \markdownRendererInputRawBlockPrototype
  \markdownRendererInputRawInlinePrototype
\ExplSyntaxOff
\stopmodule\protect
%    \end{macrocode}
% \iffalse
%</context>
% \fi