markdown (9apr18)

git-svn-id: svn://tug.org/texlive/trunk@47397 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 6208 insertions, 866 deletions

diff --git a/Master/texmf-dist/source/generic/markdown/docstrip.cfg b/Master/texmf-dist/source/generic/markdown/docstrip.cfg
index 465fa1838ef..11f5397ec77 100644
--- a/Master/texmf-dist/source/generic/markdown/docstrip.cfg
+++ b/Master/texmf-dist/source/generic/markdown/docstrip.cfg
@@ -62,7 +62,7 @@
 \let\luapostamble\empty
 \declarepreamble\texpreamble
 
-Copyright (C) 2017 Vít Novotný
+Copyright (C) 2018 Vít Novotný
 
 This work may be distributed and/or modified under the
 conditions of the LaTeX Project Public License, either version 1.3
diff --git a/Master/texmf-dist/source/generic/markdown/markdown.dtx b/Master/texmf-dist/source/generic/markdown/markdown.dtx
index 03c95872f4e..0222985095c 100644
--- a/Master/texmf-dist/source/generic/markdown/markdown.dtx
+++ b/Master/texmf-dist/source/generic/markdown/markdown.dtx
@@ -1,22 +1,14 @@
 % \iffalse
 %<*driver>
 \documentclass{ltxdockit}
-\usepackage{btxdockit}
 \usepackage[utf8]{inputenc}
 \usepackage[T1]{fontenc}
 \usepackage[american]{babel}
-\usepackage{microtype}
-\usepackage{amsmath}
-\usepackage{fancyvrb}
-\usepackage{hologo}
-\usepackage{xcolor}
-\usepackage{doc}
+\usepackage{amsmath,btxdockit,doc,fancyvrb,hologo,microtype,minted,xcolor}
 
 % Set up the style.
 \emergencystretch=1em
-\RecustomVerbatimEnvironment
-  {Verbatim}{Verbatim}
-  {gobble=2,frame=single}
+\fvset{gobble=0,frame=single}
 \setcounter{secnumdepth}{4}
 \addtokomafont{title}{\sffamily}
 \addtokomafont{paragraph}{\spotcolor}
@@ -37,15 +29,16 @@
 \newcommand\m[1]{% A TeX macro reference
   \hyperref[macro:#1]{\textcolor{spot}{\cs{#1}}}}
 \newcommand\envmdef[1]{% A TeX macro definition
-  \phantomsection\label{environment:#1}\textcolor{spot}{\t`#1`}}
+  \phantomsection\label{environment:#1}\t`#1`}
 \newcommand\envm[1]{% A LaTeX environment reference
-  \hyperref[environment:#1]{\textcolor{spot}{\t`#1`}}}
+  \hyperref[environment:#1]{\t`#1`}}
 \newcommand\luamdef[1]{% A Lua object / method definition
-  \phantomsection\label{lua:#1}\textcolor{spot}{\t`#1`}}
+  \phantomsection\label{lua:#1}\t`#1`}
 \newcommand\luam[1]{% A Lua object / method reference
   \hyperref[lua:#1]{\t`#1`}}
-\def\t`#1`{% Inline code
+\def\inline#1{% Inline code
   \textcolor{spot}{\text{\texttt{#1}}}}
+\def\t`#1`{\inline{#1}}
 \newcommand\Optitem[2][]{\penalty -1000\relax % An option item definition
   \phantomsection\label{opt:#2}\optitem[#1]{#2}}
 \newcommand\Valitem[2][]{\penalty -1000\relax % A value item definition
@@ -55,6 +48,20 @@
 \newcommand\acro[1]{% An acronym
   \textsc{#1}}
 
+% Set up markdown.
+\usepackage[
+  citations,
+  definitionLists,
+  fencedCode,
+  hybrid,
+  html,
+  stripPercentSigns,
+  underscores=false]{markdown}
+\markdownSetup{
+  renderers = {
+    codeSpan = {\inline{#1}},
+    link = {#1\footnote{See \url{#3}.}}}}
+
 % Set up the catcodes.
 \catcode`\_=12 % We won't be typesetting math and Lua contains lots of `_`.
 
@@ -65,7 +72,7 @@
   url={https://github.com/witiko/markdown},
   author={Vít Novotný},
   email={witiko@mail.muni.cz},
-  revision={\input VERSION},
+  revision=\markdownVersion,
   date={\today}}
 \hypersetup{%
   pdftitle={A Markdown Interpreter for \TeX{}},
@@ -75,701 +82,4874 @@
 % Set up the bibliography.
 \usepackage{filecontents}
 \begin{filecontents}{markdown.bib}
-  @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{luatex17,
-    author    = {{Lua\TeX{} development team}},
-    title     = {Lua\TeX{} reference manual},
-    year      = {2017},
-    month     = {2},
-    url       = {http://www.luatex.org/svn/trunk/manual/luatex.pdf},
-    urldate   = {2018-01-08}}
-  @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       = {http://mirrors.ctan.org/macros/latex/base/source2e.pdf},
-    urldate   = {2018-01-08}}
-  @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{knuth86,
-    author    = {Knuth, Donald Ervin},
-    year      = {1986},
-    title     = {The \TeX{}book},
-    edition   = {3},
-    isbn      = {0-201-13447-0},
-    pagetotal = {ix, 479},
-    publisher = {Addison-Wesley}}
+@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{luatex17,
+  author    = {{Lua\TeX{} development team}},
+  title     = {Lua\TeX{} reference manual},
+  year      = {2017},
+  month     = {2},
+  url       = {http://www.luatex.org/svn/trunk/manual/luatex.pdf},
+  urldate   = {2018-01-08}}
+@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       = {http://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       = {http://mirrors.ctan.org/macros/latex/base/doc.pdf},
+  urldate   = {2018-02-19}}
+@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{knuth86,
+  author    = {Knuth, Donald Ervin},
+  year      = {1986},
+  title     = {The \TeX{}book},
+  edition   = {3},
+  isbn      = {0-201-13447-0},
+  pagetotal = {ix, 479},
+  publisher = {Addison-Wesley}}
 \end{filecontents}
 \usepackage[
   backend=biber,
-  style=iso-numeric,
+  style=numeric,
   sorting=none,
   autolang=other,
   sortlocale=auto]{biblatex}
 \addbibresource{markdown.bib}
 
 \begin{document}
-  \printtitlepage
-  \tableofcontents
-  \DocInput{markdown.dtx}
-  \printbibliography
+\printtitlepage
+\tableofcontents
+\DocInput{markdown.dtx}
+\printbibliography
 \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;
+  }
+}
+
+%</manual-css>
+%<*manual>
+
+---
+title:  Markdown Package User Manual
+author: Vít Novotný
+---
+
 % \fi
-%
-% \section{Introduction}
-% This document is a reference manual for the \pkg{Markdown} package. It is
-% split into three sections. This section explains the purpose and the
-% background of the package and outlines its prerequisites. Section
-% \ref{sec:interfaces} describes the interfaces exposed by the package along
-% with usage notes and examples. It is aimed at the user of the package.
-% Section \ref{sec:implementation} describes the implementation of the package.
-% It is aimed at the developer of the package and the curious user.
-%
-% \subsection{About \pkg{Markdown}}
-% The \pkg{Markdown} package provides facilities for the conversion of markdown
-% markup to plain \TeX{}. These are provided both in the form of a Lua module
-% and in the form of plain \TeX{}, \LaTeX{}, and \Hologo{ConTeXt} macro
-% packages that enable the direct inclusion of markdown documents inside \TeX{}
-% documents.
-%
-% Architecturally, the package consists of the \pkg{Lunamark} v0.5.0 Lua module
-% by John MacFarlane, which was slimmed down and rewritten for the needs of the
-% package. On top of \pkg{Lunamark} sits code for the plain \TeX{}, \LaTeX{},
-% and \Hologo{ConTeXt} formats by Vít Novotný.
-%
+% \par
+% \begin{markdown}
+
+<link href="https://afeld.github.io/emoji-css/emoji.css" rel="stylesheet" />
+
+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
+ConTeXt macro packages that can be used to directly typeset TeX documents
+containing markdown markup. Unlike other convertors, the Markdown package
+makes it easy to redefine how each and every markdown element is rendered.
+Creative abuse of the markdown syntax is encouraged. <i class="em em-wink"></i>
+
+ [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 \ref{sec:interfaces} describes the interfaces
+% exposed by the package. Section \ref{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
-%<*lua>
+
+This document is a user manual for the [Markdown package][pkg]. It provides
+beginner 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   = "2.5.5",
+    version   = "2.5.6",
     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-2018 Vít Novotný",
+    copyright = {"2009-2016 John MacFarlane, Hans Hagen",
+                 "2016-2018 Vít Novotný"},
     license   = "LPPL 1.3"
 }
+
+%    \end{macrocode}
+% \iffalse
+%</lua,lua-cli>
+%<*lua>
+% \fi
+%  \begin{macrocode}
 if not modules then modules = { } end
 modules['markdown'] = metadata
 %    \end{macrocode}
+% \par
+% \begin{markdown}
+%
+% 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 on the [\TeX-\LaTeX{} Stack Exchange.](https://tex.stackexchange.com)
+%
+% 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.
+%
+% Funding by the the Faculty of Informatics at the Masaryk~University
+% in~Brno~[@novotny15] is gratefully acknowledged.
+%
+% 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.
+%
+% \end{markdown}
+% \iffalse
+%</lua>
+%<*manual>
+
+Requirements
+------------
+
+The package requires a working TeX distribution. [TeX Live][] ≥ 2013 is known to
+work and so are recent installation of [MikTeX][]. If you are using a minimal
+installation of a TeX distribution, please consult the
+[technical documentation][techdoc] for a detailed list of required packages.
+
+ [TeX Live]: https://www.tug.org/texlive/ (TeX Live - TeX Users Group)
+ [MikTeX]: https://miktex.org/ (Home - MiKTeXorg)
+
+Installation
+------------
+
+The package comes pre-installed with [TeX Live][] ≥ 2016 and with recent
+installations of [MikTeX][]. Unless you explicitly wish to use the latest
+version of the package, you are encouraged to skip this step.
+
+To install the package, first download the package from the repository
+using Git:
+``` sh
+git clone https://github.com/witiko/markdown
+``````
+Next, enter the directory named `markdown` and interpret the file named
+`markdown.ins` file using a Unicode-aware TeX engine, such as XeTeX or
+LuaTeX:
+``` sh
+cd markdown
+luatex markdown.ins
+``````
+This should produce the following files:
+
+ * `markdown.lua` – the Lua module,
+ * `markdown-cli.lua` – the Lua command-line interface,
+ * `markdown.tex` – the plain TeX macro package,
+ * `markdown.sty` – the LaTeX package, and
+ * `t-markdown.tex` – the 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>/scripts/markdown/markdown-cli.lua`
+ * `<TEXMF>/tex/generic/markdown/markdown.tex`
+ * `<TEXMF>/tex/latex/markdown/markdown.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\<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.
+
+%</manual>
+%<*lua>
+% \fi
+% \par
+% \begin{markdown}
+%
+% Requirements
+%-------------
 %
-% \subsection{Feedback}
-% Please use the \pkg{markdown} project page on
-% GitHub\footnote{\url{https://github.com/witiko/markdown/issues}} to report
-% bugs and submit feature requests. Before making a feature request, please
-% ensure that you have thoroughly studied this manual. 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 on the \TeX-\LaTeX{} Stack
-% Exchange\footnote{\url{https://tex.stackexchange.com}}.
-%
-% \subsection{Acknowledgements}
-% I would like to thank the Faculty of Informatics at the Masaryk University in
-% Brno for providing me with the opportunity to work on this package alongside
-% my studies. I would also like to thank the creator of the Lunamark Lua
-% module, John Macfarlane, for releasing Lunamark under a permissive license
-% that enabled its inclusion into the package.
-%
-% The \TeX{} part 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.
-%
-% \subsection{Prerequisites}
 % This section gives an overview of all resources required by the package.
 %
-% \subsubsection{Lua Prerequisites}\label{sec:luaprerequisites}
+%### Lua Requirements
+% \label{sec:luaprerequisites}
 % The Lua part of the package requires that the following Lua modules are
 % available from within the Lua\TeX{} engine:
-% \begin{description}
-%   \item[\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$).
+%
+% \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}
-%   \item[\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 footnote tags to the lower case. \pkg{Selene
-%     Unicode} is included in all releases of Lua\TeX{} (\TeX
-%     Live${}\geq{}2008$).
+% \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 footnote 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 = require("unicode")
 %    \end{macrocode}
-%   \item[\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$).
+% \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}
-% \end{description}
+% \par
+% \begin{markdown}
+%
 % All the abovelisted modules are statically linked into the current version of
-% the Lua\TeX{} engine (see \cite[Section~3.3]{luatex17}).
+% the Lua\TeX{} engine~[@luatex17, Section 3.3].
 %
+% \end{markdown}
 % \iffalse
 %</lua>
 %<*tex>
 % \fi
-% \subsubsection{Plain \TeX{} Prerequisites}\label{sec:texprerequisites}
+% \par
+% \begin{markdown}
+%
+%### Plain \TeX{} Requirements
+% \label{sec: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 \ref{sec:luaprerequisites}), and the following Lua module:
-% \begin{description}
-%   \item[\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
-%     \m{markdownOptionCacheDir} macro before interfacing with the
-%     \pkg{Lunamark} library. \pkg{Lua File System} is included in all releases
-%     of Lua\TeX{} (\TeX Live${}\geq{}2008$).
+%
+% \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 \m{markdownOptionCacheDir} macro 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 \luam{isdir} method that was added
-%     to the \pkg{Lua File System} library by the Lua\TeX{} engine developers
-%     (see \cite[Section~3.2]{luatex17}).
-% \end{description}
+%     to the \pkg{Lua File System} library by the Lua\TeX{} engine
+%     developers~[@luatex17, Section 3.2].
+%
 % The \pkg{Lua File System} module is statically linked into the Lua\TeX{}
-% engine (see \cite[Section~3.3]{luatex17}).
+% engine~[@luatex17, Section~3.3].
 %
-% The plain \TeX{} part of the package also requires that either the Lua\TeX{}
+% Unless you convert markdown documents to \TeX{} manually using the Lua
+% command-line interface (see Section~\ref{sec:lua-cli-interface}), the plain
+% \TeX{} part of the package will require that either the Lua\TeX{}
 % \m{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 \m{markdownMode} macro, then note that
-% unless your \TeX{} engine is globally configured to enable shell access, you
-% will need to provide the \t`-shell-escape` parameter to your engine when
-% typesetting a document.
+% you enforce the use of shell using the \m{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
-% \subsubsection{\LaTeX{} Prerequisites}\label{sec:latexprerequisites}
+% \par
+% \begin{markdown}
+%
+%### \LaTeX{} Requirements
+% \label{sec:latexprerequisites}
 % The \LaTeX{} part of the package requires that the \Hologo{LaTeX2e} format is
 % loaded,
+% \end{markdown}
 %  \begin{macrocode}
 \NeedsTeXFormat{LaTeX2e}%
 %    \end{macrocode}
+% \begin{markdown}
 % all the plain \TeX{} prerequisites (see Section \ref{sec:texprerequisites}),
 % and the following \Hologo{LaTeX2e} packages:
-% \begin{description}
-%   \item[\pkg{keyval}] A package that enables the creation of parameter sets.
-%     This package is used to provide the \m{markdownSetup} macro, the package
-%     options processing, as well as the parameters of the \envm{markdown*}
-%     \LaTeX{} environment.
+%
+% \pkg{keyval}
+%
+%:    A package that enables the creation of parameter sets. This package is
+%     used to provide the \m{markdownSetup} macro, the package options
+%     processing, as well as the parameters of the \envm{markdown*} \LaTeX{}
+%     environment.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \RequirePackage{keyval}
 %    \end{macrocode}
-%   \item[\pkg{url}] A package that provides the \m{url} macro for the
-%     typesetting of \acro{url}s. It is used to provide the default token renderer
-%     prototype (see Section \ref{sec:texrendererprototypes}) for links.
+% \par
+% \begin{markdown}
+%
+% \pkg{url}
+%
+%:    A package that provides the \m{url} macro for the typesetting of
+%     \acro{url}s. It is used to provide the default token renderer prototype
+%     (see Section \ref{sec:texrendererprototypes}) for links.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \RequirePackage{url}
 %    \end{macrocode}
-%   \item[\pkg{graphicx}] A package that provides the \m{includegraphics} macro for
-%     the typesetting of images. It is used to provide the corresponding
-%     default token renderer prototype (see Section
-%     \ref{sec:texrendererprototypes}).
+% \par
+% \begin{markdown}
+%
+% \pkg{graphicx}
+%
+%:    A package that provides the \m{includegraphics} macro for the typesetting
+%     of images. It is used to provide the corresponding default token renderer
+%     prototype (see Section \ref{sec:texrendererprototypes}).
+%
+% \end{markdown}
 %  \begin{macrocode}
 \RequirePackage{graphicx}
 %    \end{macrocode}
-%   \item[\pkg{paralist}] A package that provides the \envm{compactitem},
-%     \envm{compactenum}, and \envm{compactdesc} macros for the
-%     typesetting of tight bulleted lists, ordered lists, and definition lists.
-%     It is used to provide the corresponding default token renderer prototypes
-%     (see Section \ref{sec:texrendererprototypes}).
-%   \item[\pkg{ifthen}] A package that provides a concise syntax for the
-%     inspection of macro values. It is used to determine whether or not the
-%     \pkg{paralist} package should be loaded based on the user options.
+% \par
+% \begin{markdown}
+%
+% \pkg{paralist}
+%
+%:    A package that provides the \envm{compactitem}, \envm{compactenum}, and
+%     \envm{compactdesc} macros for the typesetting of tight bulleted lists,
+%     ordered lists, and definition lists.  It is used to provide the
+%     corresponding default token renderer prototypes (see Section
+%     \ref{sec:texrendererprototypes}).
+%
+% \pkg{ifthen}
+%
+%:    A package that provides a concise syntax for the inspection of macro
+%     values. It is used to determine whether or not the \pkg{paralist} package
+%     should be loaded based on the user options.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \RequirePackage{ifthen}
 %    \end{macrocode}
-%   \item[\pkg{fancyvrb}] A package that provides the \m{VerbatimInput} macros
-%     for the verbatim inclusion of files containing code.  It is used to
-%     provide the corresponding default token renderer prototype (see Section
+% \par
+% \begin{markdown}
+%
+% \pkg{fancyvrb}
+%
+%:    A package that provides the \m{VerbatimInput} macros for the verbatim
+%     inclusion of files containing code. It is used to provide the
+%     corresponding default token renderer prototype (see Section
 %     \ref{sec:texrendererprototypes}).
+%
+% \end{markdown}
 %  \begin{macrocode}
 \RequirePackage{fancyvrb}
 %    \end{macrocode}
-%   \item[\pkg{csvsimple}] A package that provides the default token renderer
-%     prototype for iA\,Writer content blocks with the \acro{csv} filename
-%     extension (see Section \ref{sec:texrendererprototypes}).
+% \par
+% \begin{markdown}
+%
+% \pkg{csvsimple}
+%
+%:    A package that provides the default token renderer prototype for
+%     iA\,Writer content blocks with the \acro{csv} filename extension (see
+%     Section \ref{sec:texrendererprototypes}).
+%
+% \end{markdown}
 %  \begin{macrocode}
 \RequirePackage{csvsimple}
 %    \end{macrocode}
-% \end{description}
-%
 % \iffalse
 %</latex>
 %<*context>
 % \fi
-% \subsubsection{\Hologo{ConTeXt} prerequisites}
+% \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 \ref{sec:texprerequisites}), and the following \Hologo{ConTeXt}
 % modules:
-% \begin{description}
-%   \item[\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 \ref{sec:texrendererprototypes}).
-% \end{description}
-%
-% \section{User Guide}\label{sec:interfaces}
-% This part of the manual describes the interfaces exposed by the package
+%
+% \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 \ref{sec:texrendererprototypes}).
+%
+% Interfaces
+%===========
+% \label{sec: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 purely abstract. It serves as
-% a means of structuring this manual and as a promise to the user that if they
-% only access the package through the interfaces, the future versions of the
-% package should remain backwards compatible.
+% 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.
 %
+% \end{markdown}
 % \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.
+
+### 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 kpse = require("kpse")
+kpse.set_program_name("luatex")
+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 CLI
+
+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 `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows
+systems. Use the command `kpsewhich 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 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
+========
+
+This section will show how to use the package by example.
+
+%</manual>
+%<*lua>
+% \fi
+% \par
+% \begin{markdown}
+%
+% Lua Interface
+%--------------
+% \label{sec:luainterface}
+%
+% \iffalse
+%</lua>
+%<*manual>
+
+Lua
+---
+
+The Lua part of the package makes it possible to convert a markdown document
+into TeX commands and typeset it later when convenient. Although the typical
+user will not find this terribly useful and will instead use the plain TeX,
+LaTeX, and ConTeXt macro packages to convert and typeset the markdown documents
+in a single step, they will still benefit from learning the options that
+control the behavior of the Lua parser.
+
+%</manual>
 %<*lua>
 % \fi
-% \subsection{Lua Interface}\label{sec:luainterface}
+%
 % 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 \ref{sec:teximplementation}) and will be of
 % interest to the developers of other packages and Lua modules.
 %
-% The Lua interface is implemented by the \t`markdown` Lua module.
+% The Lua interface is implemented by the `markdown` Lua module.
 %
+% \end{markdown}
 %  \begin{macrocode}
-local M = {}
+local M = {metadata = metadata}
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Conversion from Markdown to Plain \TeX{}}
+%### Conversion from Markdown to Plain \TeX{}
 % \label{sec:luaconversion}
-% The Lua interface exposes the \luamdef{new}\t`(options)` method.  This
+% The Lua interface exposes the \luamdef{new}`(options)` method.  This
 % method creates converter functions that perform the conversion from markdown
-% to plain \TeX{} according to the table \t`options` that contains options
+% to plain \TeX{} according to the table `options` that contains options
 % recognized by the Lua interface.  (see Section \ref{sec:luaoptions}). The
-% \t`options` parameter is optional; when unspecified, the behaviour will be
-% the same as if \t`options` were an empty table.
+% `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 \t`_Hello
-% world!_` to a \TeX{} output using the default options and prints the \TeX{}
+% The following example Lua code converts the markdown string `Hello
+% *world*!` to a \TeX{} output using the default options and prints the \TeX{}
 % output:
-% \begin{Verbatim}
+% ``` lua
 % local md = require("markdown")
 % local convert = md.new()
-% print(convert("_Hello world!_"))
-% \end{Verbatim}
+% print(convert("Hello *world*!"))
+% ```````
 %
-% \subsubsection{Options}\label{sec:luaoptions}
+% \end{markdown}
+% \iffalse
+%</lua>
+%<*manual>
+
+### Interfaces
+
+The Lua part of the package exposes two interfaces – the `markdown` Lua module,
+and the Lua command-line interface (CLI).
+
+#### The Lua module
+
+The `markdown` Lua module exposes the `new(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 `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 kpse = require("kpse")
+kpse.set_program_name("luatex")
+local markdown = require("markdown")
+local convert_safe = markdown.new()
+local convert_unsafe = markdown.new({hybrid = true})
+local input = [[$\sqrt{-1}$ *equals* $i$.]]
+print(convert_safe(input) .. " " .. 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 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 convert_safe = markdown.new()
+  local convert_unsafe = markdown.new({hybrid = true})
+  local input = [[$\noexpand\sqrt{-1}$ *equals* $i$.]]
+  tex.sprint(convert_safe(input) .. " " .. 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 text
+“\$\\sqrt {-1}\$ *equals* \$i\$. √-̅1̅ *equals* $i$.” In this case, we cannot
+use pdfTeX, because pdfTeX does not define the `\directlua` TeX command.
+
+#### The Lua CLI
+
+The Lua command-line interface (CLI) 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\ \input unsafe
+\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 `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows
+systems. Use the command `kpsewhich 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
+“\$\\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>
+%<*lua>
+% \fi
+% \begin{markdown}
+%
+%### Options
+% \label{sec: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
+
+This section will cover the options recognized by the Lua interface. The
+interfaces of the plain TeX, LaTeX, and ConTeXt macro packages recognize these
+options as well, in addition to their own options.
+
+%</manual>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 local defaultOptions = {}
 %    \end{macrocode}
-% \pagebreak
-% \paragraph{File and Directory Names}
-% \begin{optionlist}
-%   \Valitem[.]{cacheDir}{path}
-%     A path to the directory containing auxiliary cache files. It is
-%     considered sane to set the path to a subdirectory of \t`outputDir`.
-%     If the last segment of the path does not exist, it will be created by the
-%     plain \TeX, \LaTeX, and \Hologo{ConTeXt} 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 \t`/tmp` on \acro{un*x} systems), which gets periodically
-%     emptied.
+% \begingroup
+% \markdownSetup{
+%   renderers = {
+%     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}}}}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+% \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 `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows
+systems. Use the command `kpsewhich 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.
+
+###### ConTeXt example {.unnumbered}
+
+Using a text editor, create a text document named `document.tex` with the
+following content:
+``` tex
+\usemodule[t][markdown]
+\def\markdownOptionCacheDir{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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.cacheDir = "."
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+% \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}}
 %
-%   \Valitem[.]{outputDir}{path}
-%     A path to the directory containing output files. The path must be set
-%     to the same value as the \t`-output-directory` option of your \TeX\
-%     engine for the package to function correctly.
-%  \begin{macrocode}
-defaultOptions.outputDir = "."
-%    \end{macrocode}
-% \end{optionlist}
-% \paragraph{Parser Options}
-% \begin{optionlist}
-%   \Optitem[false]{blankBeforeBlockquote}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Require a blank line between a paragraph and the following
-%         blockquote.
-%       \item[false] Do not require a blank line between a paragraph and the
-%         following blockquote.
-%     \end{valuelist}
+:    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 `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows
+systems. Use the command `kpsewhich 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.
+
+###### 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
+
+\def\markdownOptionBlankBeforeBlockquote{true}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.blankBeforeBlockquote = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `blankBeforeCodeFence`
+
+`blankBeforeCodeFence` (default value: `false`)
+
+% \fi
+% \begin{markdown}
+%
+% \Optitem[false]{blankBeforeCodeFence}{\opt{true}, \opt{false}}
 %
-%   \Optitem[false]{blankBeforeCodeFence}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Require a blank line between a paragraph and the following
-%         fenced code block.
-%       \item[false] Do not require a blank line between a paragraph and the
-%         following fenced code block.
-%     \end{valuelist}
+:    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 code fence."  .. newline ..
+          "```"            .. newline
+  tex.sprint(convert(input))
+
+  convert = markdown.new({
+    fencedCode = true, blankBeforeCodeFence = true})
+  input = "A paragraph."       .. newline ..
+          "```"                .. newline ..
+          "Not a code fence."  .. 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 code fence.
+> ```
+>
+> A paragraph. ``` Not a code fence. ```
+
+###### 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 `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows
+systems. Use the command `kpsewhich 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 code fence.
+```
+\markdownEnd
+
+\def\markdownOptionBlankBeforeCodeFence{true}
+\markdownBegin
+A paragraph.
+```
+Not a code fence.
+```
+\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 code fence.
+> ```
+>
+> A paragraph. ``` Not a code fence. ```
+
+###### 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 code fence.
+```
+\end{markdown}
+
+\begin{markdown*}{blankBeforeCodeFence}
+A paragraph.
+```
+Not a code fence.
+```
+\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 code fence.
+> ```
+>
+> A paragraph. ``` Not a code fence. ```
+
+###### ConTeXt example {.unnumbered}
+
+Using a text editor, create a text document named `document.tex` with the
+following content:
+```` tex
+\usemodule[t][markdown]
+\def\markdownOptionFencedCode{true}
+\starttext
+
+\startmarkdown
+A paragraph.
+```
+A code fence.
+```
+\stopmarkdown
+
+\def\markdownOptionBlankBeforeCodeFence{true}
+\startmarkdown
+A paragraph.
+```
+Not a code fence.
+```
+\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 code fence.
+> ```
+>
+> A paragraph. ``` Not a code fence. ```
+
+%</manual>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.blankBeforeCodeFence = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `blankBeforeHeading`
+
+`blankBeforeHeading` (default value: `false`)
+
+% \fi
+% \begin{markdown}
+%
+% \Optitem[false]{blankBeforeHeading}{\opt{true}, \opt{false}}
 %
-%   \Optitem[false]{blankBeforeHeading}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Require a blank line between a paragraph and the following
-%         header.
-%       \item[false] Do not require a blank line between a paragraph and the
-%         following header.
-%     \end{valuelist}
+:    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 `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows
+systems. Use the command `kpsewhich 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. ==============
+
+###### 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
+
+\def\markdownOptionBlankBeforeHeading{true}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.blankBeforeHeading = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `breakableBlockquotes`
+
+`breakableBlockquotes` (default value: `false`)
+
+% \fi
+% \begin{markdown}
 %
-%   \Optitem[false]{breakableBlockquotes}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] A blank line separates block quotes.
-%       \item[false] Blank lines in the middle of a block quote are ignored.
-%     \end{valuelist}
+% \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 `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows
+systems. Use the command `kpsewhich 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.
+
+###### 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
+
+\def\markdownOptionBreakableBlockquotes{true}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.breakableBlockquotes = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `citationNbsps`
+
+`citationNbsps` (default value: `true`)
+
+% \fi
+% \begin{markdown}
+%
+% \Optitem[false]{citationNbsps}{\opt{true}, \opt{false}}
 %
-%   \Optitem[false]{citationNbsps}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Replace regular spaces with non-breakable spaces inside the
-%         prenotes and postnotes of citations produced via the pandoc citation
-%         syntax extension.
-%       \item[false] Do not replace regular spaces with non-breakable spaces
-%         inside the prenotes and postnotes of citations produced via the pandoc
-%         citation syntax extension.
-%     \end{valuelist}
+:    true
+
+     :  Replace regular spaces with non-breakable spaces inside the prenotes
+        and postnotes of citations produced via the pandoc citation syntax
+        extension.
+
+     false
+
+     :  Do not replace regular spaces with non-breakable 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-breakable 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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.citationNbsps = true
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `citations`
+
+`citations` (default value: `false`)
+
+% \fi
+% \begin{markdown}
+%
+% \Optitem[false]{citations}{\opt{true}, \opt{false}}
 %
-%   \Optitem[false]{citations}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Enable the pandoc citation syntax extension:
-%         \begin{Verbatim}
-% 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.
-%         \end{Verbatim}
-%       \item[false] Disable the pandoc citation syntax extension.
-%     \end{valuelist}
+:    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 TeXbook, volume A of Computers and typesetting._
+>     Addison-Wesley, 1984.
+
+%</manual>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.citations = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `codeSpans`
+
+`codeSpans` (default value: `true`)
+
+% \fi
+% \begin{markdown}
+%
+% \Optitem[true]{codeSpans}{\opt{true}, \opt{false}}
 %
-%   \Optitem[true]{codeSpans}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Enable the code span syntax:
-%         \begin{Verbatim}
-% Use the `printf()` function.
-% ``There is a literal backtick (`) here.``
-%         \end{Verbatim}
-%       \item[false] Disable the code span syntax. This allows you to easily
-%         use the quotation mark ligatures in texts that do not contain code
-%         spans:
-%         \begin{Verbatim}
-% ``This is a quote.''
-%         \end{Verbatim}
-%     \end{valuelist}
+:    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 `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows
+systems. Use the command `kpsewhich 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.”
+
+###### 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
+
+\def\markdownOptionCodeSpans{false}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.codeSpans = true
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `contentBlocks`
+
+`contentBlocks` (default value: `false`)
+
+% \fi
+% \begin{markdown}
 %
-%   \Optitem[false]{contentBlocks}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Enable the iA\,Writer content blocks syntax
-%         extension~\cite{sotkov17}:
-%         \begin{Verbatim}
-% 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
-%         \end{Verbatim}
-%       \item[false] Disable the iA\,Writer content blocks syntax extension.
-%     \end{valuelist}
+% \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.
+%        \iffalse
+         iA Writer content blocks syntax extension.
+%        \fi
+
+% \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*.
+
+###### 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]
+\def\markdownOptionContentBlocks{true}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.contentBlocks = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `contentBlocksLanguageMap`
+
+`contentBlocksLanguageMap` (default value: `"markdown-languages.json"`)
+
+% \fi
+% \begin{markdown}
+%
+% \Valitem[markdown-languages.json]{contentBlocksLanguageMap}{filename}
 %
-%   \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. See
-%     Section~\ref{sec:texcontentblockrenderers} for more information.
+:    The filename of the JSON file that maps filename extensions to
+     programming language names in the iA Writer content blocks.
+%    See Section~\ref{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*.
+
+###### 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]
+\def\markdownOptionContentBlocks{true}
+\def\markdownOptionContentBlocksLanguageMap{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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.contentBlocksLanguageMap = "markdown-languages.json"
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `definitionLists`
+
+`definitionLists` (default value: `false`)
+
+% \fi
+% \begin{markdown}
+%
+% \Optitem[false]{definitionLists}{\opt{true}, \opt{false}}
 %
-%   \Optitem[false]{definitionLists}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Enable the pandoc definition list syntax extension:
-%         \begin{Verbatim}
-% Term 1
-% 
-% :   Definition 1
-% 
-% Term 2 with *inline markup*
-% 
-% :   Definition 2
-% 
-%         { some code, part of Definition 2 }
-% 
-%     Third paragraph of definition 2.
-%         \end{Verbatim}
-%       \item[false] Disable the pandoc definition list syntax extension.
-%     \end{valuelist}
+:    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.
+
+###### ConTeXt example {.unnumbered}
+
+Using a text editor, create a text document named `document.tex` with the
+following content:
+``` tex
+\usemodule[t][markdown]
+\def\markdownOptionDefinitionLists{true}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.definitionLists = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `fencedCode`
+
+`fencedCode` (default value: `false`)
+
+% \fi
+% \begin{markdown}
 %
-%   \Optitem[false]{fencedCode}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Enable the commonmark fenced code block extension:
-%         \begin{Verbatim}
-% ~~~ 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{Verbatim}
-%       \item[false] Disable the commonmark fenced code block extension.
-%     \end{valuelist}
+% \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>
+> ```
+
+###### ConTeXt example {.unnumbered}
+
+Using a text editor, create a text document named `document.tex` with the
+following content:
+``` tex
+\usemodule[t][markdown]
+\def\markdownOptionFencedCode{true}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.fencedCode = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `footnotes`
+
+`footnotes` (default value: `false`)
+
+% \fi
+% \begin{markdown}
 %
-%   \Optitem[false]{footnotes}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Enable the pandoc footnote syntax extension:
-%         \begin{Verbatim}
-% Here is a footnote reference,[^1] and another.[^longnote]
-% 
-% [^1]: Here is the footnote.
-% 
-% [^longnote]: Here's one with multiple blocks.
-% 
-%     Subsequent paragraphs are indented to show that they
-% belong to the previous footnote.
-% 
-%         { some.code }
-% 
-%     The whole paragraph can be indented, or just the
-%     first line.  In this way, multi-paragraph footnotes
-%     work like multi-paragraph list items.
-% 
-% This paragraph won't be part of the note, because it
-% isn't indented.
-%         \end{Verbatim}
-%       \item[false] Disable the pandoc footnote syntax extension.
-%     \end{valuelist}
+% \Optitem[false]{footnotes}{\opt{true}, \opt{false}}
+%
+:    true
+
+     :  Enable the pandoc footnote syntax extension:
+
+        ``` md
+        Here is a footnote reference,[^1] and another.[^longnote]
+
+        [^1]: Here is the footnote.
+
+        [^longnote]: Here's one with multiple blocks.
+
+            Subsequent paragraphs are indented to show that they
+        belong to the previous footnote.
+
+                { some.code }
+
+            The whole paragraph can be indented, or just the
+            first line.  In this way, multi-paragraph footnotes
+            work like multi-paragraph list items.
+
+        This paragraph won't be part of the note, because it
+        isn't indented.
+        ``````
+
+:    false
+
+     :    Disable the pandoc footnote 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[footnotes]{markdown}
+\begin{document}
+\begin{markdown}
+Here is a footnote reference,[^1] and another.[^longnote]
+
+[^1]: Here is the footnote.
+
+[^longnote]: Here's one with multiple blocks.
+
+    Subsequent paragraphs are indented to show that they
+belong to the previous footnote.
+
+        { some.code }
+
+    The whole paragraph can be indented, or just the
+    first line.  In this way, multi-paragraph footnotes
+    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 footnote reference,[^1] and another.[^longnote]
+> 
+> [^1]: Here is the footnote.
+> 
+> [^longnote]: Here's one with multiple blocks.
+> 
+>     Subsequent paragraphs are indented to show that they
+> belong to the previous footnote.
+> 
+>         { some.code }
+> 
+>     The whole paragraph can be indented, or just the
+>     first line.  In this way, multi-paragraph footnotes
+>     work like multi-paragraph list items.
+> 
+> This paragraph won't be part of the note, because it
+> isn't indented.
+
+###### ConTeXt example {.unnumbered}
+
+Using a text editor, create a text document named `document.tex` with the
+following content:
+``` tex
+\usemodule[t][markdown]
+\def\markdownOptionFootnotes{true}
+\starttext
+\startmarkdown
+Here is a footnote reference,[^1] and another.[^longnote]
+
+[^1]: Here is the footnote.
+
+[^longnote]: Here's one with multiple blocks.
+
+    Subsequent paragraphs are indented to show that they
+belong to the previous footnote.
+
+        { some.code }
+
+    The whole paragraph can be indented, or just the
+    first line.  In this way, multi-paragraph footnotes
+    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 footnote reference,[^1] and another.[^longnote]
+> 
+> [^1]: Here is the footnote.
+> 
+> [^longnote]: Here's one with multiple blocks.
+> 
+>     Subsequent paragraphs are indented to show that they
+> belong to the previous footnote.
+> 
+>         { some.code }
+> 
+>     The whole paragraph can be indented, or just the
+>     first line.  In this way, multi-paragraph footnotes
+>     work like multi-paragraph list items.
+> 
+> This paragraph won't be part of the note, because it
+> isn't indented.
+
+%</manual>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.footnotes = false
 %    \end{macrocode}
-% 
-%   \Optitem[false]{hashEnumerators}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Enable the use of hash symbols (\t`\#`) as ordered item
-%         list markers:
-%         \begin{Verbatim}
-% #.  Bird
-% #.  McHale
-% #.  Parish
-%         \end{Verbatim}
-%       \item[false] Disable the use of hash symbols (\t`\#`) as ordered item
-%         list markers.
-%     \end{valuelist}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### 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
+
+###### 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
+
+\def\markdownOptionHashEnumerators{true}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.hashEnumerators = false
 %    \end{macrocode}
-% 
-%   \Optitem[false]{html}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true]  Enable the recognition of \textsc{html} tags, block
-%                    elements, comments, \textsc{html} instructions, and
-%                    entities in the input. Tags, block elements (along with
-%                    contents), \textsc{html} instructions, and comments will
-%                    be ignored and \textsc{html} entities will be replaced
-%                    with the corresponding Unicode codepoints.
-%
-%       \item[false] Disable the recognition of \textsc{html} markup. Any
-%                    \textsc{html} markup in the input will be rendered as
-%                    plain text.
-%     \end{valuelist}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `html`
+
+`html` (default value: `false`)
+
+% \fi
+% \begin{markdown}
+%
+% \Optitem[false]{html}{\opt{true}, \opt{false}}
+%
+:    true
+
+     :  Enable the recognition of HTML tags, block elements, comments, HTML
+        instructions, and entities in the input.  Tags, block elements (along
+        with contents), HTML instructions, and comments 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
+
+When the option is enabled, HTML entities are currently incorrectly parsed.
+See [the corresponding issue][issue-38] in the package repository.
+
+ [issue-36]: https://github.com/Witiko/markdown/issues/36
+             (HTML entities with the `html` Lua option enabled produce a Lua
+              parser error)
+
+###### 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 `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows
+systems. Use the command `kpsewhich 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.
+
+###### 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
+
+\def\markdownOptionHtml{true}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.html = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `hybrid`
+
+`hybrid` (default value: `true`)
+
+% \fi
+% \begin{markdown}
 %
-%   \Optitem[false]{hybrid}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[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.
+% \Optitem[false]{hybrid}{\opt{true}, \opt{false}}
 %
-%       \item[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{valuelist}
+:    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 convert_safe = markdown.new()
+  local convert_unsafe = markdown.new({hybrid = true})
+  local input = [[$\noexpand\sqrt{-1}$ *equals* $i$.]]
+  tex.sprint(convert_safe(input) .. " " .. 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
+\input optiontrue
+\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 `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows
+systems. Use the command `kpsewhich 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$.
+
+###### 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
+\def\markdownOptionHybrid{true}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.hybrid = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `inlineFootnotes`
+
+`inlineFootnotes` (default value: `false`)
+
+% \fi
+% \begin{markdown}
+%
+% \Optitem[false]{inlineFootnotes}{\opt{true}, \opt{false}}
 %
-%   \Optitem[false]{inlineFootnotes}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Enable the pandoc inline footnote syntax extension:
-%         \begin{Verbatim}
-% 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{Verbatim}
-%       \item[false] Disable the pandoc inline footnote syntax extension.
-%     \end{valuelist}
+:    true
+
+     :  Enable the pandoc inline footnote 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 footnote 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[footnotes, inlineFootnotes]{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.]
+
+###### ConTeXt example {.unnumbered}
+
+Using a text editor, create a text document named `document.tex` with the
+following content:
+``` tex
+\usemodule[t][markdown]
+\def\markdownOptionFootnotes{true}
+\def\markdownOptionInlineFootnotes{true}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.inlineFootnotes = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `preserveTabs`
+
+`preserveTabs` (default value: `false`)
+
+% \fi
+% \begin{markdown}
 %
-%   \Optitem[false]{preserveTabs}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Preserve all tabs in the input.
-%       \item[false] Convert any tabs in the input to spaces.
-%     \end{valuelist}
+% \Optitem[false]{preserveTabs}{\opt{true}, \opt{false}}
+%
+:    true
+
+     :  Preserve all tabs in the input.
+
+:    false
+
+     :  Convert any tabs in the input to spaces.
+
+% \end{markdown}
+% \iffalse
+
+This option is currently non-functional. See [the corresponding
+issue][issue-38] in the package repository.
+
+ [issue-38]: https://github.com/Witiko/markdown/issues/38
+             (Tabs are stripped even with the `preserveTabs=true`
+              Lua option enabled)
+
+%</manual>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.preserveTabs = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `smartEllipses`
+
+`smartEllipses` (default value: `false`)
+
+% \fi
+% \begin{markdown}
+%
+% \Optitem[false]{smartEllipses}{\opt{true}, \opt{false}}
 %
-%   \Optitem[false]{smartEllipses}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Convert any ellipses in the input to the
-%         \m{markdownRendererEllipsis} \TeX{} macro.
-%       \item[false] Preserve all ellipses in the input.
-%     \end{valuelist}
+:    true
+
+     :   Convert any ellipses in the input to the
+%        \m{markdownRendererEllipsis} \TeX{} macro.
+%        \iffalse
+         `\markdownRendererEllipsis` TeX macro.
+%        \fi
+
+:    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()
+  input = "These are just three regular dots ..."
+  tex.sprint(convert(input)) }
+\par
+\directlua{
+  local markdown = require("markdown")
+  local convert = markdown.new({smartEllipses = true})
+  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 `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows
+systems. Use the command `kpsewhich 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.
+
+###### 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
+
+\def\markdownOptionSmartEllipses{true}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.smartEllipses = false
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `startNumber`
+
+`startNumber` (default value: `true`)
+
+% \fi
+% \begin{markdown}
+%
+% \Optitem[true]{startNumber}{\opt{true}, \opt{false}}
 %
-%   \Optitem[true]{startNumber}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Make the number in the first item in ordered lists
-%         significant. The item numbers will be passed to the
-%         \m{markdownRendererOlItemWithNumber} \TeX{} macro.
-%       \item[false] Ignore the number in the items of ordered lists. Each
-%         item will only produce a \m{markdownRendererOlItem} \TeX{} macro.
-%     \end{valuelist}
+:    true
+
+     :   Make the number in the first item of an ordered lists significant. The
+         item numbers will be passed to the
+%        \m{markdownRendererOlItemWithNumber} \TeX{} macro.
+%        \iffalse
+         `\markdownRendererOlItemWithNumber` TeX macro.
+%        \fi
+
+:    false
+
+     :   Ignore the numbers in the ordered list items. Each item will only
+         produce a
+%        \m{markdownRendererOlItem} \TeX{} macro.
+%        \iffalse
+         `\markdownRendererOlItem` TeX macro.
+%        \fi
+
+% \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
+
+###### 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
+
+\def\markdownOptionStartNumber{false}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.startNumber = true
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `tightLists`
+
+`tightLists` (default value: `true`)
+
+% \fi
+% \begin{markdown}
 %
-%   \Optitem[true]{tightLists}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true] Lists whose bullets do not consist of multiple paragraphs
-%         will be detected and passed to the 
-%         \m{markdownRendererOlBeginTight}, \m{markdownRendererOlEndTight},
-%         \m{markdownRendererUlBeginTight}, \m{markdownRendererUlEndTight},
-%         \m{markdownRendererDlBeginTight}, and \m{markdownRendererDlEndTight}
-%         macros.
-%       \item[false] Lists whose bullets do not consist of multiple paragraphs
-%         will be treated the same way as lists that do.
-%     \end{valuelist}
+% \Optitem[true]{tightLists}{\opt{true}, \opt{false}}
+%
+:    true
+
+     :   Lists whose bullets do not consist of multiple paragraphs will be
+         passed to the
+%        \m{markdownRendererOlBeginTight}, \m{markdownRendererOlEndTight},
+%        \m{markdownRendererUlBeginTight}, \m{markdownRendererUlEndTight},
+%        \m{markdownRendererDlBeginTight}, and
+%        \m{markdownRendererDlEndTight} \TeX{} macros.
+%        \iffalse
+         `\markdownRendererOlBeginTight`, `\markdownRendererOlEndTight`,
+         `\markdownRendererUlBeginTight`, `\markdownRendererUlEndTight`,
+         `\markdownRendererDlBeginTight`, and
+         `\markdownRendererDlEndTight` TeX macros.
+%        \fi
+
+:    false
+
+     :   Lists whose bullets do not consist of multiple paragraphs will be
+         treated the same way as lists that do 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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.tightLists = true
 %    \end{macrocode}
+% \par
+% \iffalse
+%</lua,lua-cli>
+%<*manual>
+
+##### Option `underscores`
+
+`underscores` (default value: `true`)
+
+% \fi
+% \begin{markdown}
 %
-%   \Optitem[true]{underscores}{\opt{true}, \opt{false}}
-%     \begin{valuelist}
-%       \item[true]  Both underscores and asterisks can be used to denote
-%         emphasis and strong emphasis:
-%         \begin{Verbatim}
-% *single asterisks*
-% _single underscores_
-% **double asterisks**
-% __double underscores__
-%         \end{Verbatim}
-%       \item[false] Only asterisks can be used to denote emphasis and strong
-%         emphasis. This makes it easy to write math with the \t`hybrid` option
-%         without the need to constantly escape subscripts.
-%     \end{valuelist}
+% \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ₙ*.
+
+###### ConTeXt example {.unnumbered}
+
+Using a text editor, create a text document named `document.tex` with the
+following content:
+``` tex
+\usemodule[t][markdown]
+\def\markdownOptionHybrid{true}
+\starttext
+
+\startmarkdown
+This is _emphasized text_ and this is a math subscript: $m\_n$.
+\stopmarkdown
+
+\def\markdownOptionUnderscores{false}
+\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>
+%<*lua,lua-cli>
+% \fi
 %  \begin{macrocode}
 defaultOptions.underscores = true
 %    \end{macrocode}
-% \end{optionlist}
-% 
+% \endgroup
 % \iffalse
-%</lua>
+%</lua,lua-cli>
+%<*lua-cli>
+% \fi
+% \par
+% \begin{markdown}
+%
+%### Command-Line Interface
+% \label{sec:lua-cli-interface}
+% To provide finer control over the conversion and to simplify debugging, a
+% command-line Lua interface for converting a Markdown document to \TeX{} is
+% also provided.
+%
+% \end{markdown}
+%  \begin{macrocode}
+
+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>]]
+
+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
+
+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~\ref{sec:luaoptions}.
+% \end{markdown}
+%  \begin{macrocode}
+    elseif arg[i]:match("=") then
+      key, value = arg[i]:match("(.-)=(.*)")
+%    \end{macrocode}
+% \begin{markdown}
+% The \luam{defaultOptions} table is consulted to identify whether \meta{value}
+% should be parsed as a string or as a boolean.
+% \end{markdown}
+%  \begin{macrocode}
+      default_type = type(defaultOptions[key])
+      if default_type == "boolean" then
+        options[key] = (value == "true")
+      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
+% ```````
+%
+% This shows another advantage of using the command-line interface compared to
+% using a higher-level \TeX{} interface -- it is unnecessary to provide shell
+% access for the \TeX{} engine.
+%
+% \end{markdown}
+% \iffalse
+%</lua-cli>
 %<*tex>
-% \fi\subsection{Plain \TeX{} Interface}\label{sec:texinterface}
-% The plain \TeX{} interface provides macros for the typesetting of markdown input
-% from within plain \TeX{}, for setting the Lua interface options (see Section
-% \ref{sec:luaoptions}) used during the conversion from markdown to plain
-% \TeX{}, and for changing the way markdown the tokens are rendered.
+% \fi
+% \par
+% \begin{markdown}
+%
+% Plain \TeX{} Interface
+%-----------------------
+% \label{sec:texinterface}
+%
+% \iffalse
+%</tex>
+%<*manual>
+
+Plain TeX
+---------
+
+The plain TeX macro package provides TeX commands for typesetting markdown
+documents that invoke the Lua parser in the background. Beside TeX commands
+that correspond to the Lua options, the macro package also provides commands
+corresponding to additional plain TeX-specific options, and so-called *token
+renderer* commands that define how the individual markdown elements will be
+typeset.
+
+### Interfaces
+
+<!-- TODO -->
+
+%</manual>
+%<*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 \ref{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{2018/01/08}%
-\def\markdownVersion{2.5.5}%
+\def\markdownLastModified{2018/04/08}%
+\def\markdownVersion{2.5.6}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% The plain \TeX{} interface is implemented by the \t`markdown.tex` file that
-% can be loaded as follows:
-% \begin{Verbatim}
+% The plain \TeX{} interface is implemented by the `markdown.tex` file that can
+% be loaded as follows:
+% ``` tex
 % \input markdown
-% \end{Verbatim}
-% It is expected that the special plain \TeX{} characters have the expected
-% category codes, when \m{input}ting the file.
+% ```````
+% \noindent It is expected that the special plain \TeX{} characters have the
+% expected category codes, when \m{input}ting the file.
 %
-% \subsubsection{Typesetting Markdown}\label{sec:textypesetting}
+%### Typesetting Markdown
+% \label{sec:textypesetting}
 % The interface exposes the \mdef{markdownBegin}, \mdef{markdownEnd}, and
 % \mdef{markdownInput} macros.
 %
 % The \m{markdownBegin} macro marks the beginning of a markdown document
 % fragment and the \m{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 \m{markdownBegin} macro and redefine the
 % \m{markdownEnd} macro to produce special effects before and after the
 % markdown block.
@@ -783,14 +4963,15 @@ defaultOptions.underscores = true
 %
 % 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{} (see
-% \cite[p.~46]{knuth86}). As a corrolary, the \m{markdownBegin} macro also
+% spaces are removed before the lines enter the input buffer of
+% \TeX{}~[@knuth86, p. 46]. As a corrolary, the \m{markdownBegin} macro also
 % ignores them.
 %
 % The \m{markdownBegin} and \m{markdownEnd} macros will also consume the rest
 % of the lines at which they appear.  In the following example plain \TeX{}
-% code, the characters \t`c`, \t`e`, and \t`f` will not appear in the output.
-% \begin{Verbatim}
+% code, the characters `c`, `e`, and `f` will not appear in the output.
+%
+% ``` tex
 % \input markdown
 % a
 % b \markdownBegin c 
@@ -798,114 +4979,166 @@ defaultOptions.underscores = true
 % e \markdownEnd   f
 % g 
 % \bye
-% \end{Verbatim}
+% ```````
 %
 % Note that you may also not nest the \m{markdownBegin} and \m{markdownEnd}
 % macros.
 %
 % The following example plain \TeX{} code showcases the usage of the
 % \m{markdownBegin} and \m{markdownEnd} macros:
-% \begin{Verbatim}
+%
+% ``` tex
 % \input markdown
 % \markdownBegin
 % _Hello_ **world** ...
 % \markdownEnd
 % \bye
-% \end{Verbatim}
+% ```````
 %
 % The \m{markdownInput} macro accepts a single parameter containing 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
 % \m{markdownBegin} and \m{markdownEnd} macros.
 %
 % The following example plain \TeX{} code showcases the usage of the
 % \m{markdownInput} macro:
-% \begin{Verbatim}
+%
+% ``` tex
 % \input markdown
 % \markdownInput{hello.md}
 % \bye
-% \end{Verbatim}
+% ```````
+%
+%### Options
+% \label{sec:texoptions}
+%
+% \iffalse
+%</tex>
+%<*manual>
+
+### Options
+
+<!-- TODO -->
+
+%</manual>
+%<*tex>
+% \fi
 %
-% \subsubsection{Options}\label{sec:texoptions}
 % The plain \TeX{} options are represented by \TeX{} macros. Some of them map
-% directly to the options recognized by the Lua interface (see Section
-% \ref{sec:luaoptions}), while some of them are specific to the plain \TeX{}
-% interface.
+% directly to the options recognized by the Lua interface (see
+% Section~\ref{sec:luaoptions}), while some of them are specific to the plain
+% \TeX{} interface.
 %
-% \paragraph{File and Directory names}
+%#### File and Directory names
 % 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 \m{directlua} primitive. It
-% defaults to \m{jobname}\t`.markdown.lua`, where \m{jobname} is the base name
+% defaults to \m{jobname}`.markdown.lua`, where \m{jobname} is the base name
 % of the document being typeset.
 %
-% The expansion of this macro must not contain quotation marks (\t`"`) or
-% backslash symbols (\t`\textbackslash`). Mind that \TeX{} engines tend to
+% The expansion of this macro must not contain quotation marks (`"`) or
+% backslash symbols (`extbackslash`). Mind that \TeX{} engines tend to
 % put quotation marks around \m{jobname}, when it contains spaces.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownOptionHelperScriptFileName{\jobname.markdown.lua}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \mdef{markdownOptionInputTempFileName} macro sets the filename of the
 % temporary input file that is created during the conversion from markdown to
-% plain \TeX{} in \m{markdownMode} other than \t`2`. It defaults to
-% \m{jobname}\t`.markdown.out`. The same limitations as in the case of the
+% plain \TeX{} in \m{markdownMode} other than `2`. It defaults to
+% \m{jobname}`.markdown.out`. The same limitations as in the case of the
 % \m{markdownOptionHelperScriptFileName} macro apply here.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownOptionInputTempFileName{\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 \m{markdownMode} other than \t`2`. It defaults to
-% \m{jobname}\t`.markdown.out`. The same limitations apply here as in the case
+% plain \TeX{} in \m{markdownMode} other than `2`. It defaults to
+% \m{jobname}`.markdown.out`. The same limitations apply here as in the case
 % of the \m{markdownOptionHelperScriptFileName} macro.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownOptionOutputTempFileName{\jobname.markdown.out}%
 %    \end{macrocode}
+% \par
+% \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 \m{markdownMode} other than
-% \t`2`. It defaults to \m{jobname}\t`.markdown.err`. The same limitations
+% `2`. It defaults to \m{jobname}`.markdown.err`. The same limitations
 % apply here as in the case of the \m{markdownOptionHelperScriptFileName}
 % macro.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownOptionErrorTempFileName{\jobname.markdown.err}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \mdef{markdownOptionCacheDir} macro corresponds to the Lua interface
-% \Opt{cacheDir} option that sets the name of the directory that will contain
-% the produced cache files. The option defaults to \t`_markdown_`\m{jobname},
+% \Opt{cacheDir} option that sets the path to the directory that will contain
+% the produced cache files. The option defaults to `_markdown_`\m{jobname},
 % which is a similar naming scheme to the one used by the \pkg{minted} \LaTeX{}
 % package. The same limitations apply here as in the case of the
 % \m{markdownOptionHelperScriptFileName} macro.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownOptionCacheDir{\markdownOptionOutputDir/_markdown_\jobname}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% The \mdef{markdownOptionOutputDir} macro corresponds to the Lua interface
-% \Opt{outputDir} option that sets the name of the directory that will contain
-% the produced cache files. The option defaults to \t`.`. The same limitations
-% apply here as in the case of the \m{markdownOptionHelperScriptFileName}
-% macro.
+% The \mdef{markdownOptionOutputDir} macro sets the path to the directory that
+% will contain the 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
+% \m{markdownOptionHelperScriptFileName} macro.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownOptionOutputDir{.}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Lua Interface Options}
+%#### Lua Interface Options
 % The following macros map directly to the options recognized by the Lua
 % interface (see Section \ref{sec:luaoptions}) and are not processed by the
 % plain \TeX{} implementation, only passed along to Lua. They are undefined, which
 % makes them fall back to the default values provided by the Lua interface.
-% 
+%
 % 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
 % \m{markdownOptionHelperScriptFileName} macro.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \let\markdownOptionBlankBeforeBlockquote\undefined
 \let\markdownOptionBlankBeforeCodeFence\undefined
@@ -927,8 +5160,59 @@ defaultOptions.underscores = true
 \let\markdownOptionStartNumber\undefined
 \let\markdownOptionTightLists\undefined
 %    \end{macrocode}
+% \par
+% \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~\ref{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).
+%
+% \end{markdown}
+%  \begin{macrocode}
+\def\markdownOptionStripPercentSigns{false}%
+%    \end{macrocode}
+% \par
+% \begin{markdown}
+%
+% The \mdef{markdownIfOption}`{`\meta{name}`}` macro is provided for testing,
+% whether the value of `\markdownOption`\meta{name} is `true` or `false`.
+%
+% \end{markdown}
+%  \begin{macrocode}
+\def\markdownIfOption#1{%
+  \def\next##1##2##3##4##5{%
+    \expandafter\def\expandafter\next\expandafter{%
+      \csname iffalse\endcsname}%
+    \if##1t\if##2r\if##3u\if##4e
+      \expandafter\def\expandafter\next\expandafter{%
+        \csname iftrue\endcsname}%
+    \fi\fi\fi\fi
+    \next}%
+  \expandafter\expandafter\expandafter\next
+    \csname markdownOption#1\endcsname\relax\relax\relax\relax\relax}
+%    \end{macrocode}
+% \par
+% \begin{markdown}
+%
+%### Token Renderers
+% \label{sec:texrenderersuser}
+%
+% \iffalse
+%</tex>
+%<*manual>
+
+### Token renderers
+
+<!-- TODO -->
+
+%</manual>
+%<*tex>
+% \fi
 %
-% \subsubsection{Token Renderers}\label{sec:texrenderersuser}
 % The following \TeX{} macros may occur inside the output of the
 % converter functions exposed by the Lua interface (see Section
 % \ref{sec:luaconversion}) and represent the parsed markdown tokens. These
@@ -936,43 +5220,61 @@ defaultOptions.underscores = true
 % document. By default, they point to the corresponding prototypes (see Section
 % \ref{sec:texrendererprototypes}).
 %
-% \paragraph{Interblock Separator Renderer}
+%#### Interblock Separator Renderer
 % The \mdef{markdownRendererInterblockSeparator} macro represents a separator
 % between two markdown block elements. The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererInterblockSeparator{%
   \markdownRendererInterblockSeparatorPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Line Break Renderer}
+%#### Line Break Renderer
 % The \mdef{markdownRendererLineBreak} macro represents a forced line break.
 % The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererLineBreak{%
   \markdownRendererLineBreakPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Ellipsis Renderer}
+%#### 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 \t`true`.  The macro receives no arguments.
+% \Opt{smartEllipses} option is `true`.  The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererEllipsis{%
   \markdownRendererEllipsisPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Non-breaking Space Renderer}
+%#### Non-breaking Space Renderer
 % The \mdef{markdownRendererNbsp} macro represents a non-breaking space.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererNbsp{%
   \markdownRendererNbspPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Special Character Renderers}
+%#### Special Character Renderers
 % The following macros replace any special plain \TeX{} characters (including
-% the active pipe character (\t`|`) of \Hologo{ConTeXt}) in the input text.
+% the active pipe character (`|`) of \Hologo{ConTeXt}) in the input text.
 % These macros will only be produced, when the \Opt{hybrid} option is
-% \t`false`.
+% `false`.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererLeftBrace{%
   \markdownRendererLeftBracePrototype}%
@@ -997,402 +5299,579 @@ defaultOptions.underscores = true
 \def\markdownRendererPipe{%
   \markdownRendererPipePrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Code Span Renderer}
+%#### Code Span Renderer
 % The \mdef{markdownRendererCodeSpan} macro represents inlined code span in the
 % input text. It receives a single argument that corresponds to the inlined
 % code span.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererCodeSpan{%
   \markdownRendererCodeSpanPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Link Renderer}
+%#### 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}
 %  \begin{macrocode}
 \def\markdownRendererLink{%
   \markdownRendererLinkPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Image Renderer}
+%#### 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}
 %  \begin{macrocode}
 \def\markdownRendererImage{%
   \markdownRendererImagePrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Content Block Renderers}\label{sec:texcontentblockrenderers}
+%#### Content Block Renderers
+% \label{sec: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}
 %  \begin{macrocode}
 \def\markdownRendererContentBlock{%
   \markdownRendererContentBlockPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \mdef{markdownRendererContentBlockOnlineImage} macro represents an
 % iA\,Writer online image content block. The macro receives the same arguments
 % as \m{markdownRendererContentBlock}.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererContentBlockOnlineImage{%
   \markdownRendererContentBlockOnlineImagePrototype}%
 %    \end{macrocode}
+% \par
+% \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 \t`markdown-languages.json` file found
+% by its filename extension $s$. If any `markdown-languages.json` file found
 % by \pkg{kpathsea}\footnote{Local files take precedence. Filenames other
-% than \t`markdown-languages.json` may be specified using the
-% \t`contentBlocksLanguageMap` Lua option.} contains a record $(k, v)$, then a
+% 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$\t`:lower()`${}=k$ is considered to be in a known programming language $v$.
+% 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 \t`markdown-languages.json` file
+% 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 \t`Languages.json`
-% file provided by \cite{sotkov17} is a good starting point.
+% exist other creative uses beside syntax highlighting. The `Languages.json`
+% file provided by @sotkov17 is a good starting point.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererContentBlockCode{%
   \markdownRendererContentBlockCodePrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Bullet List Renderers}
+%#### 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}
 %  \begin{macrocode}
 \def\markdownRendererUlBegin{%
   \markdownRendererUlBeginPrototype}%
 %    \end{macrocode}
+% \par
+% \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 \t`false`. The macro receives no arguments.
+% is `false`. The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererUlBeginTight{%
   \markdownRendererUlBeginTightPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \mdef{markdownRendererUlItem} macro represents an item in a bulleted
 % list. The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererUlItem{%
   \markdownRendererUlItemPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \mdef{markdownRendererUlItemEnd} macro represents the end of an item in a
 % bulleted list. The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererUlItemEnd{%
   \markdownRendererUlItemEndPrototype}%
 %    \end{macrocode}
+% \par
+% \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}
 %  \begin{macrocode}
 \def\markdownRendererUlEnd{%
   \markdownRendererUlEndPrototype}%
 %    \end{macrocode}
+% \par
+% \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
-% \t`false`. The macro receives no arguments.
+% `false`. The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererUlEndTight{%
   \markdownRendererUlEndTightPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Ordered List Renderers}
+%#### 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). The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererOlBegin{%
   \markdownRendererOlBeginPrototype}%
 %    \end{macrocode}
+% \par
+% \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 \t`false`. The macro receives no arguments.
+% option is `false`. The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererOlBeginTight{%
   \markdownRendererOlBeginTightPrototype}%
 %    \end{macrocode}
+% \par
+% \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
-% \t`false`.  The macro receives no arguments.
+% `false`.  The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererOlItem{%
   \markdownRendererOlItemPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \mdef{markdownRendererOlItemEnd} macro represents the end of an item in
 % an ordered list. The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererOlItemEnd{%
   \markdownRendererOlItemEndPrototype}%
 %    \end{macrocode}
+% \par
+% \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 \t`true`.  The macro receives no arguments.
+% option is `true`.  The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererOlItemWithNumber{%
   \markdownRendererOlItemWithNumberPrototype}%
 %    \end{macrocode}
+% \par
+% \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). The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererOlEnd{%
   \markdownRendererOlEndPrototype}%
 %    \end{macrocode}
+% \par
+% \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
-% \t`false`. The macro receives no arguments.
+% `false`. The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererOlEndTight{%
   \markdownRendererOlEndTightPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Definition List Renderers}
+%#### Definition List Renderers
 % The following macros are only produces, when the \Opt{definitionLists} option
-% is \t`true`.
+% is `true`.
 %
 % 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}
 %  \begin{macrocode}
 \def\markdownRendererDlBegin{%
   \markdownRendererDlBeginPrototype}%
 %    \end{macrocode}
+% \par
+% \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 \t`false`. The macro receives no arguments.
+% \Opt{tightLists} option is `false`. The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererDlBeginTight{%
   \markdownRendererDlBeginTightPrototype}%
 %    \end{macrocode}
+% \par
+% \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}
 %  \begin{macrocode}
 \def\markdownRendererDlItem{%
   \markdownRendererDlItemPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \mdef{markdownRendererDlItemEnd} macro represents the end of a list of
 % definitions for a single term.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererDlItemEnd{%
   \markdownRendererDlItemEndPrototype}%
 %    \end{macrocode}
+% \par
+% \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}
 %  \begin{macrocode}
 \def\markdownRendererDlDefinitionBegin{%
   \markdownRendererDlDefinitionBeginPrototype}%
 %    \end{macrocode}
+% \par
+% \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}
 %  \begin{macrocode}
 \def\markdownRendererDlDefinitionEnd{%
   \markdownRendererDlDefinitionEndPrototype}%
 %    \end{macrocode}
+% \par
+% \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}
 %  \begin{macrocode}
 \def\markdownRendererDlEnd{%
   \markdownRendererDlEndPrototype}%
 %    \end{macrocode}
+% \par
+% \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 \t`false`. The macro receives no arguments.
+% option is `false`. The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererDlEndTight{%
   \markdownRendererDlEndTightPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Emphasis Renderers}
+%#### 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}
 %  \begin{macrocode}
 \def\markdownRendererEmphasis{%
   \markdownRendererEmphasisPrototype}%
 %    \end{macrocode}
+% \par
+% \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}
 %  \begin{macrocode}
 \def\markdownRendererStrongEmphasis{%
   \markdownRendererStrongEmphasisPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Block Quote Renderers}
+%#### Block Quote Renderers
 % The \mdef{markdownRendererBlockQuoteBegin} macro represents the beginning of
 % a block quote. The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererBlockQuoteBegin{%
   \markdownRendererBlockQuoteBeginPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \mdef{markdownRendererBlockQuoteEnd} macro represents the end of a block
 % quote. The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererBlockQuoteEnd{%
   \markdownRendererBlockQuoteEndPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Code Block Renderers}
+%#### 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}
 %  \begin{macrocode}
 \def\markdownRendererInputVerbatim{%
   \markdownRendererInputVerbatimPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \mdef{markdownRendererInputFencedCode} macro represents a fenced code
 % block. This macro will only be produced, when the \Opt{fencedCode} option is
-% \t`true`. The macro receives two arguments that correspond to the filename of
+% `true`. 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}
 %  \begin{macrocode}
 \def\markdownRendererInputFencedCode{%
   \markdownRendererInputFencedCodePrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Heading Renderers}
+%#### 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}
 %  \begin{macrocode}
 \def\markdownRendererHeadingOne{%
   \markdownRendererHeadingOnePrototype}%
 %    \end{macrocode}
+% \par
+% \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}
 %  \begin{macrocode}
 \def\markdownRendererHeadingTwo{%
   \markdownRendererHeadingTwoPrototype}%
 %    \end{macrocode}
+% \par
+% \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}
 %  \begin{macrocode}
 \def\markdownRendererHeadingThree{%
   \markdownRendererHeadingThreePrototype}%
 %    \end{macrocode}
+% \par
+% \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}
 %  \begin{macrocode}
 \def\markdownRendererHeadingFour{%
   \markdownRendererHeadingFourPrototype}%
 %    \end{macrocode}
+% \par
+% \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}
 %  \begin{macrocode}
 \def\markdownRendererHeadingFive{%
   \markdownRendererHeadingFivePrototype}%
 %    \end{macrocode}
+% \par
+% \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}
 %  \begin{macrocode}
 \def\markdownRendererHeadingSix{%
   \markdownRendererHeadingSixPrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Horizontal Rule Renderer}
+%#### Horizontal Rule Renderer
 % The \mdef{markdownRendererHorizontalRule} macro represents a horizontal rule.
 % The macro receives no arguments.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererHorizontalRule{%
   \markdownRendererHorizontalRulePrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Footnote Renderer}
+%#### Footnote Renderer
 % The \mdef{markdownRendererFootnote} macro represents a footnote. This macro
-% will only be produced, when the \Opt{footnotes} option is \t`true`.  The
+% will only be produced, when the \Opt{footnotes} option is `true`.  The
 % macro receives a single argument that corresponds to the footnote text.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererFootnote{%
   \markdownRendererFootnotePrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Parenthesized Citations Renderer}
+%#### 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 \t`true`. The macro receives the parameter
-% \t`\textbraceleft`\meta{number of citations}\t`\textbraceright` followed by
-% \meta{suppress author}\t`\textbraceleft`\meta{prenote}\t`\textbraceright^^A
-% \textbraceleft`\meta{postnote}\t`\textbraceright\textbraceleft`\meta{name}^^A
-% \t`\textbraceright` repeated \meta{number of citations} times. The
-% \meta{suppress author} parameter is either the token \t`-`, when the author's
-% name is to be suppressed, or \t`+` otherwise.
+% \Opt{citations} option is `true`. 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}
 %  \begin{macrocode}
 \def\markdownRendererCite{%
   \markdownRendererCitePrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Text Citations Renderer}
+%#### 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 \t`true`. The macro receives parameters in the same 
+% \Opt{citations} option is `true`. The macro receives parameters in the same 
 % format as the \m{markdownRendererCite} macro.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererTextCite{%
   \markdownRendererTextCitePrototype}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Token Renderer Prototypes}\label{sec:texrendererprototypes}
+%### Token Renderer Prototypes
+% \label{sec:texrendererprototypes}
 % The following \TeX{} macros provide definitions for the token renderers (see
 % Section \ref{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
 % \ref{sec:lateximplementation} and \ref{sec:contextimplementation}).
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererInterblockSeparatorPrototype{}%
 \def\markdownRendererLineBreakPrototype{}%
@@ -1453,50 +5932,71 @@ defaultOptions.underscores = true
 \def\markdownRendererCitePrototype#1{}%
 \def\markdownRendererTextCitePrototype#1{}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Logging Facilities}
+%### Logging Facilities
 % The \mdef{markdownInfo}, \mdef{markdownWarning}, and
 % \mdef{markdownError} macros provide access to logging to the rest of
 % the macros. Their first argument specifies the text of the info, warning, or
 % error message.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownInfo#1{}%
 \def\markdownWarning#1{}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
+%
 % The \m{markdownError} macro receives a second argument that provides a help
 % text suggesting a remedy to the error.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownError#1#2{}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
+%
 % You may redefine these macros to redirect and process the info, warning, and
 % error messages.
 %
-% \subsubsection{Miscellanea}
+%### 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 \emph{other}.
+% these to *other*.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \let\markdownMakeOther\relax
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \mdef{markdownReadAndConvert} macro implements the \m{markdownBegin}
 % macro. The first argument specifies the token sequence that will terminate
 % the markdown input (\m{markdownEnd} in the instance of the \m{markdownBegin}
 % macro) when the plain \TeX{} special characters have had their category
-% changed to \emph{other}. The second argument specifies the token sequence
+% 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}
-% Locally swap the category code of the backslash symbol (\t`\textbackslash`)
-% with the pipe symbol (\t`|`). This is required in order that all the special
-% symbols in the first argument of the \t`markdownReadAndConvert` macro have
-% the category code \emph{other}.
+% \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{%
@@ -1504,24 +6004,27 @@ defaultOptions.underscores = true
                            {|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 \ref{sec:directlua}), the first argument may not contain the
-% string \t`]]` (regardless of the category code of the bracket symbol (\t`]`)).
+% 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:
 % \begin{itemize}
-%   \item\t`0` -- Shell escape via the 18 output file stream
-%   \item\t`1` -- Shell escape via the Lua \luam{os.execute} method
-%   \item\t`2` -- Direct Lua access
+%   \item`0` -- Shell escape via the 18 output file stream
+%   \item`1` -- Shell escape via the Lua \luam{os.execute} method
+%   \item`2` -- Direct Lua access
 % \end{itemize}
 % 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 \m{markdownMode} after the implementation has been
 % loaded is undefined.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \ifx\markdownMode\undefined
   \ifx\directlua\undefined
@@ -1531,9 +6034,13 @@ defaultOptions.underscores = true
   \fi
 \fi
 %    \end{macrocode}
-% 
+% \par
+% \begin{markdown}
+%
 % The following macros are no longer a part of the plain \TeX{} interface and
 % are only defined for backwards compatibility:
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownLuaRegisterIBCallback#1{\relax}%
 \def\markdownLuaUnregisterIBCallback#1{\relax}%
@@ -1541,7 +6048,34 @@ defaultOptions.underscores = true
 % \iffalse
 %</tex>
 %<*latex>
-% \fi\subsection{\LaTeX{} Interface}\label{sec:latexinterface}
+% \fi
+% \par
+% \begin{markdown}
+%
+% \LaTeX{} Interface
+%-------------------
+% \label{sec:latexinterface}
+%
+% \iffalse
+%</latex>
+%<*manual>
+
+LaTeX
+-----
+
+The LaTeX macro package provides additional syntactic sugar on top of the plain
+TeX macro package and provides sane default definitions of the token renderers.
+
+<!-- TODO -->
+
+### Interfaces
+
+<!-- TODO -->
+
+%</manual>
+%<*latex>
+% \fi
+%
 % The \LaTeX{} interface provides \LaTeX{} environments for the typesetting of
 % markdown input from within \LaTeX{}, facilities for setting Lua interface
 % options (see Section \ref{sec:luaoptions}) used during the conversion from
@@ -1549,19 +6083,25 @@ defaultOptions.underscores = true
 % are rendered. The rest of the interface is inherited from the plain \TeX{}
 % interface (see Section \ref{sec:texinterface}).
 %
-% The \LaTeX{} interface is implemented by the \t`markdown.sty` file, which
+% 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=\\\{\}]
 % \textbackslash{}usepackage[\textrm{\meta{options}}]\{markdown\}
 % \end{Verbatim}
+% \begin{markdown}
 % where \meta{options} are the \LaTeX{} interface options (see Section
 % \ref{sec:latexoptions}). Note that \meta{options} inside the \m{usepackage}
-% macro may not set the \t`markdownRenderers` (see Section
-% \ref{sec:latexrenderers}) and \t`markdownRendererPrototypes` (see Section
+% macro may not set the `markdownRenderers` (see Section
+% \ref{sec:latexrenderers}) and `markdownRendererPrototypes` (see Section
 % \ref{sec:latexrendererprototypes}) keys. This limitation is due to the way
 % \Hologo{LaTeX2e} parses package options.
 %
-% \subsubsection{Typesetting Markdown}
+% \end{markdown}
+% \par
+% \begin{markdown}
+%
+%### Typesetting Markdown
 % The interface exposes the \envmdef{markdown} and \envmdef{markdown*}
 % \LaTeX{} environments, and redefines the \m{markdownInput} command.
 %
@@ -1569,11 +6109,15 @@ defaultOptions.underscores = true
 % typeset markdown document fragments. The starred version of the
 % \envm{markdown} environment accepts \LaTeX{} interface options (see
 % Section \ref{sec:latexoptions}) as its only argument. These options will
-% only influnce this markdown document fragment.
+% 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 \m{markdown} macro and append your own
 % code to the \m{endmarkdown} macro to produce special effects before and after
 % the \envm{markdown} \LaTeX{} environment (and likewise for the starred
@@ -1585,7 +6129,7 @@ defaultOptions.underscores = true
 %
 % The following example \LaTeX{} code showcases the usage of the
 % \envm{markdown} and \envm{markdown*} environments:
-% \begin{Verbatim}
+% ``` tex
 % \documentclass{article}            \documentclass{article}
 % \usepackage{markdown}              \usepackage{markdown}
 % \begin{document}                   \begin{document}
@@ -1595,7 +6139,7 @@ defaultOptions.underscores = true
 % \end{markdown}                     \end{markdown*}
 % % ...                              % ...
 % \end{document}                     \end{document}
-% \end{Verbatim}
+% ```````
 %
 % The \m{markdownInput} macro accepts a single mandatory parameter containing
 % the filename of a markdown document and expands to the result of the
@@ -1607,7 +6151,7 @@ defaultOptions.underscores = true
 %
 % The following example \LaTeX{} code showcases the usage of the
 % \m{markdownInput} macro:
-% \begin{Verbatim}
+% ``` tex
 % \documentclass{article}
 % \usepackage{markdown}
 % \begin{document}
@@ -1615,13 +6159,26 @@ defaultOptions.underscores = true
 % \markdownInput[smartEllipses]{hello.md}
 % % ...
 % \end{document}
-% \end{Verbatim}
+% ```````
+%
+%### Options
+% \label{sec:latexoptions}
+%
+% \iffalse
+%</latex>
+%<*manual>
+
+### Options
+
+<!-- TODO -->
+
+%</manual>
+%<*latex>
+% \fi
 %
-% \subsubsection{Options}\label{sec:latexoptions}
 % The \LaTeX{} options are represented by a comma-delimited list of
-% \meta{\meta{key}=\meta{value}} pairs. For boolean options, the
-% \meta{=\meta{value}} part is optional, and \meta{\meta{key}} will be
-% interpreted as \meta{\meta{key}=true}.
+% \meta{key}`=`\meta{value} pairs. For boolean options, the `=`\meta{value}
+% part is optional, and \meta{key} will be interpreted as \meta{key}`=true`.
 %
 % The \LaTeX{} options map directly to the options recognized by the plain
 % \TeX{} interface (see Section \ref{sec:texoptions}) and to the markdown token
@@ -1632,14 +6189,20 @@ defaultOptions.underscores = true
 % Section \ref{sec:latexinterface}), when using the \envm{markdown*} \LaTeX{}
 % environment, or via the \mdef{markdownSetup} macro.  The \m{markdownSetup}
 % macro receives the options to set up as its only argument.
+%
+% \markdownEnd
 %  \begin{macrocode}
 \newcommand\markdownSetup[1]{%
   \setkeys{markdownOptions}{#1}}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Plain \TeX{} Interface Options}
+%#### Plain \TeX{} Interface Options
 % The following options map directly to the option macros exposed by the plain
 % \TeX{} interface (see Section \ref{sec:texoptions}).
+%
+% \end{markdown}
 %  \begin{macrocode}
 \define@key{markdownOptions}{helperScriptFileName}{%
   \def\markdownOptionHelperScriptFileName{#1}}%
@@ -1695,24 +6258,44 @@ defaultOptions.underscores = true
   \def\markdownOptionTightLists{#1}}%
 \define@key{markdownOptions}{underscores}[true]{%
   \def\markdownOptionUnderscores{#1}}%
+\define@key{markdownOptions}{stripPercentSigns}[true]{%
+  \def\markdownOptionStripPercentSigns{#1}}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The following example \LaTeX{} code showcases a possible configuration of
 % plain \TeX{} interface options \m{markdownOptionHybrid},
 % \m{markdownOptionSmartEllipses}, and \m{markdownOptionCacheDir}.
-% \begin{Verbatim}
+% ``` tex
 % \markdownSetup{
 %   hybrid,
 %   smartEllipses,
 %   cacheDir = /tmp,
 % }
-% \end{Verbatim}
+% ```````
 %
-% \paragraph{Plain \TeX{} Markdown Token Renderers}\label{sec:latexrenderers}
-% The \LaTeX{} interface recognizes an option with the \t`renderers` key,
+%#### Plain \TeX{} Markdown Token Renderers
+% \label{sec:latexrenderers}
+%
+% \iffalse
+%</latex>
+%<*manual>
+
+### Token renderers
+
+<!-- TODO -->
+
+%</manual>
+%<*latex>
+% \fi
+%
+% 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
 % \ref{sec:texrenderersuser}).
+%
+% \end{markdown}
 %  \begin{macrocode}
 \define@key{markdownRenderers}{interblockSeparator}{%
   \renewcommand\markdownRendererInterblockSeparator{#1}}%
@@ -1831,25 +6414,29 @@ defaultOptions.underscores = true
 \define@key{markdownRenderers}{textCite}{%
   \renewcommand\markdownRendererTextCite[1]{#1}}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The following example \LaTeX{} code showcases a possible configuration of the
 % \m{markdownRendererLink} and \m{markdownRendererEmphasis} markdown token
 % renderers.
-% \begin{Verbatim}
+% ``` tex
 % \markdownSetup{
 %   renderers = {
 %     link = {#4},                   % Render links as the link title.
 %     emphasis = {\emph{#1}},    % Render emphasized text via `\emph`.
 %   }
 % }
-% \end{Verbatim}
+% ```````
 %
-% \paragraph{Plain \TeX{} Markdown Token Renderer Prototypes}
+%#### Plain \TeX{} Markdown Token Renderer Prototypes
 % \label{sec:latexrendererprototypes}
-% The \LaTeX{} interface recognizes an option with the \t`rendererPrototypes`
+% 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 \ref{sec:texrendererprototypes}).
+%
+% \end{markdown}
 %  \begin{macrocode}
 \define@key{markdownRendererPrototypes}{interblockSeparator}{%
   \renewcommand\markdownRendererInterblockSeparatorPrototype{#1}}%
@@ -1968,47 +6555,89 @@ defaultOptions.underscores = true
 \define@key{markdownRendererPrototypes}{textCite}{%
   \renewcommand\markdownRendererTextCitePrototype[1]{#1}}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The following example \LaTeX{} code showcases a possible configuration of the
 % \m{markdownRendererImagePrototype} and \m{markdownRendererCodeSpanPrototype}
 % markdown token renderer prototypes.
-% \begin{Verbatim}
+% ``` tex
 % \markdownSetup{
 %   rendererPrototypes = {
 %     image = {\includegraphics{#2}},
 %     codeSpan = {\texttt{#1}},    % Render inline code via `\texttt`.
 %   }
 % }
-% \end{Verbatim}
+% ```````
 %
 % \iffalse
 %</latex>
 %<*context>
-% \fi\subsection{\Hologo{ConTeXt} Interface}\label{sec:contextinterface}
+% \fi
+% \Hologo{ConTeXt} Interface
+%---------------------------
+% \label{sec:contextinterface}
+%
+% \iffalse
+%</context>
+%<*manual>
+
+ConTeXt
+-------
+
+The ConTeXt macro package provides additional syntactic sugar on top of the
+plain TeX macro package and provides sane default definitions of the token
+renderers.
+
+### Interfaces
+
+<!-- TODO -->
+
+### Options
+
+<!-- TODO -->
+
+### Token renderers
+
+<!-- TODO -->
+
+%</manual>
+%<*context>
+% \fi
+%
 % The \Hologo{ConTeXt} interface provides a start-stop macro pair for the
 % typesetting of markdown input from within \Hologo{ConTeXt}. The rest of the
 % interface is inherited from the plain \TeX{} interface (see Section
 % \ref{sec:texinterface}).
+%
+% \end{markdown}
 %  \begin{macrocode}
 \writestatus{loading}{ConTeXt User Module / markdown}%
 \unprotect
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \Hologo{ConTeXt} interface is implemented by the
-% \t`t-markdown.tex` \Hologo{ConTeXt} module file that can be loaded as follows:
-% \begin{Verbatim}
+% `t-markdown.tex` \Hologo{ConTeXt} module file that can be loaded as follows:
+% ``` tex
 % \usemodule[t][markdown]
-% \end{Verbatim}
-% It is expected that the special plain \TeX{} characters have the expected
-% category codes, when \m{input}ting the file.
+% ```````
+% \noindent It is expected that the special plain \TeX{} characters have the
+% expected category codes, when \m{input}ting the file.
 %
-% \subsubsection{Typesetting Markdown}
+%### Typesetting Markdown
 % The interface exposes the \mdef{startmarkdown} and \mdef{stopmarkdown} macro
 % pair for the typesetting of a markdown document fragment.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \let\startmarkdown\relax
 \let\stopmarkdown\relax
 %    \end{macrocode}
+% \par
+% \begin{markdown}
+%
 % You may prepend your own code to the \m{startmarkdown} macro and redefine the
 % \m{stopmarkdown} macro to produce special effects before and after the
 % markdown block.
@@ -2019,24 +6648,30 @@ defaultOptions.underscores = true
 %
 % The following example \Hologo{ConTeXt} code showcases the usage of the
 % \m{startmarkdown} and \m{stopmarkdown} macros:
-% \begin{Verbatim}
+% ``` tex
 % \usemodule[t][markdown]
 % \starttext
 % \startmarkdown
 % _Hello_ **world** ...
 % \stopmarkdown
 % \stoptext
-% \end{Verbatim}
-% 
-% \section{Technical Documentation}\label{sec:implementation}
-% This part of the manual describes the implementation of the interfaces
+% ```````
+%
+% Implementation
+%===============
+% \label{sec:implementation}
+% This part of the documentation describes the implementation of the interfaces
 % exposed by the package (see Section \ref{sec:interfaces}) and is aimed at the
 % developers of the package, as well as the curious users.
 %
 % \iffalse
 %</context>
 %<*lua>
-% \fi\subsection{Lua Implementation}\label{sec:luaimplementation}
+% \fi
+%
+% Lua Implementation
+%-------------------
+% \label{sec:luaimplementation}
 % The Lua implementation implements \luamdef{writer} and \luamdef{reader}
 % objects that provide the conversion from markdown to plain \TeX{}.
 %
@@ -2046,6 +6681,7 @@ defaultOptions.underscores = true
 % were hidden behind the converter functions exposed by the Lua interface (see
 % Section \ref{sec:luainterface}).
 %
+% \end{markdown}
 %  \begin{macrocode}
 local upper, gsub, format, length =
   string.upper, string.gsub, string.format, string.len
@@ -2054,30 +6690,42 @@ 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}
-% 
-% \subsubsection{Utility Functions}
+% \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
-% \t`util` object. The functions were originally located in the
-% \t`lunamark/util.lua` file in the Lunamark Lua module.
+% `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}
-% 
-% The \luamdef{util.err} method prints an error message \t`msg` and exits.
-% If \t`exit_code` is provided, it specifies the exit code.  Otherwise, the
+% \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 \t`string` and
-% \t`salt`, adds the \t`suffix` and looks into the directory \t`dir`, whether a
+% 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
-% \t`transform(string)` as its content. The filename is then returned.
+% `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 ""))
@@ -2095,9 +6743,13 @@ function util.cache(dir, string, salt, transform, suffix)
   return name
 end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% The \luamdef{util.table_copy} method creates a shallow copy of a table \t`t`
+% 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 = { }
@@ -2105,11 +6757,15 @@ function util.table_copy(t)
   return setmetatable(u, getmetatable(t))
 end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% The \luamdef{util.expand_tabs_in_line} expands tabs in string \t`s`. If
-% \t`tabstop` is specified, it is used as the tab stop width. Otherwise,
+% 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 \cite[Chapter~21]{ierusalimschy13}.
+% expansion algorithm from @ierusalimschy13 [Chapter 21].
+%
+% \end{markdown}
 %  \begin{macrocode}
 function util.expand_tabs_in_line(s, tabstop)
   local tab = tabstop or 4
@@ -2121,11 +6777,15 @@ function util.expand_tabs_in_line(s, tabstop)
           end))
 end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% The \luamdef{util.walk} method walks a rope \t`t`, applying a function \t`f`
+% 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)
@@ -2150,9 +6810,13 @@ function util.walk(t, f)
   end
 end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% The \luamdef{util.flatten} method flattens an array \t`ary` that does not
+% 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 = {}
@@ -2168,10 +6832,14 @@ function util.flatten(ary)
   return new
 end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% The \luamdef{util.rope_to_string} method converts a rope \t`rope` to a
+% 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 \luam{util.walk} method.
+%
+% \end{markdown}
 %  \begin{macrocode}
 function util.rope_to_string(rope)
   local buffer = {}
@@ -2179,9 +6847,13 @@ function util.rope_to_string(rope)
   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 \luam{util.walk} method.
+%
+% \end{markdown}
 %  \begin{macrocode}
 function util.rope_last(rope)
   if #rope == 0 then
@@ -2196,10 +6868,14 @@ function util.rope_last(rope)
   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`$.
 %
-% Given an array \t`ary` and a string \t`x`, the \luamdef{util.intersperse}
-% method returns an array \t`new`, such that \t`ary[i] == new[2*(i-1)+1]` and
-% \t`new[2*i] == x` for all $1\leq\t`i`\leq\t`\#ary`$.
+% \end{markdown}
 %  \begin{macrocode}
 function util.intersperse(ary, x)
   local new = {}
@@ -2214,10 +6890,14 @@ function util.intersperse(ary, x)
   return new
 end
 %    \end{macrocode}
-% 
-% Given an array \t`ary` and a function \t`f`, the \luamdef{util.map} method
-% returns an array \t`new`, such that \t`new[i] == f(ary[i])` for all
-% $1\leq\t`i`\leq\t`\#ary`$.
+% \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 = {}
@@ -2227,39 +6907,48 @@ function util.map(ary, f)
   return new
 end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% Given a table \t`char_escapes` mapping escapable characters to escaped
-% strings and optionally a table \t`string_escapes` mapping escapable strings
+% 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 \t`string.gsub`
+%
+% 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}
-% Create an \pkg{LPeg} capture \t`escapable` that produces the escaped string
+% \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}
-% If \t`string_escapes` is provided, turn \t`escapable` into the
-% {\catcode`\_=8\[
-%   \sum_{(\t`k`,\t`v`)\in\t`string\_escapes`}\t`P(k) / v` + \t`escapable`
-% \]}^^A
-% capture that replaces any occurance of the string \t`k` with the string
-% \t`v` for each $(\t`k`, \t`v`)\in\t`string\_escapes`$. Note that the pattern
+% \begin{markdown}
+% If `string_escapes` is provided, turn `escapable` into the
+% $$\sum_{(`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
@@ -2267,22 +6956,30 @@ function util.escaper(char_escapes, string_escapes)
     end
   end
 %    \end{macrocode}
-% Create an \pkg{LPeg} capture \t`escape_string` that captures anything
-% \t`escapable` does and matches any other unmatched characters.
+% \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}
-% Return a function that matches the input string \t`s` against the
-% \t`escape_string` capture.
+% \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 \t`dir` and a filename \t`file` and returns it.
+% name `dir` and a filename `file` and returns it.
+%
+% \end{markdown}
 %  \begin{macrocode}
 function util.pathname(dir, file)
   if #dir == 0 then
@@ -2292,11 +6989,16 @@ function util.pathname(dir, file)
   end
 end
 %    \end{macrocode}
-% \subsubsection{\textsc{html} Entities}
+% \par
+% \begin{markdown}
+%
+%### \textsc{html} Entities
 % This section documents the \textsc{html} entities recognized by the
-% markdown reader.  These functions are encapsulated in the \t`entities`
+% markdown reader.  These functions are encapsulated in the `entities`
 % object. The functions were originally located in the
-% \t`lunamark/entities.lua` file in the Lunamark Lua module.
+% `lunamark/entities.lua` file in the Lunamark Lua module.
+%
+% \end{markdown}
 %  \begin{macrocode}
 local entities = {}
 
@@ -2552,143 +7254,216 @@ local character_entities = {
   ["diams"] = 0x2666,
 }
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% Given a string \t`s` of decimal digits, the \luamdef{entities.dec_entity}
+% Given a string `s` of decimal digits, the \luamdef{entities.dec_entity}
 % returns the corresponding \textsc{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 \t`s` of hexadecimal digits, the
+% Given a string `s` of hexadecimal digits, the
 % \luamdef{entities.hex_entity} returns the corresponding
 % \textsc{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 \t`s` (like \t`ouml`), the
+% Given a character entity name `s` (like `ouml`), the
 % \luamdef{entities.char_entity} returns the corresponding
 % \textsc{utf}8-encoded Unicode codepoint.
+%
+% \end{markdown}
 %  \begin{macrocode}
 function entities.char_entity(s)
   local n = character_entities[s]
   return unicode.utf8.char(n)
 end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Plain \TeX{} Writer}\label{sec:texwriter}
+%### Plain \TeX{} Writer
+% \label{sec:texwriter}
 % This section documents the \luam{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
-% \t`lunamark/writer/generic.lua`, \t`lunamark/writer/tex.lua`, and
-% \t`lunamark/writer/latex.lua` files in the Lunamark Lua module.
+% `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
 % \ref{sec:luainterface}), the \luam{writer} object is exported, so that the
 % curious user could easily tinker with the methods of the objects produced by
 % the \luam{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
-% \ref{sec:luaoptions}) \t`options`. When \t`options` are unspecified, it is
+% \ref{sec:luaoptions}) `options`. When `options` are unspecified, it is
 % assumed that an empty table was passed to the method.
 %
 % The objects produced by the \luam{writer.new} method expose instance methods
 % and variables of their own. As a convention, I will refer to these
-% \meta{member}s as \t`writer->`\meta{member}.
+% \meta{member}s as `writer->`\meta{member}.
+%
+% \end{markdown}
 %  \begin{macrocode}
 function M.writer.new(options)
   local self = {}
   options = options or {}
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% Make the \t`options` table inherit from the \luam{defaultOptions} table.
+% Make the `options` table inherit from the \luam{defaultOptions} table.
+%
+% \end{markdown}
 %  \begin{macrocode}
   setmetatable(options, { __index = function (_, key)
     return defaultOptions[key] 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 \t`s` to the output format.
+% 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 \t`s` to the output format.
+% input paragraph `s` to the output format.
+%
+% \end{markdown}
 %  \begin{macrocode}
   function self.paragraph(s)
     return s
   end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define \luamdef{writer->pack} as a function that will take the filename
-% \t`name` of the output file prepared by the reader and transform it to the
+% `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]]
+    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}
   self.interblocksep = "\\markdownRendererInterblockSeparator\n{}"
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define \luamdef{writer->eof} as the end of file marker in the output format.
+%
+% \end{markdown}
 %  \begin{macrocode}
   self.eof = [[\relax]]
 %    \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->hrule} as the output format of a horizontal rule.
+%
+% \end{markdown}
 %  \begin{macrocode}
   self.hrule = "\\markdownRendererHorizontalRule{}"
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define a table \luamdef{escaped_chars} containing the mapping from special
-% plain \TeX{} characters (including the active pipe character (\t`|`) of
+% plain \TeX{} characters (including the active pipe character (`|`) of
 % \Hologo{ConTeXt}) to their escaped variants. Define tables
 % \luamdef{escaped_minimal_chars} and \luamdef{escaped_minimal_strings}
 % containing the mapping from special plain characters and character strings
 % that need to be escaped even in content that will not be typeset.
+%
+% \end{markdown}
 %  \begin{macrocode}
   local escaped_chars = {
      ["{"] = "\\markdownRendererLeftBrace{}",
@@ -2720,22 +7495,31 @@ function M.writer.new(options)
      ["^^"] = "\\markdownRendererCircumflex\\markdownRendererCircumflex ",
    }
 %    \end{macrocode}
+% \par
+% \begin{markdown}
+%
 % Use the \luam{escaped_chars} table to create an escaper function
 % \luamdef{escape} and the \luam{escaped_minimal_chars} and
 % \luam{escaped_minimal_strings} tables to create an escaper function
 % \luamdef{escape_minimal}.
+%
+% \end{markdown}
 %  \begin{macrocode}
   local escape = util.escaper(escaped_chars)
   local escape_citation = util.escaper(escaped_citation_chars,
     escaped_minimal_strings)
   local escape_uri = util.escaper(escaped_uri_chars, escaped_minimal_strings)
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define \luamdef{writer->string} as a function that will transform an input
-% plain text span \t`s` to the output format and \luamdef{writer->uri} as a
-% function that will transform an input \acro{uri} \t`u` to the output format.
-% If the \Opt{hybrid} option is \t`true`, use identity functions. Otherwise,
+% 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 `true`, use identity functions. Otherwise,
 % use the \luam{escape} and \luam{escape_minimal} functions.
+%
+% \end{markdown}
 %  \begin{macrocode}
   if options.hybrid then
     self.string = function(s) return s end
@@ -2747,18 +7531,26 @@ function M.writer.new(options)
     self.uri = escape_uri
   end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define \luamdef{writer->code} as a function that will transform an input
-% inlined code span \t`s` to the output format.
+% inlined code span `s` to the output format.
+%
+% \end{markdown}
 %  \begin{macrocode}
   function self.code(s)
     return {"\\markdownRendererCodeSpan{",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 \t`lab` corresponds to the label,
-% \t`src` to \acro{uri}, and \t`tit` to the title of the link.
+% 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,"}",
@@ -2767,10 +7559,14 @@ function M.writer.new(options)
                           "{",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 \t`lab` corresponds to the label, \t`src`
-% to the \acro{url}, and \t`tit` to the title of the image.
+% 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,"}",
@@ -2779,21 +7575,25 @@ function M.writer.new(options)
                            "{",self.string(tit or ""),"}"}
   end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \luamdef{languages_json} table maps programming language filename
 % extensions to fence infostrings. All \luam{options.contentBlocksLanguageMap}
 % files located by \pkg{kpathsea} are loaded into a chain of tables.
 % \luam{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 kpse = require('kpse')
-  kpse.set_program_name('luatex')
+  local kpse = require("kpse")
+  kpse.set_program_name("luatex")
   local base, prev, curr
   for _, file in ipairs{kpse.lookup(options.contentBlocksLanguageMap,
                                     { all=true })} do
-    json = assert(io.open(file, "r")):read("*all")
-                                     :gsub('("[^\n]-"):','[%1]=')
+    json = io.open(file, "r"):read("*all")
+                             :gsub('("[^\n]-"):','[%1]=')
     curr = (function()
       local _ENV={ json=json, load=load } -- run in sandbox
       return load("return "..json)()
@@ -2810,12 +7610,16 @@ local languages_json = (function()
   return base or {}
 end)()
 %    \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 \t`src`
-% corresponds to the \acro{uri} prefix, \t`suf` to the \acro{uri} extension,
-% \t`type` to the type of the content block (\t`localfile` or \t`onlineimage`),
-% and \t`tit` to the title of the content block.
+% 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)
     src = src.."."..suf
@@ -2839,10 +7643,14 @@ end)()
     end
   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 \t`items` is an array of the list
-% items and \t`tight` specifies, whether the list is tight or not.
+% 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}
   local function ulitem(s)
     return {"\\markdownRendererUlItem ",s,
@@ -2864,12 +7672,16 @@ end)()
     end
   end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define \luamdef{writer->ollist} as a function that will transform an input
-% ordered list to the output format, where \t`items` is an array of the list
-% items and \t`tight` specifies, whether the list is tight or not. If the
-% optional parameter \t`startnum` is present, it should be used as the number
+% 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 should be used as the number
 % of the first list item.
+%
+% \end{markdown}
 %  \begin{macrocode}
   local function olitem(s,num)
     if num ~= nil then
@@ -2900,21 +7712,29 @@ end)()
     end
   end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define \luamdef{writer->inline_html} and \luamdef{writer->display_html}
 % as functions that will transform an inline or block \textsc{html} element
-% respectively to the output format, where \t`html` is the \textsc{html}
+% respectively to the output format, where `html` is the \textsc{html}
 % input.
+%
+% \end{markdown}
 %  \begin{macrocode}
   function self.inline_html(html)  return "" end
   function self.display_html(html) return "" end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define \luamdef{writer->definitionlist} as a function that will transform an
-% input definition list to the output format, where \t`items` is an array of
-% tables, each of the form \t`\{ term = t, definitions = defs \}`, where \t`t`
-% is a term and \t`defs` is an array of definitions. \t`tight` specifies,
+% 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,"}"}
@@ -2940,53 +7760,77 @@ end)()
     end
   end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define \luamdef{writer->emphasis} as a function that will transform an
-% emphasized span \t`s` of input text to the output format.
+% 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->strong} as a function that will transform a strongly
-% emphasized span \t`s` of input text to the output format.
+% 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 \t`s` to the output format.
+% input block quote `s` to the output format.
+%
+% \end{markdown}
 %  \begin{macrocode}
   function self.blockquote(s)
     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 \t`s` to the output format.
+% input code block `s` to the output format.
+%
+% \end{markdown}
 %  \begin{macrocode}
   function self.verbatim(s)
     local name = util.cache(options.cacheDir, s, nil, nil, ".verbatim")
     return {"\\markdownRendererInputVerbatim{",name,"}"}
   end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define \luamdef{writer->codeFence} as a function that will transform an
-% input fenced code block \t`s` with the infostring \t`i` to the output
+% input fenced code block `s` with the infostring `i` to the output
 % format.
+%
+% \end{markdown}
 %  \begin{macrocode}
   function self.fencedCode(i, s)
     local name = util.cache(options.cacheDir, s, nil, nil, ".verbatim")
     return {"\\markdownRendererInputFencedCode{",name,"}{",i,"}"}
   end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define \luamdef{writer->heading} as a function that will transform an
-% input heading \t`s` at level \t`level` to the output format.
+% input heading `s` at level `level` to the output format.
+%
+% \end{markdown}
 %  \begin{macrocode}
   function self.heading(s,level)
     local cmd
@@ -3008,28 +7852,36 @@ end)()
     return {cmd,"{",s,"}"}
   end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define \luamdef{writer->note} as a function that will transform an
-% input footnote \t`s` to the output format.
+% input footnote `s` to the output format.
+%
+% \end{markdown}
 %  \begin{macrocode}
   function self.note(s)
     return {"\\markdownRendererFootnote{",s,"}"}
   end
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Define \luamdef{writer->citations} as a function that will transform an
-% input array of citations \t`cites` to the output format. If \t`text_cites`
-% is \t`true`, the citations should be rendered in-text, when applicable.
-% The \t`cites` array contains tables with the following keys and values:
+% input array of citations `cites` to the output format. If `text_cites`
+% is `true`, the citations should be rendered in-text, when applicable.
+% The `cites` array contains tables with the following keys and values:
 % \begin{itemize}
-%   \item\t`suppress_author` -- If the value of the key is true, then the
+%   \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\t`prenote` -- The value of the key is either \t`nil` or a rope
+%   \item`prenote` -- The value of the key is either `nil` or a rope
 %     that should be inserted before the citation.
-%   \item\t`postnote` -- The value of the key is either \t`nil` or a rope
+%   \item`postnote` -- The value of the key is either `nil` or a rope
 %     that should be inserted after the citation.
-%   \item\t`name` -- The value of this key is the citation name.
+%   \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",
@@ -3044,13 +7896,23 @@ end)()
   return self
 end
 %    \end{macrocode}
-% \subsubsection{Parsers}
+% \par
+% \begin{markdown}
+%
+%### Parsers
 % The \luamdef{parsers} hash table stores \acro{peg} patterns that are
 % static and can be reused between different \luam{reader} objects.
+%
+% \end{markdown}
 %  \begin{macrocode}
 local parsers                  = {}
 %    \end{macrocode}
-% \paragraph{Basic Parsers}
+% \par
+% \begin{markdown}
+%
+%#### Basic Parsers
+%
+% \end{markdown}
 %  \begin{macrocode}
 parsers.percent                = P("%")
 parsers.at                     = P("@")
@@ -3146,7 +8008,12 @@ parsers.indented_blocks = function(bl)
          * (parsers.blankline^1 + parsers.eof) )
 end
 %    \end{macrocode}
-% \paragraph{Parsers Used for Markdown Lists}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for Markdown Lists
+%
+% \end{markdown}
 %  \begin{macrocode}
 parsers.bulletchar = C(parsers.plus + parsers.asterisk + parsers.dash)
 
@@ -3161,7 +8028,12 @@ parsers.bullet = ( parsers.bulletchar * #parsers.spacing
                                  * parsers.bulletchar * #parsers.spacing
                  )
 %    \end{macrocode}
-% \paragraph{Parsers Used for Markdown Code Spans}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for Markdown Code Spans
+%
+% \end{markdown}
 %  \begin{macrocode}
 parsers.openticks   = Cg(parsers.backtick^1, "ticks")
 
@@ -3181,7 +8053,12 @@ parsers.intickschar = (parsers.any - S(" \n\r`"))
 parsers.inticks     = parsers.openticks * parsers.space^-1
                     * C(parsers.intickschar^0) * parsers.closeticks
 %    \end{macrocode}
-% \paragraph{Parsers Used for Fenced Code Blocks}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for Fenced Code Blocks
+%
+% \end{markdown}
 %  \begin{macrocode}
 local function captures_geq_length(s,i,a,b)
   return #a >= #b and i
@@ -3226,7 +8103,12 @@ parsers.fencedline   = function(char)
                        end
 end
 %    \end{macrocode}
-% \paragraph{Parsers Used for Markdown Tags and Links}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for Markdown Tags and Links
+%
+% \end{markdown}
 %  \begin{macrocode}
 parsers.leader      = parsers.space^-3
 
@@ -3293,7 +8175,12 @@ parsers.optionaltitle
                     = parsers.spnl * parsers.title * parsers.spacechar^0
                     + Cc("")
 %    \end{macrocode}
-% \paragraph{Parsers Used for iA\,Writer Content Blocks}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for iA\,Writer Content Blocks
+%
+% \end{markdown}
 %  \begin{macrocode}
 parsers.contentblock_tail
                     = parsers.optionaltitle
@@ -3360,7 +8247,12 @@ parsers.localfilepath
                     * Cs(parsers.alphanumeric^1)
                     * Cc("localfile")
 %    \end{macrocode}
-% \paragraph{Parsers Used for Citations}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for Citations
+%
+% \end{markdown}
 %  \begin{macrocode}
 parsers.citation_name = Cs(parsers.dash^-1) * parsers.at
                       * Cs(parsers.citation_chars
@@ -3415,7 +8307,12 @@ parsers.citation_headless_body
                     * (parsers.sp * parsers.semicolon * parsers.spnl
                       * parsers.citation_body_chunk)^0
 %    \end{macrocode}
-% \paragraph{Parsers Used for Footnotes}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for Footnotes
+%
+% \end{markdown}
 %  \begin{macrocode}
 local function strip_first_char(s)
   return s:sub(2)
@@ -3424,7 +8321,12 @@ end
 parsers.RawNoteRef = #(parsers.lbracket * parsers.circumflex)
                    * parsers.tag / strip_first_char
 %    \end{macrocode}
-% \paragraph{Parsers Used for \textsc{html}}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for \textsc{html}
+%
+% \end{markdown}
 %  \begin{macrocode}
 -- case-insensitive match (we assume s is lowercase). must be single byte encoding
 parsers.keyword_exact = function(s)
@@ -3532,7 +8434,12 @@ parsers.inlinehtml  = parsers.emptyelt_any
                     + parsers.openelt_any
                     + parsers.closeelt_any
 %    \end{macrocode}
-% \paragraph{Parsers Used for \textsc{html} entities}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for \textsc{html} entities
+%
+% \end{markdown}
 %  \begin{macrocode}
 parsers.hexentity = parsers.ampersand * parsers.hash * S("Xx")
                   * C(parsers.hexdigit^1) * parsers.semicolon
@@ -3541,14 +8448,24 @@ parsers.decentity = parsers.ampersand * parsers.hash
 parsers.tagentity = parsers.ampersand * C(parsers.alphanumeric^1)
                   * parsers.semicolon
 %    \end{macrocode}
-% \paragraph{Helpers for References}
+% \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}
-% \paragraph{Inline Elements}
+% \par
+% \begin{markdown}
+%
+%#### Inline Elements
+%
+% \end{markdown}
 %  \begin{macrocode}
 parsers.Inline       = V("Inline")
 
@@ -3560,7 +8477,12 @@ end
 
 parsers.urlchar      = parsers.anyescaped - parsers.newline - parsers.more
 %    \end{macrocode}
-% \paragraph{Block Elements}
+% \par
+% \begin{markdown}
+%
+%#### Block Elements
+%
+% \end{markdown}
 %  \begin{macrocode}
 parsers.Block        = V("Block")
 
@@ -3590,7 +8512,12 @@ parsers.lineof = function(c)
              + parsers.newline^-1 * parsers.eof))
 end
 %    \end{macrocode}
-% \paragraph{Lists}
+% \par
+% \begin{markdown}
+%
+%#### Lists
+%
+% \end{markdown}
 %  \begin{macrocode}
 parsers.defstartchar = S("~:")
 parsers.defstart     = ( parsers.defstartchar * #parsers.spacing
@@ -3606,7 +8533,12 @@ parsers.defstart     = ( parsers.defstartchar * #parsers.spacing
 
 parsers.dlchunk = Cs(parsers.line * (parsers.indentedline - parsers.blankline)^0)
 %    \end{macrocode}
-% \paragraph{Headings}
+% \par
+% \begin{markdown}
+%
+%#### Headings
+%
+% \end{markdown}
 %  \begin{macrocode}
 -- parse Atx heading start and return level
 parsers.HeadingStart = #parsers.hash * C(parsers.hash^-6)
@@ -3619,12 +8551,15 @@ local function strip_atx_end(s)
   return s:gsub("[#%s]*\n$","")
 end
 %    \end{macrocode}
-% 
-% \subsubsection{Markdown Reader}\label{sec:markdownreader}
+% \par
+% \begin{markdown}
+%
+%### Markdown Reader
+% \label{sec:markdownreader}
 % This section documents the \luam{reader} object, which implements the
 % routines for parsing the markdown input. The object corresponds to the
 % markdown reader object that was located in the
-% \t`lunamark/reader/markdown.lua` file in the Lunamark Lua module.
+% `lunamark/reader/markdown.lua` file in the Lunamark Lua module.
 %
 % Although not specified in the Lua interface (see Section
 % \ref{sec:luainterface}), the \luam{reader} object is exported, so that the
@@ -3634,40 +8569,54 @@ end
 %
 % The \luamdef{reader.new} method creates and returns a new \TeX{} reader
 % object associated with the Lua interface options (see Section
-% \ref{sec:luaoptions}) \t`options` and with a writer object \t`writer`. When
-% \t`options` are unspecified, it is assumed that an empty table was passed to
+% \ref{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 \luam{reader.new} method expose instance methods
 % and variables of their own. As a convention, I will refer to these
-% \meta{member}s as \t`reader->`\meta{member}.
+% \meta{member}s as `reader->`\meta{member}.
+%
+% \end{markdown}
 %  \begin{macrocode}
 M.reader = {}
 function M.reader.new(writer, options)
   local self = {}
   options = options or {}
 %    \end{macrocode}
+% \par
+% \begin{markdown}
+%
+% Make the `options` table inherit from the \luam{defaultOptions} table.
 %
-% Make the \t`options` table inherit from the \luam{defaultOptions} table.
+% \end{markdown}
 %  \begin{macrocode}
   setmetatable(options, { __index = function (_, key)
     return defaultOptions[key] end })
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Top-Level Helper Functions}
+%#### Top-Level Helper Functions
 % Define \luamdef{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}
   local function normalize_tag(tag)
     return unicode.utf8.lower(
       gsub(util.rope_to_string(tag), "[ \n\r\t]+", " "))
   end
 %    \end{macrocode}
-% 
+% \par
+% \begin{markdown}
+%
 % Define \luamdef{expandtabs} either as an identity function, when the
-% \Opt{preserveTabs} Lua inrerface option is \t`true`, or to a function that
+% \Opt{preserveTabs} Lua inrerface option is `true`, or to a function that
 % expands tabs into spaces otherwise.
+%
+% \end{markdown}
 %  \begin{macrocode}
   local expandtabs
   if options.preserveTabs then
@@ -3682,14 +8631,23 @@ function M.reader.new(writer, options)
                  end
   end
 %    \end{macrocode}
-% 
+% \par
+% \begin{markdown}
+%
 % The \luamdef{larsers} (as in ``local \luam{parsers}'') hash table stores
-% \acro{peg} patterns that depend on the received \t`options`, which impedes
+% \acro{peg} patterns that depend on the received `options`, which impedes
 % their reuse between different \luam{reader} objects.
+%
+% \end{markdown}
 %  \begin{macrocode}
   local larsers    = {}
 %    \end{macrocode}
-% \paragraph{Top-Level Parser Functions}
+% \par
+% \begin{markdown}
+%
+%#### Top-Level Parser Functions
+%
+% \end{markdown}
 %  \begin{macrocode}
   local function create_parser(name, grammar)
     return function(str)
@@ -3738,7 +8696,12 @@ function M.reader.new(writer, options)
                       return larsers.inlines_nbsp
                     end)
 %    \end{macrocode}
-% \paragraph{Parsers Used for Markdown Lists (local)}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for Markdown Lists (local)
+%
+% \end{markdown}
 %  \begin{macrocode}
   if options.hashEnumerators then
     larsers.dig = parsers.digit + parsers.hash
@@ -3759,7 +8722,12 @@ function M.reader.new(writer, options)
                      + parsers.space * parsers.space * C(larsers.dig^1
                                      * parsers.period) * #parsers.spacing
 %    \end{macrocode}
-% \paragraph{Parsers Used for Blockquotes (local)}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for Blockquotes (local)
+%
+% \end{markdown}
 %  \begin{macrocode}
   -- strip off leading > and indents, and run through blocks
   larsers.blockquote_body = ((parsers.leader * parsers.more * parsers.space^-1)/""
@@ -3773,7 +8741,12 @@ function M.reader.new(writer, options)
                             * (parsers.blankline^0 / "")
   end
 %    \end{macrocode}
-% \paragraph{Parsers Used for Citations (local)}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for Citations (local)
+%
+% \end{markdown}
 %  \begin{macrocode}
   larsers.citations = function(text_cites, raw_cites)
       local function normalize(str)
@@ -3798,7 +8771,12 @@ function M.reader.new(writer, options)
       return writer.citations(text_cites, cites)
   end
 %    \end{macrocode}
-% \paragraph{Parsers Used for Footnotes (local)}
+% \par
+% \begin{markdown}
+%
+%#### Parsers Used for Footnotes (local)
+%
+% \end{markdown}
 %  \begin{macrocode}
   local rawnotes = {}
 
@@ -3830,7 +8808,12 @@ function M.reader.new(writer, options)
                      * (parsers.tag / parse_inlines_no_inline_note) -- no notes inside notes
                      / writer.note
 %    \end{macrocode}
-% \paragraph{Helpers for Links and References (local)}
+% \par
+% \begin{markdown}
+%
+%#### Helpers for Links and References (local)
+%
+% \end{markdown}
 %  \begin{macrocode}
   -- List of references defined in the document
   local references
@@ -3891,7 +8874,12 @@ function M.reader.new(writer, options)
     end
   end
 %    \end{macrocode}
-% \paragraph{Inline Elements (local)}
+% \par
+% \begin{markdown}
+%
+%#### Inline Elements (local)
+%
+% \end{markdown}
 %  \begin{macrocode}
   larsers.Str      = parsers.normalchar^1 / writer.string
 
@@ -4053,7 +9041,12 @@ function M.reader.new(writer, options)
                         + parsers.decentity / entities.dec_entity  / writer.string
                         + parsers.tagentity / entities.char_entity / writer.string
 %    \end{macrocode}
-% \paragraph{Block Elements (local)}
+% \par
+% \begin{markdown}
+%
+%#### Block Elements (local)
+%
+% \end{markdown}
 %  \begin{macrocode}
   larsers.ContentBlock = parsers.leader
                        * (parsers.localfilepath + parsers.onlineimageurl)
@@ -4106,7 +9099,12 @@ function M.reader.new(writer, options)
   larsers.Plain        = parsers.nonindentspace * Ct(parsers.Inline^1)
                        / writer.plain
 %    \end{macrocode}
-% \paragraph{Lists (local)}
+% \par
+% \begin{markdown}
+%
+%#### Lists (local)
+%
+% \end{markdown}
 %  \begin{macrocode}
   larsers.starter = parsers.bullet + larsers.enumerator
 
@@ -4185,14 +9183,24 @@ function M.reader.new(writer, options)
                              * -larsers.DefinitionListItemLoose * Cc(true))
                            ) / writer.definitionlist
 %    \end{macrocode}
-% \paragraph{Blank (local)}
+% \par
+% \begin{markdown}
+%
+%#### Blank (local)
+%
+% \end{markdown}
 %  \begin{macrocode}
   larsers.Blank        = parsers.blankline / ""
                        + larsers.NoteBlock
                        + larsers.Reference
                        + (parsers.tightblocksep / "\n")
 %    \end{macrocode}
-% \paragraph{Headings (local)}
+% \par
+% \begin{markdown}
+%
+%#### Headings (local)
+%
+% \end{markdown}
 %  \begin{macrocode}
   -- parse atx header
   larsers.AtxHeading = Cg(parsers.HeadingStart,"level")
@@ -4210,7 +9218,12 @@ function M.reader.new(writer, options)
 
   larsers.Heading = larsers.AtxHeading + larsers.SetextHeading
 %    \end{macrocode}
-% \paragraph{Syntax Specification}
+% \par
+% \begin{markdown}
+%
+%#### Syntax Specification
+%
+% \end{markdown}
 %  \begin{macrocode}
   local syntax =
     { "Blocks",
@@ -4353,19 +9366,25 @@ function M.reader.new(writer, options)
   inlines_nbsp_t.Space = larsers.NonbreakingSpace
   larsers.inlines_nbsp = Ct(inlines_nbsp_t)
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \paragraph{Exported Conversion Function}
+%#### Exported Conversion Function
 % Define \luamdef{reader->convert} as a function that converts markdown string
-% \t`input` into a plain \TeX{} output and returns it. Note that the converter
+% `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}
   function self.convert(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 \ref{sec:luaoptions}). The \Opt{cacheDir} option
 % is disregarded.
+% \end{markdown}
 %  \begin{macrocode}
     local opt_string = {}
     for k,_ in pairs(defaultOptions) do
@@ -4377,8 +9396,10 @@ function M.reader.new(writer, options)
     table.sort(opt_string)
     local salt = table.concat(opt_string, ",") .. "," .. metadata.version
 %    \end{macrocode}
+% \begin{markdown}
 % Produce the cache file, transform its filename via the \luam{writer->pack}
 % method, and return the result.
+% \end{markdown}
 %  \begin{macrocode}
     local name = util.cache(options.cacheDir, input, salt, function(input)
         return util.rope_to_string(parse_blocks_toplevel(input)) .. writer.eof
@@ -4388,11 +9409,16 @@ function M.reader.new(writer, options)
   return self
 end
 %    \end{macrocode}
-% \subsubsection{Conversion from Markdown to Plain \TeX{}}
+% \par
+% \begin{markdown}
+%
+%### Conversion from Markdown to Plain \TeX{}
 % The \luam{new} method returns the \luam{reader->convert} function of a reader
 % object associated with the Lua interface options (see Section
-% \ref{sec:luaoptions}) \t`options` and with a writer object associated with
-% \t`options`.
+% \ref{sec:luaoptions}) `options` and with a writer object associated with
+% `options`.
+%
+% \end{markdown}
 %  \begin{macrocode}
 function M.new(options)
   local writer = M.writer.new(options)
@@ -4402,17 +9428,84 @@ end
 
 return M
 %    \end{macrocode}
-%
 % \iffalse
 %</lua>
+%<*lua-cli>
+% \fi
+% \par
+% \begin{markdown}
+%
+%### Command-Line Implementation
+% \label{sec:lua-cli-implementation}
+% The command-line implementation provides the actual conversion routine for
+% the command-line interface described in Section~\ref{sec:lua-cli-interface}.
+%
+% \end{markdown}
+%  \begin{macrocode}
+
+local input
+if input_filename then
+  local input_file = io.open(input_filename, "r")
+  input = assert(input_file:read("*a"))
+  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 kpse = require("kpse")
+kpse.set_program_name("luatex")
+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)
+local output = convert(input:gsub("\r\n?", "\n"))
+
+if output_filename then
+  local output_file = io.open(output_filename, "w")
+  assert(output_file:write(output))
+  assert(output_file:close())
+else
+  assert(io.write(output))
+end
+%    \end{macrocode}
+% \iffalse
+%</lua-cli>
 %<*tex>
-% \fi\subsection{Plain \TeX{} Implementation}\label{sec:teximplementation}
+% \fi
+% \par
+% \begin{markdown}
+%
+% Plain \TeX{} Implementation
+%----------------------------
+% \label{sec: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 \ref{sec:texinterface}).
 %
-% \subsubsection{Logging Facilities}\label{sec:texinterfacelogging}
+%### Logging Facilities
+% \label{sec:texinterfacelogging}
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownInfo#1{%
   \immediate\write-1{(l.\the\inputlineno) markdown.tex info: #1.}}%
@@ -4422,16 +9515,20 @@ return M
   \errhelp{#2.}%
   \errmessage{(l.\the\inputlineno) markdown.tex error: #1}}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Token Renderer Prototypes}
+%### Token Renderer Prototypes
 % 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\markdownRendererLeftBracePrototype{\char`\{}%
+\def\markdownRendererRightBracePrototype{\char`\}}%
 \def\markdownRendererDollarSignPrototype{\char`$}%
 \def\markdownRendererPercentSignPrototype{\char`\%}%
 \def\markdownRendererAmpersandPrototype{\char`&}%
@@ -4476,7 +9573,7 @@ return M
 \def\markdownRendererBlockQuoteBeginPrototype{\par\begingroup\it}%
 \def\markdownRendererBlockQuoteEndPrototype{\endgroup\par}%
 \def\markdownRendererInputVerbatimPrototype#1{%
-  \par{\tt\input"#1"\relax}\par}%
+  \par{\tt\input"#1"\relax{}}\par}%
 \def\markdownRendererInputFencedCodePrototype#1#2{%
   \markdownRendererInputVerbatimPrototype{#1}}%
 \def\markdownRendererHeadingOnePrototype#1{#1}%
@@ -4490,11 +9587,15 @@ return M
 \def\markdownRendererCitePrototype#1{}%
 \def\markdownRendererTextCitePrototype#1{}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Lua Snippets}
+%### Lua Snippets
 % The \mdef{markdownLuaOptions} macro expands to a Lua table that
 % contains the plain \TeX{} options (see Section \ref{sec:texoptions}) in a
 % format recognized by Lua (see Section \ref{sec:luaoptions}).
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownLuaOptions{{%
 \ifx\markdownOptionBlankBeforeBlockquote\undefined\else
@@ -4547,7 +9648,6 @@ return M
 \ifx\markdownOptionInlineFootnotes\undefined\else
   inlineFootnotes = \markdownOptionInlineFootnotes,
 \fi
-  outputDir = "\markdownOptionOutputDir",
 \ifx\markdownOptionPreserveTabs\undefined\else
   preserveTabs = \markdownOptionPreserveTabs,
 \fi
@@ -4565,146 +9665,224 @@ return M
 \fi}
 }%
 %    \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
 % \luam{convert} function for the use by any further Lua code.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownPrepare{%
 %    \end{macrocode}
+% \begin{markdown}
 % First, ensure that the \m{markdownOptionCacheDir} directory exists.
+% \end{markdown}
 %  \begin{macrocode}
 local lfs = require("lfs")
 local cacheDir = "\markdownOptionCacheDir"
-if lfs.isdir(cacheDir) == true then else
+if not lfs.isdir(cacheDir) then
   assert(lfs.mkdir(cacheDir))
 end
 %    \end{macrocode}
-% Next, load the \t`markdown` module and create a converter function using
+% \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
 % \m{markdownLuaOptions} macro.
+% \end{markdown}
 %  \begin{macrocode}
 local md = require("markdown")
 local convert = md.new(\markdownLuaOptions)
 }%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Buffering Markdown Input}
+%### Buffering Markdown Input
+% \label{sec:buffering}
 % 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 \m{markdownReadAndConvert} macro is largely a rewrite of the
 % \Hologo{LaTeX2e} \m{filecontents} macro to plain \TeX{}.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \begingroup
 %    \end{macrocode}
-% Make the newline and tab characters active and swap the character codes of the
-% backslash symbol (\t`\textbackslash`) and the pipe symbol (\t`|`), so that
-% we can use the backslash as an ordinary character inside the macro definition.
+% \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
+% \m{markdownOptionStripPercentSigns} is `true`.
+% \end{markdown}
 %  \begin{macrocode}
   \catcode`\^^M=13%
   \catcode`\^^I=13%
   \catcode`|=0%
   \catcode`\\=12%
-  |gdef|markdownReadAndConvert#1#2{%
-    |begingroup%
+  |catcode`@=14%
+  |catcode`|%=12@
+  |gdef|markdownReadAndConvert#1#2{@
+    |begingroup@
 %    \end{macrocode}
+% \begin{markdown}
 % Open the \m{markdownOptionInputTempFileName} file for writing.
+% \end{markdown}
 %  \begin{macrocode}
-    |immediate|openout|markdownOutputFileStream%
-      |markdownOptionInputTempFileName%
-    |markdownInfo{Buffering markdown input into the temporary %
-      input file "|markdownOptionInputTempFileName" and scanning %
-      for the closing token sequence "#1"}%
+    |immediate|openout|markdownOutputFileStream@
+      |markdownOptionInputTempFileName@
+    |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
-% \emph{other} in order to prevent unwanted interpretation of the input.
-% Change also the category of the space character, so that we can retrieve it
+% *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.
-%  \begin{macrocode}
-    |def|do##1{|catcode`##1=12}|dospecials%
-    |catcode`| =12%
-    |markdownMakeOther%
-%    \end{macrocode}
+% \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
+% \m{markdownOptionStripPercentSigns} is `true`.
+% 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@
+      |else@
+        |expandafter@
+          |markdownReadAndConvertProcessLine@
+          |expandafter##1@
+      |fi}@
+%    \end{macrocode}
+% \begin{markdown}
 % The \mdef{markdownReadAndConvertProcessLine} macro will process the individual
-% lines of output. Note the use of the comments to ensure that the entire macro
-% is at a single line and therefore no (active) newline symbols are produced.
+% 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{%
+    |def|markdownReadAndConvertProcessLine##1#1##2#1##3|relax{@
 %    \end{macrocode}
+% \begin{markdown}
 % When the ending token sequence does not appear in the line, store the line in
 % the \m{markdownOptionInputTempFileName} file.
+% \end{markdown}
 %  \begin{macrocode}
-      |ifx|relax##3|relax%
-        |immediate|write|markdownOutputFileStream{##1}%
-      |else%
+      |ifx|relax##3|relax@
+        |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 \m{markdownOptionInputTempFileName} file, return the
 % character categories back to the former state, convert the
 % \m{markdownOptionInputTempFileName} file from markdown to plain \TeX{},
 % \m{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}%
-          |immediate|closeout|markdownOutputFileStream%
-          |endgroup%
-          |markdownInput|markdownOptionInputTempFileName%
-          #2}%
-      |fi%
+        |def^^M{@
+          |markdownInfo{The ending token sequence was found}@
+          |immediate|closeout|markdownOutputFileStream@
+          |endgroup@
+          |markdownInput|markdownOptionInputTempFileName@
+          #2}@
+      |fi@
 %    \end{macrocode}
+% \begin{markdown}
 % Repeat with the next line.
+% \end{markdown}
 %  \begin{macrocode}
-      ^^M}%
+      ^^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}%
+    |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 \m{markdownReadAndConvertProcessLine} macro.
+% \end{markdown}
 %  \begin{macrocode}
-    |catcode`|^^M=13%
-    |def^^M##1^^M{%
-      |def^^M####1^^M{%
-        |markdownReadAndConvertProcessLine####1#1#1|relax}%
-      ^^M}%
-    ^^M}%
+    |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}
 %
-% \subsubsection{Lua Shell Escape Bridge}\label{sec:luabridge}
+%### Lua Shell Escape Bridge
+% \label{sec: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 \m{markdownMode} values of \t`0` and \t`1`.
+% corresponds to the \m{markdownMode} values of `0` and `1`.
 %
 % The \m{markdownLuaExecute} macro defined here and in Section
 % \ref{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 (see
-% \cite[Section~3.1.1]{luatex17}).
+% execute Lua scripts using the \TeX{}Lua interpreter~[@luatex17, Section
+% 3.1.1].
+%
+% \end{markdown}
 %  \begin{macrocode}
 \ifnum\markdownMode<2\relax
 \ifnum\markdownMode=0\relax
@@ -4713,17 +9891,21 @@ local convert = md.new(\markdownLuaOptions)
   \markdownInfo{Using mode 1: Shell escape via os.execute}%
 \fi
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \mdef{markdownExecuteShellEscape} macro contains the numeric value indicating
-% whether the shell access is enabled (\t`1`), disabled (\t`0`), or restricted
-% (\t`2`).
-% 
+% whether the shell access is enabled (`1`), disabled (`0`), or restricted
+% (`2`).
+%
 % Inherit the value of the the \m{pdfshellescape} (Lua\TeX{}, \Hologo{pdfTeX})
 % or the \m{shellescape} (\Hologo{XeTeX}) commands. If neither of these
 % commands is defined and Lua is available, attempt to access the
 % \luam{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
@@ -4740,10 +9922,14 @@ local convert = md.new(\markdownLuaOptions)
   \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 \luam{os.execute} method otherwise.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \ifnum\markdownMode=0\relax
   \def\markdownExecuteDirect#1{\immediate\write18{#1}}%
@@ -4752,11 +9938,15 @@ local convert = md.new(\markdownLuaOptions)
     \directlua{os.execute("\luaescapestring{#1}")}}%
 \fi
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % The \mdef{markdownExecute} macro is a wrapper on top of
 % \m{markdownExecuteDirect} that checks the value of
 % \m{markdownExecuteShellEscape} and prints an error message if the shell is
 % inaccessible.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownExecute#1{%
   \ifnum\markdownExecuteShellEscape=1\relax
@@ -4767,24 +9957,32 @@ local convert = md.new(\markdownLuaOptions)
       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 \luam{print} function in the same manner it
 % would use the \luam{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 \m{markdownOptionHelperScriptFileName} 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
@@ -4792,13 +9990,15 @@ local convert = md.new(\markdownLuaOptions)
       "|markdownOptionHelperScriptFileName"}%
     |immediate|write|markdownOutputFileStream{%
       local ran_ok, error = pcall(function()
-        local kpse = require('kpse')
-        kpse.set_program_name('luatex')
+        local kpse = require("kpse")
+        kpse.set_program_name("luatex")
         #1
       end)
 %    \end{macrocode}
+% \begin{markdown}
 % If there was an error, use the file \m{markdownOptionErrorTempFileName} to
 % store the error message.
+% \end{markdown}
 %  \begin{macrocode}
       if not ran_ok then
         local file = io.open("%
@@ -4815,9 +10015,11 @@ local convert = md.new(\markdownLuaOptions)
       end}%
     |immediate|closeout|markdownOutputFileStream
 %    \end{macrocode}
+% \begin{markdown}
 % Execute the generated \m{markdownOptionHelperScriptFileName} Lua script using
 % the \TeX{}Lua binary and store the output in the
 % \m{markdownOptionOutputTempFileName} file.
+% \end{markdown}
 %  \begin{macrocode}
     |markdownInfo{Executing a helper Lua script from the file
       "|markdownOptionHelperScriptFileName" and storing the result in the
@@ -4827,93 +10029,130 @@ local convert = md.new(\markdownLuaOptions)
       "|markdownOptionOutputDir
       /|markdownOptionOutputTempFileName"}%
 %    \end{macrocode}
+% \begin{markdown}
 % \m{input} the generated \m{markdownOptionOutputTempFileName} file.
+% \end{markdown}
 %  \begin{macrocode}
     |input|markdownOptionOutputTempFileName|relax}%
 |endgroup
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Direct Lua Access}\label{sec:directlua}
+%### Direct Lua Access
+% \label{sec:directlua}
 % The following \TeX{} code is intended for \TeX{} engines that provide
 % direct access to Lua (Lua\TeX{}). The macro \m{markdownLuaExecute} defined
 % here and in Section \ref{sec:luabridge} are meant to be indistinguishable to
-% the remaining code. This corresponds to the \m{markdownMode} value of \t`2`.
+% the remaining code. This corresponds to the \m{markdownMode} value of `2`.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \else
 \markdownInfo{Using mode 2: Direct Lua access}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
+%
 % The direct Lua access version of the \m{markdownLuaExecute} macro is defined
 % in terms of the \m{directlua} primitive. The \luam{print} function is set as
 % an alias to the \m{tex.print} method in order to mimic the behaviour of the
 % \m{markdownLuaExecute} definition from Section \ref{sec:luabridge},
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownLuaExecute#1{\directlua{local print = tex.print #1}}%
 \fi
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Typesetting Markdown}
+%### Typesetting Markdown
 % The \m{markdownInput} macro uses an implementation of the
 % \m{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.
+% \end{markdown}
 %  \begin{macrocode}
   \catcode`|=0%
   \catcode`\\=12%
   |gdef|markdownInput#1{%
     |markdownInfo{Including markdown document "#1"}%
 %    \end{macrocode}
-% Attempt to open the markdown document to record it in the \t`.log` and
-% \t`.fls` files. This allows external programs such as \LaTeX Mk to track
+% \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
     |markdownLuaExecute{%
       |markdownPrepare
-      local input = assert(io.open("#1","r")):read("*a")
+      local input = assert(io.open("#1", "r"):read("*a"))
 %    \end{macrocode}
+% \begin{markdown}
 % Since the Lua converter expects \acro{unix} line endings, normalize the
 % input.
+% \end{markdown}
 %  \begin{macrocode}
       print(convert(input:gsub("\r\n?", "\n")))}}%
 |endgroup
 %    \end{macrocode}
-%
 % \iffalse
 %</tex>
 %<*latex>
-% \fi\subsection{\LaTeX{} Implementation}\label{sec:lateximplementation}
+% \fi
+% \par
+% \begin{markdown}
+%
+% \LaTeX{} Implementation
+%------------------------
+% \label{sec:lateximplementation}
 % The \LaTeX{} implemenation makes use of the fact that, apart from some subtle
-% differences, \LaTeX{} implements the majority of the plain \TeX{} format
-% (see \cite[Section~9]{latex17}). As a consequence, we can directly reuse the
+% 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}
 \input markdown
 \def\markdownVersionSpace{ }%
 \ProvidesPackage{markdown}[\markdownLastModified\markdownVersionSpace v%
   \markdownVersion\markdownVersionSpace markdown renderer]%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Logging Facilities}
+%### Logging Facilities
 % The \LaTeX{} implementation redefines the plain \TeX{} logging macros (see
 % Section \ref{sec:texinterfacelogging}) to use the \LaTeX{} \m{PackageInfo},
 % \m{PackageWarning}, and \m{PackageError} macros.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \renewcommand\markdownInfo[1]{\PackageInfo{markdown}{#1}}%
 \renewcommand\markdownWarning[1]{\PackageWarning{markdown}{#1}}%
 \renewcommand\markdownError[2]{\PackageError{markdown}{#1}{#2.}}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Typesetting Markdown}
+%### Typesetting Markdown
 % The \mdef{markdownInputPlainTeX} macro is used to store the original plain
 % \TeX{} implementation of the \m{markdownInput} macro. The \m{markdownInput}
 % is then redefined to accept an optional argument with options recognized by
 % the \LaTeX{} interface (see Section \ref{sec:latexoptions}).
+%
+% \end{markdown}
 %  \begin{macrocode}
 \let\markdownInputPlainTeX\markdownInput
 \renewcommand\markdownInput[2][]{%
@@ -4922,9 +10161,13 @@ local convert = md.new(\markdownLuaOptions)
     \markdownInputPlainTeX{#2}%
   \endgroup}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
+%
+% The \envm{markdown}, and \envm{markdown*} \LaTeX{} environments are
+% implemented using the \m{markdownReadAndConvert} macro.
 %
-% The \env{markdown}, and \env{markdown*} \LaTeX{} environments are implemented
-% using the \m{markdownReadAndConvert} macro.
+% \end{markdown}
 %  \begin{macrocode}
 \renewenvironment{markdown}{%
   \markdownReadAndConvert@markdown{}}\relax
@@ -4933,11 +10176,13 @@ local convert = md.new(\markdownLuaOptions)
   \markdownReadAndConvert@markdown*}\relax
 \begingroup
 %    \end{macrocode}
+% \begin{markdown}
 % Locally swap the category code of the backslash symbol with the pipe symbol,
-% and of the left (\t`\{`) and right brace (\t`\}`) with the less-than (\t`<`)
-% and greater-than (\t`>`) signs. This is required in order that all the
+% 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
-% \t`markdownReadAndConvert` macro have the category code \emph{other}.
+% `markdownReadAndConvert` macro have the category code *other*.
+% \end{markdown}
 %  \begin{macrocode}
   \catcode`\|=0\catcode`\<=1\catcode`\>=2%
   \catcode`\\=12|catcode`|{=12|catcode`|}=12%
@@ -4946,16 +10191,25 @@ local convert = md.new(\markdownLuaOptions)
                            <|end<markdown#1>>>%
 |endgroup
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Options}
+%### Options
 % The supplied package options are processed using the \m{markdownSetup} macro.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \DeclareOption*{%
   \expandafter\markdownSetup\expandafter{\CurrentOption}}%
 \ProcessOptions\relax
 %    \end{macrocode}
-% After processing the options, activate the \t`renderers` and
-% \t`rendererPrototypes` keys.
+% \par
+% \begin{markdown}
+%
+% After processing the options, activate the `renderers` and
+% `rendererPrototypes` keys.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \define@key{markdownOptions}{renderers}{%
   \setkeys{markdownRenderers}{#1}%
@@ -4964,15 +10218,19 @@ local convert = md.new(\markdownLuaOptions)
   \setkeys{markdownRendererPrototypes}{#1}%
   \def\KV@prefix{KV@markdownOptions@}}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Token Renderer Prototypes}
+%### Token Renderer Prototypes
 % The following configuration should be considered placeholder.
 %
-% If the \m{markdownOptionTightLists} macro expands to \t`false`, do not load
+% If the \m{markdownOptionTightLists} macro expands to `false`, do not load
 % the \pkg{paralist} package. This is necessary for \Hologo{LaTeX2e} document
 % classes that do not play nice with \pkg{paralist}, such as \pkg{beamer}.
 % If the \m{markdownOptionTightLists} is undefined and the \pkg{beamer}
 % document class is in use, then do not load the \pkg{paralist} package either.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \ifx\markdownOptionTightLists\undefined
   \@ifclassloaded{beamer}{}{
@@ -4982,10 +10240,15 @@ local convert = md.new(\markdownLuaOptions)
     \RequirePackage{paralist}}
 \fi
 %    \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}
 \@ifpackageloaded{paralist}{
   \markdownSetup{rendererPrototypes={
@@ -5014,8 +10277,6 @@ local convert = md.new(\markdownLuaOptions)
   tilde = {\textasciitilde},
   pipe = {\textbar},
   codeSpan = {\texttt{#1}},
-  link = {#1\footnote{\ifx\empty#4\empty\else#4:
-    \fi\texttt<\url{#3}\texttt>}},
   contentBlock = {%
     \ifthenelse{\equal{#1}{csv}}{%
       \begin{table}%
@@ -5056,18 +10317,28 @@ local convert = md.new(\markdownLuaOptions)
     \ifx\relax#2\relax
       \VerbatimInput{#1}%
     \else
-      \ifx\minted@jobname\undefined
+      \ifx\minted@code\undefined
         \ifx\lst@version\undefined
           \markdownRendererInputFencedCode{#1}{}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
+%
 % When the \pkg{listings} package is loaded, use it for syntax highlighting.
+%
+% \end{markdown}
 %  \begin{macrocode}
         \else
           \lstinputlisting[language=#2]{#1}%
         \fi
 %    \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}
       \else
         \inputminted{#2}{#1}%
@@ -5076,8 +10347,12 @@ local convert = md.new(\markdownLuaOptions)
   horizontalRule = {\noindent\rule[0.5ex]{\linewidth}{1pt}},
   footnote = {\footnote{#1}}}}
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Support the nesting of strong emphasis.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \newif\ifmarkdownLATEXStrongEmphasisNested
 \markdownLATEXStrongEmphasisNestedfalse
@@ -5093,31 +10368,39 @@ local convert = md.new(\markdownLuaOptions)
       \markdownLATEXStrongEmphasisNestedfalse
     \fi}}}
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % Support \LaTeX{} document classes that do not provide chapters.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \ifx\chapter\undefined
   \markdownSetup{rendererPrototypes = {
     headingOne = {\section{#1}},
     headingTwo = {\subsection{#1}},
     headingThree = {\subsubsection{#1}},
-    headingFour = {\paragraph{#1}},
-    headingFive = {\subparagraph{#1}}}}
+    headingFour = {\paragraph{#1}\leavevmode},
+    headingFive = {\subparagraph{#1}\leavevmode}}}
 \else
   \markdownSetup{rendererPrototypes = {
     headingOne = {\chapter{#1}},
     headingTwo = {\section{#1}},
     headingThree = {\subsection{#1}},
     headingFour = {\subsubsection{#1}},
-    headingFive = {\paragraph{#1}},
-    headingSix = {\subparagraph{#1}}}}
+    headingFive = {\paragraph{#1}\leavevmode},
+    headingSix = {\subparagraph{#1}\leavevmode}}}
 \fi
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % There is a basic implementation for citations that uses the \LaTeX{} \m{cite}
 % macro. There is also a more advanced implementation that uses the Bib\LaTeX{}
 % \m{autocites} and \m{textcites} macros. This implementation will be used, when
 % Bib\LaTeX{} is loaded.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \newcount\markdownLaTeXCitationsCounter
 
@@ -5168,12 +10451,35 @@ local convert = md.new(\markdownLuaOptions)
       \expandafter{\expandafter}%
     \fi}}}
 %    \end{macrocode}
+% \par
+% \begin{markdown}
+%
+% 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. After the hyperlink has been typeset,
+% we restore the original catcode.
+%
+% \end{markdown}
+%  \begin{macrocode}
+\def\markdownRendererLinkPrototype{%
+  \begingroup
+  \catcode`\#=12
+  \def\next##1##2##3##4{%
+    ##1\footnote{%
+      \ifx\empty##4\empty\else##4: \fi\texttt<\url{##3}\texttt>}%
+    \endgroup}%
+  \next}
+%    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Miscellanea}
+%### 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 \m{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
@@ -5182,28 +10488,38 @@ local convert = md.new(\markdownLuaOptions)
     \advance\count0 by 1\relax
   \ifnum\count0<256\repeat}%
 %    \end{macrocode}
-%
 % \iffalse
 %</latex>
 %<*context>
-% \fi\subsection{\Hologo{ConTeXt} Implementation}
+% \fi
+% \par
+% \begin{markdown}
+%
+% \Hologo{ConTeXt} Implementation
+%--------------------------------
 % \label{sec: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
-% \emph{seem} to implement (the documentation is scarce) the majority of the
+% *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.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\dospecials{\do\ \do\\\do\{\do\}\do\$\do\&%
   \do\#\do\^\do\_\do\%\do\~}%
 \input markdown
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
 % When buffering user input, we should disable the bytes with the high bit set,
 % since these are made active by the \m{enableregime} macro. We will do this
 % by redefining the \m{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
@@ -5212,31 +10528,46 @@ local convert = md.new(\markdownLuaOptions)
     \advance\count0 by 1\relax
   \ifnum\count0<256\repeat
 %    \end{macrocode}
-% On top of that, make the pipe character (\t`|`) inactive during the scanning.
+% \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}
-% 
-% \subsubsection{Logging Facilities}
+% \par
+% \begin{markdown}
+%
+%### Logging Facilities
 % The \Hologo{ConTeXt} implementation redefines the plain \TeX{} logging macros (see
 % Section \ref{sec:texinterfacelogging}) to use the \Hologo{ConTeXt}
 % \m{writestatus} macro.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownInfo#1{\writestatus{markdown}{#1.}}%
 \def\markdownWarning#1{\writestatus{markdown\space warn}{#1.}}%
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Typesetting Markdown}
+%### Typesetting Markdown
 % The \m{startmarkdown} and \m{stopmarkdown} macros are implemented using the
 % \m{markdownReadAndConvert} macro.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \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 that appear in the
-% first argument of the \t`markdownReadAndConvert` macro have the category code
-% \emph{other}.
+% first argument of the `markdownReadAndConvert` macro have the category code
+% *other*.
+% \end{markdown}
 %  \begin{macrocode}
   \catcode`\|=0%
   \catcode`\\=12%
@@ -5245,9 +10576,13 @@ local convert = md.new(\markdownLuaOptions)
                            {|stopmarkdown}}%
 |endgroup
 %    \end{macrocode}
+% \par
+% \begin{markdown}
 %
-% \subsubsection{Token Renderer Prototypes}
+%### Token Renderer Prototypes
 % The following configuration should be considered placeholder.
+%
+% \end{markdown}
 %  \begin{macrocode}
 \def\markdownRendererLineBreakPrototype{\blank}%
 \def\markdownRendererLeftBracePrototype{\textbraceleft}%
@@ -5326,15 +10661,17 @@ local convert = md.new(\markdownLuaOptions)
     \typefile{#1}%
   \else
 %    \end{macrocode}
-% 
+% \par
+% \begin{markdown}
+%
 % The code fence infostring is used as a name from the \Hologo{ConTeXt}
 % \m{definetyping} macro. This allows the user to set up code highlighting
 % mapping as follows:
-% \begin{Verbatim}
+% ````` tex
 % % Map the `TEX` syntax highlighter to the `latex` infostring.
 % \definetyping [latex]
 % \setuptyping  [latex] [option=TEX]
-% 
+%
 % \starttext
 %   \startmarkdown
 % ~~~ latex
@@ -5345,7 +10682,9 @@ local convert = md.new(\markdownLuaOptions)
 % ~~~
 %   \stopmarkdown
 % \stoptext
-% \end{Verbatim}
+% `````````
+%
+% \end{markdown}
 %  \begin{macrocode}
     \typefile[#2][]{#1}%
   \fi}%
@@ -5360,7 +10699,6 @@ local convert = md.new(\markdownLuaOptions)
 \def\markdownRendererFootnotePrototype#1{\footnote{#1}}%
 \stopmodule\protect
 %    \end{macrocode}
-%
 % \iffalse
 %</context>
 % \fi
diff --git a/Master/texmf-dist/source/generic/markdown/markdown.ins b/Master/texmf-dist/source/generic/markdown/markdown.ins
index 76ed44df1ef..0965a974b78 100644
--- a/Master/texmf-dist/source/generic/markdown/markdown.ins
+++ b/Master/texmf-dist/source/generic/markdown/markdown.ins
@@ -1,8 +1,12 @@
 \input docstrip.tex
 \generate{\usepreamble\luapreamble\usepostamble\luapostamble
           \file{markdown.lua}{\from{markdown.dtx}{lua}}
+          \file{markdown-cli.lua}{\from{markdown.dtx}{lua-cli}}
           \usepreamble\texpreamble\usepostamble\texpostamble
           \file{markdown.tex}{\from{markdown.dtx}{tex}}
           \file{markdown.sty}{\from{markdown.dtx}{latex}}
-          \file{t-markdown.tex}{\from{markdown.dtx}{context}}}
+          \file{t-markdown.tex}{\from{markdown.dtx}{context}}
+          \usepreamble\empty\usepostamble\empty
+          \file{markdown.md}{\from{markdown.dtx}{manual}}
+          \file{markdown.css}{\from{markdown.dtx}{manual-css}}}
 \endbatchfile