Markdown Package User Manual
Author: Vít Starý Novotný, Andrej Genčur

# 1 Introduction

The Markdown package converts CommonMark 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 converters, the Markdown package does not require any external programs, and makes it easy to redefine how each and every markdown element is rendered. Creative abuse of the markdown syntax is encouraged.

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

## 1.1 Requirements

The package requires either our official Docker image, which contains the latest development version of the Markdown package, or a TeX distribution: TeX Live ≥ 2023 is known to work with the current version of the Markdown package and so are recent versions of MikTeX. If you are using an older, incomplete, or atypical TeX distribution, please consult the technical documentation for a detailed list of requirements.

You are also advised to use LuaTeX with the Markdown Package for TeX. Using pdfTeX, XeTeXt and other TeX engines comes with several limitations:

1. The filenames of your .tex files may not contain spaces, see also #573.
2. If `-output-directory` is provided, it may not contain spaces and it won’t be automatically detected by MikTeX, see also miktex/miktex#1630.1

## 1.2 Installation

If the Markdown package is not included in your TeX distribution, you will need to install it.

From Releases, download an archive `markdown.zip` for this version of the Markdown package (3.15.1) or a different version that you wish to install. Then, unzip the archive. If you downloaded an archive for a different version of the Markdown package, you should now locate a file named `markdown.html` with the user manual for that version, open it, and follow the installation steps in it rather than the steps from this manual.

Alternatively, download the package from the repository using Git, enter the directory named `markdown` and run the `make base` command using GNU Make:

    git clone https://github.com/witiko/markdown
    cd markdown
    make base

Either of the two abovelisted approaches should produce the following files:

- `markdown.lua`, `markdown-parser.lua`, and `markdown-unicode-data.lua`: The Lua module
- `markdown-cli.lua` and `markdown2tex.lua`: The Lua command-line interface
- `markdown.tex`: The plain TeX macro package
- `markdown.sty`: The LaTeX package
- `markdownthemewitiko_markdown_defaults.tex`, `markdownthemewitiko_markdown_defaults.sty`, and `t-markdownthemewitiko_markdown_defaults.tex`: The `witiko/markdown/defaults` theme
- `t-markdown.tex`: The ConTeXt module

### 1.2.1 Local Installation

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

- `⟨TEXMF⟩/tex/luatex/markdown/markdown.lua`
- `⟨TEXMF⟩/tex/luatex/markdown/markdown-parser.lua`
- `⟨TEXMF⟩/tex/luatex/markdown/markdown-unicode-data.lua`
- `⟨TEXMF⟩/scripts/markdown/markdown-cli.lua`
- `⟨TEXMF⟩/scripts/markdown/markdown2tex.lua`
- `⟨TEXMF⟩/tex/generic/markdown/markdown.tex`
- `⟨TEXMF⟩/tex/generic/markdown/markdownthemewitiko_markdown_defaults.tex`
- `⟨TEXMF⟩/tex/latex/markdown/markdown.sty`
- `⟨TEXMF⟩/tex/latex/markdown/markdownthemewitiko_markdown_defaults.sty`
- `⟨TEXMF⟩/tex/context/third/markdown/t-markdown.tex`
- `⟨TEXMF⟩/tex/context/third/markdown/t-markdownthemewitiko_markdown_defaults.tex`

`⟨TEXMF⟩` corresponds to a root directory of one of your TeX directory structure (TDS) trees. You may list the locations of all TDS trees using a command such as `kpsewhich -var-value=TEXMF` (in TeX Live) or `mtxrun --resolve-path TEXMF` (in ConTeXt Standalone). For more information, consult the manual of your TeX distribution.

### 1.2.2 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.

This is where the individual files should be placed:

- `./markdown.lua`
- `./markdown-parser.lua`
- `./markdown-unicode-data.lua`
- `./markdown-cli.lua`
- `./markdown2tex.lua`
- `./markdown/markdown.tex`
- `./markdown.sty`
- `./t-markdown.tex`
- `./markdownthemewitiko_markdown_defaults.tex`
- `./markdownthemewitiko_markdown_defaults.sty`
- `./t-markdownthemewitiko_markdown_defaults.tex`

The file `markdown.tex` must be placed in a directory named `markdown`.

### 1.2.3 Installing Dependencies (ConTeXt Standalone)

The Markdown package has a number of external dependencies. Here are the package names of these dependencies in the TeX Live distribution:

    hard l3kernel
    hard lt3luabridge
    hard lua-tinyyaml
    soft amsfonts
    soft amsmath
    soft csvsimple
    soft enumitem
    soft epstopdf
    soft epstopdf-pkg
    soft etoolbox
    soft fancyvrb
    soft graphics
    soft ltxcmds
    soft lua-ul
    soft luacolor
    soft luaxml
    soft paralist
    soft pgf
    soft soul
    soft tools
    soft url
    soft verse
    soft xcolor

Some TeX distributions, such as TeX Live installed with a scheme smaller than `scheme-full` or ConTeXt Standalone, may lack some or all of these dependencies. To complete the installation of the Markdown package with such distributions, you should follow these steps:

1. For each package that is a hard dependency of the Markdown package (i.e. has the prefix `hard` in the above list), download an archive from the web address `https://mirror.ctan.org/systems/texlive/tlnet/archive/⟨package name⟩.tar.xz`.

2. Unpack the downloaded package archives to the directory `⟨TEXMF⟩`.

   `⟨TEXMF⟩` corresponds to a root directory of one of your TeX directory structure (TDS) trees. You may list the locations of all TDS trees using a command such as `kpsewhich -var-value=TEXMF` (in TeX Live) or `mtxrun --resolve-path TEXMF` (in ConTeXt Standalone). For more information, consult the manual of your TeX distribution.

   To unpack the package archive, you would use a command such as `tar xJf ⟨package name⟩.tar.xz -C ⟨TEXMF⟩` on GNU/Linux and other Un*x systems.

   Some package archives may contain extra top-level directories such as `texmf-dist` and `tlpkg`. For these packages, you should only extract the contents of the directory `texmf-dist` to `⟨TEXMF⟩`. Here, you might use a command such as `tar xJf ⟨package name⟩.tar.xz -C ⟨TEXMF⟩ --wildcards 'texmf-dist/*' --strip-components=1` on GNU/Linux and other Un*x systems.

3. Run a command such as `texhash` (in TeX Live) or `mtxrun --generate` and `context --generate --luatex` (in ConTeXt Standalone) to make the installed packages visible to TeX. For more information, consult the manual of your TeX distribution.

## 1.3 First Document

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

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

    docker run --rm -v "$PWD"/workdir:/workdir -w /workdir witiko/markdown \
      luatex document.tex

### 1.3.1 Using Lua

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

    \input markdown
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input hello
    \endgroup
    \bye

#### 1.3.1.1 Using the Lua Module

Using a text editor, create a text document named `hello.lua` with the following content:

    #!/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:

    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:

    texlua hello.lua > hello.tex
    pdftex document.tex

#### 1.3.1.2 Using the Lua Command-Line Interface

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

    Hello *world*!

Next, invoke LuaTeX from the terminal:

    markdown2tex -- hello.md 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:

    markdown2tex -- hello.md hello.tex
    pdftex document.tex

### 1.3.2 Using Plain TeX

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

    \input markdown
    \markdownBegin
    Hello *world*!
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

Instead of LuaTeX, you may also use pdfTeX:

    pdftex --shell-escape document.tex

This should also produce a PDF document named `document.pdf` with the same content.

Instead of writing your markdown document between `\markdownBegin` and `\markdownEnd`, you can also include markdown documents using the `\markdownInput` macro, similarly to how you might use the `\input` TeX primitive to include TeX documents.

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

    Hello *world*!

Create also a text document named `document.tex` with the following content:

    \input markdown
    \markdownInput{hello.md}
    \bye

Next, invoke LuaTeX or pdfTeX from the terminal like in the previous example. A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

### 1.3.3 Using LaTeX

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

    \documentclass{article}
    \usepackage{markdown}
    \begin{document}
    \begin{markdown}
    Hello *world*!
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

Instead of LuaTeX, you may also use pdfTeX:

    pdflatex --shell-escape document.tex

This should also produce a PDF document named `document.pdf` with the same content.

Instead of writing your markdown document between `\begin{markdown}` and `\end{markdown}`, you can also include markdown documents using the `\markdownInput` macro, similarly to how you might use the `\input` TeX primitive to include LaTeX documents.

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

    Hello *world*!

Create also a text document named `document.tex` with the following content:

    \documentclass{article}
    \usepackage{markdown}
    \begin{document}
    \begin{markdown}
    \markdownInput{hello.md}
    \end{markdown}
    \end{document}

Next, invoke LuaTeX or pdfTeX from the terminal like in the previous example. A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

As the next step, try typesetting the example documents distributed along with the Markdown package:

    git clone https://github.com/witiko/markdown
    cd markdown/examples
    lualatex latex-luatex.tex

A PDF document named `latex-luatex.pdf` should be produced. Open the text documents `latex-luatex.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:

    lualatex latex-luatex.tex

to see the effect of your changes.

### 1.3.4 Using ConTeXt

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

    \usemodule[t][markdown]
    \starttext
    \startmarkdown
    Hello *world*!
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

Instead of writing your markdown document between `\startmarkdown` and `\stopmarkdown`, you can also include markdown documents using the `\inputmarkdown` macro, similarly to how you might use the `\input` TeX primitive to include ConTeXt documents.

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

    Hello *world*!

Create also a text document named `document.tex` with the following content:

    \usemodule[t][markdown]
    \starttext
    \inputmarkdown{hello.md}
    \stoptext

Next, invoke LuaTeX from the terminal like in the previous example. A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

As the next step, try typesetting the example documents distributed along with the Markdown package:

    git clone https://github.com/witiko/markdown
    cd markdown/examples
    context --luatex 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:

    context --luatex context.tex

to see the effect of your changes.

# 2 Examples

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

## 2.1 Interfaces

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

### 2.1.1 Lua

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

#### 2.1.1.1 Lua Module

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

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:

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input example
    \endgroup
    \bye

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

    #!/usr/bin/env texlua
    local kpse = require("kpse")
    kpse.set_program_name("luatex")
    local markdown = require("markdown")
    local input, convert_nomath, convert_math, paragraph

    input = [[$\sqrt{-1}$ *equals* $i$.]]
    convert_nomath = markdown.new()
    convert_math = markdown.new({texMathDollars = true})
    paragraph = [[\par]]

    print(
      convert_nomath(input) .. paragraph ..
      convert_math(input)
    )

Next, invoke LuaTeX from the terminal:

    texlua example.lua > example.tex
    luatex document.tex

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

> $\sqrt{-1}$ equals $i$.

> −1 equals i.

Invoking pdfTeX should have the same effect:

    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:

    \input markdown
    \input lmfonts
    \directlua{
      local markdown = require("markdown")
      local input, convert_nomath, convert_math, paragraph

      input = [[$\string\sqrt{-1}$ *equals* $i$.]]
      convert_nomath = markdown.new()
      convert_math = markdown.new({texMathDollars = true})
      paragraph = [[\par]]

      tex.sprint(
        convert_nomath(input) .. paragraph ..
        convert_math(input)
      )
    }
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> $\sqrt{-1}$ equals $i$.

> −1 equals i.

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

#### 2.1.1.2 Lua Command-Line Interface

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

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

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input nomath
    \par
    \input math
    \endgroup
    \bye

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

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

Next, invoke LuaTeX from the terminal:

    markdown2tex -- example.md nomath.tex
    markdown2tex tex_math_dollars=true -- example.md math.tex
    luatex document.tex

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

> $\sqrt{-1}$ equals $i$.

> −1 equals i.

Invoking pdfTeX should have the same effect:

    markdown2tex -- example.md nomath.tex
    markdown2tex tex_math_dollars=true -- example.md math.tex
    pdftex document.tex

### 2.1.2 Plain TeX

The plain TeX interface provides TeX commands that typeset markdown documents by using the Lua interface behind the scenes. Unlike the Lua interface, the plain TeX interface does not provide low-level tools for converting markdown to TeX. Instead, its goal is to provide high-level typesetting capabilities.

The plain TeX interface accepts the same options as the `markdown` Lua module, in addition to its own options, but now the options are specified as TeX commands.

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

    \input markdown
    \input lmfonts

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

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

    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> $\sqrt{-1}$ equals $i$.

> −1 equals i.

Invoking pdfTeX should have the same effect:

    pdftex --shell-escape document.tex

### 2.1.3 LaTeX

The LaTeX interface provides the same level of functionality as the plain TeX interface by using the plain TeX interface behind the scenes. Unlike the plain TeX interface, the LaTeX interface uses familiar LaTeX idioms, such as package options and environments.

The LaTeX interface accepts the same options as the plain TeX interface, but now the options are specified as ⟨key⟩=⟨value⟩ pairs and they are passed either as package options, in the `markdownSetup` command, or as parameters for the `markdown` LaTeX environment.

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

    \documentclass{article}
    \usepackage{markdown}
    \begin{document}

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

    \begin{markdown}[texMathDollars]
    $\sqrt{-1}$ *equals* $i$
    \end{markdown}

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> $\sqrt{-1}$ equals $i$.

> −1 equals i.

Invoking pdfTeX should have the same effect:

    pdflatex --shell-escape document.tex

### 2.1.4 ConTeXt

The ConTeXt interface provides the same level of functionality as the plain TeX interface by using the plain TeX interface behind the scenes. Unlike the plain TeX interface, the ConTeXt interface uses familiar ConTeXt idioms as syntactic sugar.

The ConTeXt interface accepts the same options as the plain TeX interface.

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

    \usemodule[t][markdown]
    \starttext

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

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> $\sqrt{-1}$ equals $i$.

> −1 equals i.

## 2.2 Options

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

### 2.2.1 Lua

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

#### 2.2.1.1 Option `eagerCache`

`eagerCache` (default value: `true`)
  true

    Converted markdown documents will be cached in `cacheDir`. This can be useful for post-processing the converted documents and for recovering historical versions of the documents from the cache. Furthermore, it can also significantly improve the processing speed for documents that require multiple compilation runs, since each markdown document is only converted once. However, it also produces a large number of auxiliary files on the disk.

    This behavior will always be used if the `finalizeCache` option is enabled.

  false

    Converted markdown documents will not be cached. This decreases the number of auxiliary files that we produce and makes it easier to use the Lua command-line interface for plumbing. However, it makes it impossible to post-process the converted documents and recover historical versions of the documents from the cache. Furthermore, it can significantly reduce the processing speed for documents that require multiple compilation runs, since each markdown document is converted multiple times needlessly.

    This behavior will only be used when the `finalizeCache` option is disabled.

##### Lua CLI Example

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

    Hello *world*!

Next, invoke LuaTeX from the terminal with the `eagerCache` option disabled:

    markdown2tex eagerCache=false -- hello.md hello.tex

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

    Hello \markdownRendererEmphasis{world}!\relax

Invoke LuaTeX from the terminal again, this time with the `eagerCache` option enabled:

    markdown2tex eagerCache=true -- hello.md hello.tex

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

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

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

    Hello \markdownRendererEmphasis{world}!\relax

#### 2.2.1.2 Option `experimental`

`experimental` (default value: `false`)
  true

    Experimental features that are planned to be the new default in the next major release of the Markdown package will be enabled.

    At the moment, this has the following effects:

    1. The version `experimental` of the theme `witiko/markdown/defaults` will be loaded.
    2. Warnings for hard-deprecated features will become errors.
    3. The experimental option `htmlOverLinks` will be enabled.

    In the future, the effects may extend to other areas as well.

  false

    Experimental features will be disabled.

#### 2.2.1.3 Option `singletonCache`

`singletonCache` (default value: `true`)
  true

    Conversion functions produced by the function `new``(options)` will be cached in an LRU cache of size 1 keyed by `options`. This is more time- and space-efficient than always producing a new conversion function but may expose bugs related to the idempotence of conversion functions.

    This has been the default behavior since version 3.0.0 of the Markdown package.

  false

    Every call to the function `new``(options)` will produce a new conversion function that will not be cached. This is slower than caching conversion functions and may expose bugs related to memory leaks in the creation of conversion functions, see also #226 (comment).

    This was the default behavior until version 3.0.0 of the Markdown package.

#### 2.2.1.4 Option `unicodeNormalization`

`unicodeNormalization` (default value: `true`)
  true

    Markdown documents will be normalized using one of the four Unicode normalization forms before conversion. The Unicode normalization norm used is determined by option `unicodeNormalizationForm`.

  false

    Markdown documents will not be Unicode-normalized before conversion.

#### 2.2.1.5 Option `unicodeNormalizationForm`

`unicodeNormalizationForm` (default value: `nfc`)
  nfc

    When option `unicodeNormalization` has been enabled, markdown documents will be normalized using Unicode Normalization Form C (NFC) before conversion.

  nfd

    When option `unicodeNormalization` has been enabled, markdown documents will be normalized using Unicode Normalization Form D (NFD) before conversion.

  nfkc

    When option `unicodeNormalization` has been enabled, markdown documents will be normalized using Unicode Normalization Form KC (NFKC) before conversion.

  nfkd

    When option `unicodeNormalization` has been enabled, markdown documents will be normalized using Unicode Normalization Form KD (NFKD) before conversion.

#### 2.2.1.6 Option `cacheDir`

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

  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.

##### Lua Module Example

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

    \input markdown
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \directlua{
      local markdown = require("markdown")
      local convert = markdown.new({cacheDir = "cache"})
      local input = "Hello *world*!"
      tex.sprint(convert(input)) }
    \endgroup
    \bye

Create an empty directory named `cache` next to our text document. Then, invoke LuaTeX from the terminal:

    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

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

    \input markdown
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input hello
    \endgroup
    \bye

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

    Hello *world*!

Next, invoke LuaTeX from the terminal:

    markdown2tex cacheDir=cache -- hello.md hello.tex
    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.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionCacheDir{cache}
    \markdownBegin
    Hello *world*!
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    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

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

    \documentclass{article}
    \usepackage[cacheDir=cache]{markdown}
    \begin{document}
    \begin{markdown}
    Hello *world*!
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    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

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

    \usemodule[t][markdown]
    \setupmarkdown[cacheDir = cache]
    \starttext
    \startmarkdown
    Hello *world*!
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --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.

#### 2.2.1.7 Option `contentBlocksLanguageMap`

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

  The filename of the JSON file that maps filename extensions to programming language names in the iA Writer content blocks when the `contentBlocks` option is enabled.

##### LaTeX Example

Using a text editor, create a text document named `table.csv` with the following content:

    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:

    {
      "tex": "LaTeX"
    }

Create also a text document named `code.tex` with the following content:

    This is an example code listing in \LaTeX.

Create also a text document named `part.md` with the following content:

    This is a *transcluded markdown document*.

Create also a text document named `document.tex` with the following content:

    \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:

    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

>     This is an example code listing in \LaTeX.

> This is a transcluded markdown document.

##### ConTeXt Example

Using a text editor, create a text document named `table.csv` with the following content:

    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:

    {
      "tex": "ConTeXt"
    }

Create also a text document named `code.tex` with the following content:

    This is an example code listing in \ConTeXt.

Create also a text document named `part.md` with the following content:

    This is a *transcluded markdown document*.

Create also a text document named `document.tex` with the following content:

    \usemodule[t][markdown]
    \setupmarkdown
      [
        contentBlocks = yes,
        contentBlocksLanguageMap = language-map.json,
      ]
    \definetyping [ConTeXt]
    \setuptyping  [ConTeXt] [option=TEX]
    \starttext
    \startmarkdown
    /table.csv  (An example table)
    /code.tex   (An example code listing)
    /part.md    (A file transclusion example)
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex 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

>     This is an example code listing in \ConTeXt.

> This is a transcluded markdown document.

#### 2.2.1.8 Option `debugExtensionsFileName`

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

  The filename of the JSON file that will be produced when the `debugExtensions` option is enabled. This file will contain the extensible subset of the PEG grammar of markdown after built-in syntax extensions (see options `citations`, `contentBlocks`, `definitionLists`, etc.) and user-defined syntax extensions (see option `extensions`) have been applied.

#### 2.2.1.9 Option `frozenCacheFileName`

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

  A path to an output file (frozen cache) that will be created when the `finalizeCache` option is enabled and will contain a mapping between an enumeration of markdown documents and their auxiliary cache files.

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

##### Lua Module Example

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

    \input markdown
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \directlua{
      local markdown = require("markdown")
      local convert = markdown.new({finalizeCache = true, frozenCacheFileName = "cache.tex"})
      local input = "Hello *world*!"
      tex.sprint(convert(input)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    luatex document.tex

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

##### Lua CLI Example

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

    \input markdown
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input hello
    \endgroup
    \bye

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

    Hello *world*!

Next, invoke LuaTeX from the terminal:

    markdown2tex finalizeCache=true frozenCacheFileName=cache.tex -- hello.md hello.tex
    luatex document.tex

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

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionFinalizeCache{true}
    \def\markdownOptionFrozenCacheFileName{cache.tex}
    \markdownBegin
    Hello *world*!
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

Next, create a new text document `frozen-document.tex` with the following content:

    \input markdown
    \def\markdownOptionFrozenCache{true}
    \def\markdownOptionFrozenCacheFileName{cache.tex}
    \markdownBegin
    Hi *world*!
    \markdownEnd
    \bye

Last, invoke pdfTeX without shell access from the terminal:

    pdftex -no-shell-escape frozen-document.tex

A PDF document named `frozen-document.pdf` should be produced and contain the text “Hello world!” Since we used the contents of the frozen cache using the `\markdownOptionFrozenCache` option, we were able to typeset the document without accessing the shell or invoking Lua, but the change in the content of the markdown document from “Hello world!” to “Hi world!” was not reflected.

##### LaTeX Example

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

    \documentclass[finalizecache]{article}
    \usepackage[frozenCacheFileName=cache.tex]{markdown}
    \begin{document}
    \begin{markdown}
    Hello *world*!
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

Next, create a new text document `frozen-document.tex` with the following content:

    \documentclass[frozencache]{article}
    \usepackage[frozenCacheFileName=cache.tex]{markdown}
    \begin{document}
    \begin{markdown}
    Hi *world*!
    \end{markdown}
    \end{document}

Last, invoke pdfTeX without shell access from the terminal:

    pdflatex -no-shell-escape frozen-document.tex

A PDF document named `frozen-document.pdf` should be produced and contain the text “Hello world!” Since we used the contents of the frozen cache using the `frozencache` option, we were able to typeset the document without accessing the shell or invoking Lua, but the change in the content of the markdown document from “Hello world!” to “Hi world!” was not reflected.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown
      [
        finalizeCache = yes,
        frozenCacheFileName = cache.tex,
      ]
    \starttext
    \startmarkdown
    Hello *world*!
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

Next, create a new text document `frozen-document.tex` with the following content:

    \usemodule[t][markdown]
    \setupmarkdown
      [
        frozenCache = yes,
        frozenCacheFileName = cache.tex,
      ]
    \starttext
    \startmarkdown
    Hi *world*!
    \stopmarkdown
    \stoptext

Last, invoke LuaTeX from the terminal:

    context --luatex frozen-document.tex

A PDF document named `frozen-document.pdf` should be produced and contain the text “Hello world!” Since we used the contents of the frozen cache using the `\markdownOptionFrozenCache` option, we were able to typeset the document without accessing the shell or invoking Lua, but the change in the content of the markdown document from “Hello world!” to “Hi world!” was not reflected.

#### 2.2.1.10 Option `acronyms`

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

  Acronyms, initialisms, and other all-caps sequences that will be recognized in markdown text and formatted accordingly.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup {
      % Format the following words as acronyms.
      acronyms = {HTML, YAML},
      renderers = {
        % Format acronyms as small caps.
        acronym = \textsc{\MakeLowercase{#1}},
      },
    }
    \begin{document}
    \begin{markdown}

    HTML and YAML are two staples of modern tooling that often get mentioned
    in the same breath, even though they live in very different layers of the stack.

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex --shell-escape document.tex

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

> HTML and YAML are two staples of modern tooling that often get mentioned in the same breath, even though they live in very different layers of the stack.

#### 2.2.1.11 Option `autoIdentifiers`

`autoIdentifiers` (default value: `false`)
  true

    Enable the Pandoc auto identifiers syntax extension:

        The following heading received the identifier
        `sesame-street`:

        # 123 Sesame Street

  false

    Disable the Pandoc auto identifiers syntax extension.

See also the option `gfmAutoIdentifiers`.

#### 2.2.1.12 Option `blankBeforeBlockquote`

`blankBeforeBlockquote` (default value: `false`)
  true

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

  false

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

##### Lua Module Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \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)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    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

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input optionfalse
    \input optiontrue
    \endgroup
    \bye

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

    A paragraph.
    > A quote?

Next, invoke LuaTeX from the terminal:

    markdown2tex -- content.md optionfalse.tex
    markdown2tex blankBeforeBlockquote=true -- content.md optiontrue.tex
    luatex document.tex

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

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

    \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:

    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

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

    \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:

    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

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

    \usemodule[t][markdown]
    \starttext

    \startmarkdown
    A paragraph.
    > A quote.
    \stopmarkdown

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --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.

#### 2.2.1.13 Option `blankBeforeCodeFence`

`blankBeforeCodeFence` (default value: `false`)
  true

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

  false

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

##### Lua Module Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \directlua{
      local markdown = require("markdown")
      local newline = [[^^J^^J]]
      local convert, input

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

      convert = markdown.new({
        fencedCode = true, blankBeforeCodeFence = true})
      input = "A paragraph."       .. newline ..
              "```"                .. newline ..
              "Not a fenced code." .. newline ..
              "```"                .. newline
      tex.sprint(convert(input)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    luatex document.tex

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

> A paragraph.

>     A fenced code.

> A paragraph. `Not a fenced code.`

##### Lua CLI Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input optionfalse
    \input optiontrue
    \endgroup
    \bye

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

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

Next, invoke LuaTeX from the terminal:

    markdown2tex fencedCode=true -- content.md optionfalse.tex
    markdown2tex fencedCode=true blankBeforeCodeFence=true  -- content.md optiontrue.tex
    luatex document.tex

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

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

    \input markdown
    \def\markdownOptionFencedCode{true}

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

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

    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> A paragraph.

>     A fenced code.

> A paragraph. `Not a fenced code.`

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[fencedCode]{markdown}
    \begin{document}

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

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

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> A paragraph.

>     A fenced code.

> A paragraph. `Not a fenced code.`

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[fencedCode = yes]
    \starttext

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

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> A paragraph.

>     A fenced code.

> A paragraph. `Not a fenced code.`

#### 2.2.1.14 Option `blankBeforeDivFence`

`blankBeforeDivFence` (default value: `false`)
  true

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

  false

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

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[fencedDivs]{markdown}
    \begin{document}

    \begin{markdown}
    A paragraph.

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

    \begin{markdown}[blankBeforeDivFence]
    A paragraph.

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

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> A paragraph.

> A fenced div.

> A paragraph.

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

#### 2.2.1.15 Option `blankBeforeHeading`

`blankBeforeHeading` (default value: `false`)
  true

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

  false

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

##### Lua Module Example

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

    \input markdown
    \input lmfonts
    \def\markdownRendererHeadingOne#1{{\bf #1}\par}
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \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)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    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

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input optionfalse
    \input optiontrue
    \endgroup
    \bye

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

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

Next, invoke LuaTeX from the terminal:

    markdown2tex -- content.md optionfalse.tex
    markdown2tex blankBeforeHeading=true  -- content.md optiontrue.tex
    luatex document.tex

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

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

    \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:

    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

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

    \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:

    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

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

    \usemodule[t][markdown]
    \starttext

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

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --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. ==============

#### 2.2.1.16 Option `blankBeforeHtmlBlock`

`blankBeforeHtmlBlock` (default value: `false`)
  true

    Require a blank line between a paragraph and the following CommonMark HTML block.

  false

    Do not require a blank line between a paragraph and the following CommonMark HTML block.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[blankBeforeHtmlBlock]{markdown}
    \usepackage{marginnote}
    \markdownSetup{
      renderers = {
        inlineHtmlComment = \marginnote{#1},
      },
    }
    \begin{document}
    \begin{markdown}
    A useful use of block HTML comments are side notes.
    <!-- Side notes are displayed in the horizontal margins next to the relevant
    passages, which makes them *easier for the reader to find* than notes. -->
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex
    lualatex document.tex

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

> A useful use of HTML comments are side notes.

The horizontal margins should contain the following text:

> Side notes are displayed in the horizontal margins next to the relevant passages, which makes them easier for the reader to find than notes.

#### 2.2.1.17 Option `blankBeforeList`

`blankBeforeList` (default value: `false`)
  true

    Require a blank line between a paragraph and the following list.

  false

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

##### Lua Module Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \directlua{
      local markdown = require("markdown")
      local newline = [[^^J^^J]]
      local convert, input

      convert = markdown.new()
      input = "A paragraph."   .. newline ..
              "- a list"       .. newline
      tex.sprint(convert(input))

      convert = markdown.new({
        blankBeforeList = true})
      input = "A paragraph."   .. newline ..
              "- not a list"     .. newline
      tex.sprint(convert(input)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    luatex document.tex

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

> A paragraph.

> - a list

> A paragraph. - not a list

##### Lua CLI Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input optionfalse
    \input optiontrue
    \endgroup
    \bye

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

    A paragraph.
    - a list?

Next, invoke LuaTeX from the terminal:

    markdown2tex -- content.md optionfalse.tex
    markdown2tex blankBeforeList=true  -- content.md optiontrue.tex
    luatex document.tex

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

> A paragraph.

> - a list?

> A paragraph. - a list?

##### Plain TeX Example

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

    \input markdown

    \markdownBegin
    A paragraph.
    - a list
    \markdownEnd

    \def\markdownOptionBlankBeforeList{true}
    \markdownBegin
    A paragraph.
    - not a list
    \markdownEnd

    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> A paragraph.

> - a list

> A paragraph. - not a list

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \begin{document}

    \begin{markdown}
    A paragraph.
    - a list
    \end{markdown}

    \begin{markdown}[blankBeforeList]
    A paragraph.
    - not a list
    \end{markdown}

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> A paragraph.

> - a list

> A paragraph. - not a list

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \starttext

    \startmarkdown
    A paragraph.
    - a list
    \stopmarkdown

    \setupmarkdown[blankBeforeList = yes]
    \startmarkdown
    A paragraph.
    - not a list
    \stopmarkdown

    \stoptext

Next, invoke LuaTeX from the terminal:

    context document.tex

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

> A paragraph.

> - a list

> A paragraph. - not a list

#### 2.2.1.18 Option `bracketedSpans`

`bracketedSpans` (default value: `false`)
  true

    Enable the Pandoc bracketed span syntax extension:

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

  false

    Disable the Pandoc bracketed span syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[bracketedSpans]{markdown}
    \usepackage{expl3}
    \ExplSyntaxOn
    \markdownSetup{
      renderers = {
        bracketedSpanAttributeContextBegin = {
          \group_begin:
          \color_group_begin:
          \markdownSetup{
            renderers = {
              attributeKeyValue = {
                \str_if_eq:nnT
                  { ##1 }
                  { color }
                  {
                     \color_select:n { ##2 }
                  }
              },
            },
          }
        },
        bracketedSpanAttributeContextEnd = {
          \color_group_end:
          \group_end:
        },
      },
    }
    \ExplSyntaxOff
    \begin{document}
    \begin{markdown}
    Here is some [colored text]{color=red}.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> Here is some colored text.

#### 2.2.1.19 Option `breakableBlockquotes`

`breakableBlockquotes` (default value: `true`)
  true

    A blank line separates block quotes.

  false

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

##### Lua Module Example

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

    \input markdown
    \input lmfonts
    \def\markdownRendererHeadingOne#1{{\bf #1}\par}
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \directlua{
      local markdown = require("markdown")
      local newline = [[^^J^^J]]
      local convert, input

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

      convert = markdown.new()
      input = "> A block quote."       .. newline .. newline ..
              "> Another block quote." .. newline
      tex.sprint(convert(input)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    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

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input optionfalse
    \input optiontrue
    \endgroup
    \bye

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

    > A single block quote

    > or two block quotes?

Next, invoke LuaTeX from the terminal:

    markdown2tex breakableBlockquotes=false -- content.md optionfalse.tex
    markdown2tex  -- content.md optiontrue.tex
    luatex document.tex

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

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

    \input markdown

    \def\markdownOptionBreakableBlockquotes{false}
    \markdownBegin
    > A single

    > block quote.
    \markdownEnd

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

    > Another block quote.
    \markdownEnd

    \bye

Next, invoke LuaTeX from the terminal:

    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

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

    \documentclass{article}
    \usepackage{markdown}
    \begin{document}

    \begin{markdown}[breakableBlockquotes = false]
    > A single

    > block quote.
    \end{markdown}

    \begin{markdown}
    > A block quote.

    > Another block quote.
    \end{markdown}

    \end{document}

Next, invoke LuaTeX from the terminal:

    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

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

    \usemodule[t][markdown]
    \starttext

    \setupmarkdown[breakableBlockquotes = no]
    \startmarkdown
    > A single

    > block quote.
    \stopmarkdown

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

    > Another block quote.
    \stopmarkdown

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --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.

#### 2.2.1.20 Option `citationNbsps`

`citationNbsps` (default value: `true`)
  true

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

  false

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

##### LaTeX Example

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

    @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:

    \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:

    lualatex document.tex
    bibtex document.aux
    lualatex document.tex
    lualatex document.tex

A PDF document named `document.pdf` should be produced and contain the following text, where the middot (`·`) denotes a non-breaking space:

> The TeXbook [1, p.·123·and·130] is good.

> The TeXbook [1, p. 123 and 130] is good.

> ### References

> [1] Donald·Ervin Knuth. The TeXbook, volume A of Computers and typesetting. Addison-Wesley, 1984.

#### 2.2.1.21 Option `citations`

`citations` (default value: `false`)
  true

    Enable the Pandoc citation syntax extension:

        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.

##### LaTeX Example

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

    @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:

    \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:

    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.

#### 2.2.1.22 Option `codeSpans`

`codeSpans` (default value: `true`)
  true

    Enable the code span syntax:

        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.''

##### Lua Module Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \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)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    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

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input optionfalse
    \par
    \input optiontrue
    \endgroup
    \bye

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

    ``Is this a code span?'' ``Or a quote?''

Next, invoke LuaTeX from the terminal:

    markdown2tex codeSpans=false -- content.md optionfalse.tex
    markdown2tex -- content.md optiontrue.tex
    luatex document.tex

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

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

    \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:

    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

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

    \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:

    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

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

    \usemodule[t][markdown]
    \starttext

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

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --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.”

#### 2.2.1.23 Option `contentBlocks`

`contentBlocks` (default value: `false`)
  true

    Enable the iA Writer content blocks syntax extension:

        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.

##### LaTeX Example

Using a text editor, create a text document named `table.csv` with the following content:

    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:

    {
      "tex": "LaTeX"
    }

Create also a text document named `code.tex` with the following content:

    This is an example code listing in \LaTeX.

Create also a text document named `part.md` with the following content:

    This is a *transcluded markdown document*.

Create also a text document named `document.tex` with the following content:

    \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:

    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

>     This is an example code listing in \LaTeX.

> This is a transcluded markdown document.

##### ConTeXt Example

Using a text editor, create a text document named `table.csv` with the following content:

    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:

    {
      "tex": "ConTeXt"
    }

Create also a text document named `code.tex` with the following content:

    This is an example code listing in \ConTeXt.

Create also a text document named `part.md` with the following content:

    This is a *transcluded markdown document*.

Create also a text document named `document.tex` with the following content:

    \usemodule[t][markdown]
    \setupmarkdown[contentBlocks = yes]
    \definetyping [ConTeXt]
    \setuptyping  [ConTeXt] [option=TEX]
    \starttext
    \startmarkdown
    /table.csv  (An example table)
    /code.tex   (An example code listing)
    /part.md    (A file transclusion example)
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex 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

>     This is an example code listing in \ConTeXt.

> This is a transcluded markdown document.

#### 2.2.1.24 Option `contentLevel`

`contentLevel` (default value: `block`)
  block

    Treat content as a sequence of blocks.

        - this is a list
        - it contains two items

  inline

    Treat all content as inline content.

        - this is a text
        - not a list

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionContentLevel{inline}
    \markdownBegin
    - this is
    - a text
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> - this is - a text

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \begin{document}

    \begin{markdown}
    - this is
    - a list
    \end{markdown}

    \begin{markdown}[contentLevel=inline]
    - this is
    - a text
    \end{markdown}

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> - this is
> - a list

> - this is - a text

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \starttext

    \startmarkdown
    - this is
    - a list
    \stopmarkdown

    \setupmarkdown[contentLevel = inline]
    \startmarkdown
    - this is
    - a text
    \stopmarkdown

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> - this is
> - a list

> - this is - a text

#### 2.2.1.25 Option `debugExtensions`

`debugExtensions` (default value: `false`)
  true

    Produce a JSON file that will contain the extensible subset of the PEG grammar of markdown after built-in syntax extensions (see options `citations`, `contentBlocks`, `definitionLists`, etc.) and user-defined syntax extensions (see option `extensions`) have been applied. This helps you to see how the different extensions interact. The name of the produced JSON file is controlled by the `debugExtensionsFileName` option.

  false

    Do not produce a JSON file with the PEG grammar of markdown.

##### LaTeX Example

Using a text editor, create a text document named `strike-through.lua` with the following content:

    local strike_through = {
      api_version = 2,
      grammar_version = 4,
      finalize_grammar = function(reader)
        local nonspacechar = lpeg.P(1) - lpeg.S("\t ")
        local doubleslashes = lpeg.P("//")
        local function between(p, starter, ender)
          ender = lpeg.B(nonspacechar) * ender
          return (starter * #nonspacechar
                 * lpeg.Ct(p * (p - ender)^0) * ender)
        end

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

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

    return strike_through

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

    \documentclass{article}
    \usepackage{soul}
    \usepackage[extension = strike-through.lua,
                debugExtensions]{markdown}
    \begin{document}
    \begin{markdown}
    This is //a lunar roving vehicle// strike-through text.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

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

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

    {
        "Block": [
            "Blockquote",
            "Verbatim",
            "FencedCode (built-in fenced_code syntax extension)",
            "ThematicBreak",
            "BulletList",
            "OrderedList",
            "DisplayHtml",
            "Heading"
        ],
        "BlockOrParagraph": [
            "Block",
            "Paragraph",
            "Plain"
        ],
        "EndlineExceptions": [
            "EndlineExceptions (built-in fenced_code syntax extension)"
        ],
        "Inline": [
            "Str",
            "Space",
            "Endline",
            "EndlineBreak",
            "LinkAndEmph",
            "StrikeThrough (user-defined \"./strike-through.lua\" syntax extension)",
            "Code",
            "AutoLinkUrl",
            "AutoLinkEmail",
            "AutoLinkRelativeReference",
            "InlineHtml",
            "HtmlEntity",
            "EscapedChar",
            "Smart",
            "Symbol"
        ]
    }

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

#### 2.2.1.26 Option `definitionLists`

`definitionLists` (default value: `false`)
  true

    Enable the pandoc definition list syntax extension:

        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.

##### LaTeX Example

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

    \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:

    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

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

    \usemodule[t][markdown]
    \setupmarkdown[definitionLists = yes]
    \starttext
    \startmarkdown
    Term 1

    :   Definition 1

    Term 2 with *inline markup*

    :   Definition 2

            { some code, part of Definition 2 }

        Third paragraph of definition 2.
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex 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.

#### 2.2.1.27 Option `ensureJekyllData`

`ensureJekyllData` (default value: `false`)
  true

    When the `jekyllData` and `expectJekyllData` options are enabled, then a markdown document must begin directly with YAML metadata and must contain nothing but YAML metadata. Otherwise, an error is produced.

  false

    When the `jekyllData` and `expectJekyllData` options are enabled, then a markdown document may begin directly with YAML metadata and may contain nothing but YAML metadata. Otherwise, the markdown document is processed as markdown text.

#### 2.2.1.28 Option `expectJekyllData`

`expectJekyllData` (default value: `false`)
  true

    When the `jekyllData` option is enabled, then a markdown document may begin directly with YAML metadata and may contain nothing but YAML metadata.

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

  false

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

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

##### LaTeX Example

Using a text editor, create a text document named `jane-doe.yml` with the following content:

    name: Jane Doe
    age:  99

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

    \documentclass{article}
    \usepackage[jekyllData]{markdown}
    \markdownSetup{
      jekyllDataRenderers = {
        name = {\gdef\name{#1}},
        code = {\gdef\age{#1}},
      },
      renderers = {
        jekyllDataEnd = {\name{} is \age{} years old.},
      }
    }
    \begin{document}
    \markdownInput[expectJekyllData]{jane-doe.yml}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> Jane Doe is 99 years old.

#### 2.2.1.29 Option `extensions`

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

  The filenames of user-defined syntax extensions that will be applied to the markdown reader. If the `kpathsea` library is available, files will be searched for not only in the current working directory but also in the TeX directory structure.

##### LaTeX Example

Using a text editor, create a text document named `strike-through.lua` with the following content:

    local strike_through = {
      api_version = 2,
      grammar_version = 4,
      finalize_grammar = function(reader)
        local nonspacechar = lpeg.P(1) - lpeg.S("\t ")
        local doubleslashes = lpeg.P("//")
        local function between(p, starter, ender)
          ender = lpeg.B(nonspacechar) * ender
          return (starter * #nonspacechar
                 * lpeg.Ct(p * (p - ender)^0) * ender)
        end

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

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

    return strike_through

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

    \documentclass{article}
    \usepackage{soul}
    \usepackage[extension = strike-through.lua]{markdown}
    \begin{document}
    \begin{markdown}
    This is //a lunar roving vehicle// strike-through text.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

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

#### 2.2.1.30 Option `fancyLists`

`fancyLists` (default value: `false`)
  true

    Enable the Pandoc fancy list syntax extension:

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

  false

    Disable the Pandoc fancy list syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{minted}
    \usepackage[fancyLists]{markdown}
    \begin{document}
    \begin{markdown}
    a) first item
    b) second item
    c) third item
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex --shell-escape document.tex

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

> 1. first item
> 2. second item
> 3. third item

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[fancyLists = yes]
    \starttext
    \startmarkdown
    a) first item
    b) second item
    c) third item
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> 1. first item
> 2. second item
> 3. third item

#### 2.2.1.31 Option `fencedCode`

`fencedCode` (default value: `true`)
  true

    Enable the commonmark fenced code block extension:

        ~~~ 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.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{minted}
    \usepackage{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:

    lualatex --shell-escape document.tex

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

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

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

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \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:

    context --luatex document.tex

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

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

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

#### 2.2.1.32 Option `fencedCodeAttributes`

`fencedCodeAttributes` (default value: `false`)
  true

    Enable the Pandoc fenced code attribute syntax extension:

        ~~~~ {#mycode .haskell .numberLines startFrom=100}
        qsort []     = []
        qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
                       qsort (filter (>= x) xs)
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  false

    Disable the Pandoc fenced code attribute syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[fencedCode,
                fencedCodeAttributes]{markdown}
    \usepackage{minted}
    \markdownSetup{
      renderers = {
        fencedCodeAttributeContextBegin = {%
          \begingroup
          \markdownSetup{
            renderers = {
              attributeKeyValue = {%
                \setminted{{#1} = {#2}}%
              },
            },
          }%
        },
        fencedCodeAttributeContextEnd = {%
          \endgroup
        },
      },
    }
    \begin{document}
    \begin{markdown}
    ~~~ js {linenos=true}
    if (a > 3) {
        moveShip(5 * gravity, DOWN);
    }
    ~~~~~~
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex --shell-escape document.tex

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

>     1. if (a > 3) {
>     2.     moveShip(5 * gravity, DOWN);
>     3. }

#### 2.2.1.33 Option `fencedDivs`

`fencedDivs` (default value: `false`)
  true

    Enable the Pandoc fenced div syntax extension:

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

        And another.
        :::::

  false

    Disable the Pandoc fenced div syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[fencedDivs]{markdown}
    \begin{document}
    \begin{markdown}{slice=special}
    Here is a regular paragraph.

    ::::: {#special}
    Here is a special paragraph.
    :::::

    And here is another regular paragraph.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex --shell-escape document.tex

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

> Here is a special paragraph.

#### 2.2.1.34 Option `finalizeCache`

`finalizeCache` (default value: `false`)

  Whether an output file specified with the `frozenCacheFileName` option (frozen cache) that contains a mapping between an enumeration of markdown documents and their auxiliary cache files will be created.

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

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionFinalizeCache{true}
    \markdownBegin
    Hello *world*!
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

A PDF document named `document.pdf` should be produced and contain the text “Hello world!” A frozen cache will also be produced as we requested using the `finalizeCache` option.

Next, change the content of `document.tex` as follows:

    \input markdown
    \def\markdownOptionFrozenCache{true}
    \markdownBegin
    Hi *world*!
    \markdownEnd
    \bye

Last, invoke pdfTeX without shell access from the terminal:

    pdftex -no-shell-escape document.tex

A new PDF document named `document.pdf` should be produced and contain the same text “Hello world!” Since we used the contents of the frozen cache using the `\markdownOptionFrozenCache` option, we were able to typeset the document without accessing the shell or invoking Lua, but the change in the content of the markdown document from “Hello world!” to “Hi world!” was not reflected.

##### LaTeX Example

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

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

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

A PDF document named `document.pdf` should be produced and contain the text “Hello world!” A frozen cache will also be produced as we requested using the `finalizecache` option.

Next, change the content of `document.tex` as follows:

    \documentclass[frozencache]{article}
    \usepackage{markdown}
    \begin{document}
    \begin{markdown}
    Hi *world*!
    \end{markdown}
    \end{document}

Last, invoke pdfTeX without shell access from the terminal:

    pdflatex -no-shell-escape document.tex

A new PDF document named `document.pdf` should be produced and contain the same text “Hello world!” Since we used the contents of the frozen cache using the `\markdownOptionFrozenCache` option, we were able to typeset the document without accessing the shell or invoking Lua, but the change in the content of the markdown document from “Hello world!” to “Hi world!” was not reflected.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[finalizeCache = yes]
    \starttext
    \startmarkdown
    Hello *world*!
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

Next, change the content of `document.tex` as follows:

    \usemodule[t][markdown]
    \setupmarkdown[frozenCache = yes]
    \starttext
    \startmarkdown
    Hi *world*!
    \stopmarkdown
    \stoptext

Last, invoke LuaTeX from the terminal:

    context --luatex document.tex

A new PDF document named `document.pdf` should be produced and contain the same text “Hello world!” Since we used the contents of the frozen cache using the `\markdownOptionFrozenCache` option, we were able to typeset the document without accessing the shell or invoking Lua, but the change in the content of the markdown document from “Hello world!” to “Hi world!” was not reflected.

#### 2.2.1.35 Option `frozenCacheCounter`

`frozenCacheCounter` (default value: `0`)

  The number of the current markdown document that will be stored in an output file (frozen cache) when the `finalizeCache` is enabled. When the document number is 0, then a new frozen cache will be created. Otherwise, the frozen cache will be appended.

  Each frozen cache entry will define a TeX macro `\markdownFrozenCache`⟨number⟩ that will typeset markdown document number ⟨number⟩.

##### Lua Module Example

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

    \input markdown
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \directlua{
      local markdown = require("markdown")
      local firstConvert = markdown.new({finalizeCache = true, frozenCacheCounter = 0})
      local firstInput = "Hello"
      local secondConvert = markdown.new({finalizeCache = true, frozenCacheCounter = 1})
      local secondInput = "*world*!"
      tex.sprint(firstConvert(firstInput) .. [[ ]] .. secondConvert(secondInput)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    luatex document.tex

A PDF document named `document.pdf` should be produced and contain the text “Hello world!” A frozen cache with two entries will also be produced as we requested using the `frozenCacheCounter` option.

#### 2.2.1.36 Option `gfmAutoIdentifiers`

`gfmAutoIdentifiers` (default value: `false`)
  true

    Enable the Pandoc GitHub-flavored auto identifiers syntax extension:

        The following heading received the identifier
        `123-sesame-street`:

        # 123 Sesame Street

  false

    Disable the Pandoc GitHub-flavored auto identifiers syntax extension.

See also the option `autoIdentifiers`.

#### 2.2.1.37 Option `hashEnumerators`

`hashEnumerators` (default value: `false`)
  true

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

        #. Bird
        #. McHale
        #. Parish

  false

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

##### LaTeX Example

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

    \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:

    lualatex document.tex

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

> # . Bird

> # . McHale

> # . Parish

> 1. Bird
> 2. McHale
> 3. Parish

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \starttext

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

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> # . Bird

> # . McHale

> # . Parish

> 1. Bird
> 2. McHale
> 3. Parish

#### 2.2.1.38 Option `headerAttributes`

`headerAttributes` (default value: `false`)
  true

    Enable the assignment of HTML attributes to headings:

        # My first heading {#foo}

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

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

  false

    Disable the assignment of HTML attributes to headings.

#### 2.2.1.39 Option `html`

`html` (default value: `true`)
  true

    Enable the recognition of HTML entities, inline HTML tags, and block HTML elements, comments, declarations, processing instructions, and CDATA sections in the input.

    HTML entities will be replaced with the corresponding Unicode codepoints and other HTML content will be ignored by default.

  false

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

##### Lua Module Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \directlua{
      local markdown = require("markdown")
      local convert = markdown.new({html = false})
      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()
      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)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    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

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input optionfalse
    \par
    \input optiontrue
    \endgroup
    \bye

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

    <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:

    markdown2tex html=false -- content.md optionfalse.tex
    markdown2tex -- content.md optiontrue.tex
    luatex document.tex

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

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

    \input markdown
    \input lmfonts

    \def\markdownOptionHtml{false}
    \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:

    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

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

    \documentclass{article}
    \usepackage{markdown}
    \begin{document}

    \begin{markdown}[html = false]
    <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}
    <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:

    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

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

    \usemodule[t][markdown]
    \starttext

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

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --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.

#### 2.2.1.40 Option `htmlOutput`

`htmlOutput` (default value: `basic`)
  basic

    When the `html` option is enabled, produce basic coarse-grained renderers for all HTML.

  commonmark

    When the `html` option is enabled, produce fine-grained renderers for each top-level non-terminal element of CommonMark’s grammar for HTML blocks and raw HTML.

#### 2.2.1.41 Option `htmlOverLinks`

`htmlOverLinks` (default value: `false`)
  true

    When the option `html` is enabled and a text can be understood either as a hyperlink or HTML, interpret it as HTML.

    This is especially relevant when the option `relativeReferences` is enabled, since it makes e.g. `</foo>` a valid hyperlink.

  false

    When the option `html` is enabled and a text can be understood either as a hyperlink or HTML, interpret it as a hyperlink.

This is an experimental option. Whenever the option `experimental` is enabled and this option is unspecified, it will be enabled. Like other experimental options, this option will be enabled by default and soft-deprecated in the next major release of the Markdown package.

#### 2.2.1.42 Option `hybrid`

`hybrid` (default value: `false`)
  true

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

  false

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

The `hybrid` option makes it difficult to untangle TeX input from markdown text, which makes documents written with the `hybrid` option less interoperable and more difficult to read for authors. Therefore, the option has been soft-deprecated in version 3.7.1 of the Markdown package: It will never be removed but using it prints a warning and is discouraged.

Consider one of the following better alternatives for mixing TeX and markdown:

- With the `contentBlocks` option, authors can move large blocks of TeX code to separate files and include them in their markdown documents as external resources:

      Here is a mathematical formula:

       /math-formula.tex

- With the `rawAttribute` option, authors can denote raw text spans and code blocks that will be interpreted as TeX code:

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

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

- With options `texMathDollars`, `texMathSingleBackslash`, and `texMathDoubleBackslash`, authors can freely type TeX commands between dollar signs or backslash-escaped brackets:

      $H_2 O$ is a liquid.

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

##### Lua Module Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \directlua{
      local markdown = require("markdown")
      local input, convert_safe, convert_unsafe, paragraph

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

      tex.sprint(
        convert_safe(input) .. paragraph ..
        convert_unsafe(input)
      )
    }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    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

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input optionfalse
    \par
    \input optiontrue
    \endgroup
    \bye

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

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

Next, invoke LuaTeX from the terminal:

    markdown2tex -- content.md optionfalse.tex
    markdown2tex hybrid=true -- content.md optiontrue.tex
    luatex document.tex

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

> $\sqrt {-1}$ equals $i$.

> −1 equals i.

##### Plain TeX Example

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

    \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:

    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

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

    \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:

    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

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

    \usemodule[t][markdown]
    \starttext

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

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> $\sqrt {-1}$ equals $i$.

> −1 equals i.

#### 2.2.1.43 Option `inlineCodeAttributes`

`inlineCodeAttributes` (default value: `false`)
  true

    Enable the Pandoc inline code span attribute extension:

        `<$>`{.haskell}

  false

    Enable the Pandoc inline code span attribute extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[inlineCodeAttributes]{markdown}
    \usepackage{expl3}
    \ExplSyntaxOn
    \markdownSetup{
      renderers = {
        codeSpanAttributeContextBegin = {
          \group_begin:
          \color_group_begin:
          \markdownSetup{
            renderers = {
              attributeKeyValue = {
                \str_if_eq:nnT
                  { ##1 }
                  { color }
                  {
                     \color_select:n { ##2 }
                  }
              },
            },
          }
        },
        codeSpanAttributeContextEnd = {
          \color_group_end:
          \group_end:
        },
      },
    }
    \ExplSyntaxOff
    \begin{document}
    \begin{markdown}
    Here is some `colored text`{color=red}.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> Here is some `colored text`.

#### 2.2.1.44 Option `inlineNotes`

`inlineNotes` (default value: `false`)
  true

    Enable the Pandoc inline note syntax extension:

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

  false

    Disable the Pandoc inline note syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[inlineNotes]{markdown}
    \begin{document}
    \begin{markdown}
    Here is an inline note.^[Inline 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:

    lualatex document.tex

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

> Here is an inline note.2

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[inlineNotes = yes]
    \starttext
    \startmarkdown
    Here is an inline note.^[Inline 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:

    context --luatex document.tex

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

> Here is an inline note.3

#### 2.2.1.45 Option `jekyllData`

`jekyllData` (default value: `false`)

  true

  Enable the Pandoc YAML metadata block syntax extension for entering metadata in YAML:
  yaml
  title: ‘This is the title: it contains a colon’
  author:
  - Author One
  - Author Two
  keywords: [nothing, nothingness]
  abstract: |
  This is the abstract.

  It consists of two paragraphs.
  ~

  false

    Disable the Pandoc YAML metadata block syntax extension for entering metadata in YAML.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionJekyllData{true}
    \ExplSyntaxOn
    \keys_define:nn
      { markdown/jekyllData }
      {
        name .code:n = { \gdef\name{#1} },
        age  .code:n = { \gdef\age{#1}  },
      }
    \ExplSyntaxOff
    \def\markdownRendererJekyllDataEnd{%
      \name{} is \age{} years old.}
    \markdownBegin
    ---
    name: Jane Doe
    age:  99
    ---
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> Jane Doe is 99 years old.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[jekyllData]{markdown}
    \markdownSetup{
      jekyllDataRenderers = {
        name = {\gdef\name{#1}},
        code = {\gdef\age{#1}},
      },
      renderers = {
        jekyllDataEnd = {\name{} is \age{} years old.},
      }
    }
    \begin{document}

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

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> Jane Doe is 99 years old.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[jekyllData = yes]
    \ExplSyntaxOn
    \keys_define:nn
      { markdown/jekyllData }
      {
        name .code:n = { \gdef\name{#1} },
        age  .code:n = { \gdef\age{#1}  },
      }
    \ExplSyntaxOff
    \def\markdownRendererJekyllDataEnd{%
      \name{} is \age{} years old.}
    \starttext

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> Jane Doe is 99 years old.

#### 2.2.1.46 Option `linkAttributes`

`linkAttributes` (default value: `false`)
  true

    Enable the Pandoc link and image attribute syntax extension:

        An inline ![image](foo.jpg){#id .class height=20px}
        and a reference ![image][ref] with attributes.

        [ref]: foo.jpg "optional title" {#id .class key=val}

  false

    Enable the Pandoc link and image attribute syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[linkAttributes]{markdown}
    \usepackage{expl3, graphicx}
    \ExplSyntaxOn
    \markdownSetup{
      renderers = {
        imageAttributeContextBegin = {
          \group_begin:
          \markdownSetup{
            renderers = {
              attributeKeyValue = {
                \setkeys
                  { Gin }
                  { { ##1 } = { ##2 } }
              },
            },
          }
        },
        imageAttributeContextEnd = {
          \group_end:
        },
      },
    }
    \ExplSyntaxOff
    \begin{document}
    \begin{markdown}
    Here is an example image:

     ![example image](example-image){width=5cm height=4cm}
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

A PDF document named `document.pdf` should be produced and contain an example image (from Martin Scharrer’s mwe package) displayed at size 5cm × 4cm.

#### 2.2.1.47 Option `lineBlocks`

`lineBlocks` (default value: `false`)
  true

    Enable the Pandoc line block syntax extension:

        | this is a line block that
        | spans multiple
        | even
          discontinuous
        | lines

  false

    Disable the Pandoc line block syntax extension.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionLineBlocks{true}
    \markdownBegin
    | I would spread the cloths under your feet:
    | But I, being poor, have only my dreams;
    | I have spread my dreams under your feet;
    | Tread softly because you tread on my dreams.
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> I would spread the cloths under your feet:
> But I, being poor, have only my dreams;
> I have spread my dreams under your feet;
> Tread softly because you tread on my dreams.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[lineBlocks]{markdown}
    \begin{document}
    \begin{markdown}
    | I would spread the cloths under your feet:
    | But I, being poor, have only my dreams;
    | I have spread my dreams under your feet;
    | Tread softly because you tread on my dreams.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> I would spread the cloths under your feet:
> But I, being poor, have only my dreams;
> I have spread my dreams under your feet;
> Tread softly because you tread on my dreams.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[lineBlocks = yes]
    \starttext
    \startmarkdown
    | I would spread the cloths under your feet:
    | But I, being poor, have only my dreams;
    | I have spread my dreams under your feet;
    | Tread softly because you tread on my dreams.
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> I would spread the cloths under your feet:
> But I, being poor, have only my dreams;
> I have spread my dreams under your feet;
> Tread softly because you tread on my dreams.

#### 2.2.1.48 Option `mark`

`mark` (default value: `false`)
  true

    Enable the Pandoc mark syntax extension:

        This ==is highlighted text.==

  false

    Disable the Pandoc mark syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[mark]{markdown}
    \begin{document}
    \begin{markdown}

    This ==is highlighted text.==

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> This is highlighted text.

#### 2.2.1.49 Option `notes`

`notes` (default value: `false`)
  true

    Enable the Pandoc note syntax extension:

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

        [^1]: Here is the note.

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

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

                { some.code }

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

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

  false

    Disable the Pandoc note syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[notes]{markdown}
    \begin{document}
    \begin{markdown}
    Here is a note reference,[^1] and another.[^longnote]

    [^1]: Here is the note.

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

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

            { some.code }

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

    This paragraph won't be part of the note, because it
    isn't indented.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

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

>     Subsequent paragraphs are indented to show that they

> belong to the previous note.

>         { some.code }

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

> This paragraph won’t be part of the note, because it isn’t indented.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[notes = yes]
    \starttext
    \startmarkdown
    Here is a note reference,[^1] and another.[^longnote]

    [^1]: Here is the note.

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

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

            { some.code }

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

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

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

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

>     Subsequent paragraphs are indented to show that they

> belong to the previous note.

>         { some.code }

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

> This paragraph won’t be part of the note, because it isn’t indented.

#### 2.2.1.50 Option `pipeTables`

`pipeTables` (default value: `false`)
  true

    Enable the PHP Markdown pipe table syntax extension:

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

  false

    Disable the PHP Markdown pipe table syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[pipeTables]{markdown}
    \begin{document}
    \begin{markdown}
    | Right | Left | Default | Center |
    |------:|:-----|---------|:------:|
    |   12  |  12  |    12   |    12  |
    |  123  |  123 |   123   |   123  |
    |    1  |    1 |     1   |     1  |
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

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

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[pipeTables = yes]
    \starttext
    \startmarkdown
    | Right | Left | Default | Center |
    |------:|:-----|---------|:------:|
    |   12  |  12  |    12   |    12  |
    |  123  |  123 |   123   |   123  |
    |    1  |    1 |     1   |     1  |
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

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

#### 2.2.1.51 Option `preserveTabs`

`preserveTabs` (default value: `true`)
  true

    Preserve tabs in code block and fenced code blocks.

  false

    Convert any tabs in the input to spaces.

#### 2.2.1.52 Option `rawAttribute`

`rawAttribute` (default value: `false`)
  true

    Enable the Pandoc raw attribute syntax extension:

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

    To enable raw blocks, the `fencedCode` option must also be enabled:

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

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

  false

    Disable the Pandoc raw attribute syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[rawAttribute, fencedCode]{markdown}
    \usepackage{expl3}
    \begin{document}
    \begin{markdown}
    `$H_2 O$`{=tex} is a liquid.

    ``` {=html}
    <p>Here is some HTML content that will be ignored.</p>
    ```
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> H2O is a liquid.

#### 2.2.1.53 Option `relativeReferences`

`relativeReferences` (default value: `false`)
  true

    Enable relative references in autolinks:

        I conclude in Section <#conclusion>.

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

  false

    :   Disable relative references in autolinks.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[headerAttributes, relativeReferences]{markdown}
    \begin{document}
    \begin{markdown}

    I conclude in Section <#conclusion>.

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

    \end{markdown}
    \end{document}

Next, invoke LuaTeX twice from the terminal:

    lualatex document.tex
    lualatex document.tex

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

> I conclude in Section 1.

> # 1. Conclusion

> In this paper, we have discovered that most grandmas would rather eat dinner with their grandchildren than get eaten. Begone, wolf!

#### 2.2.1.54 Option `shiftHeadings`

`shiftHeadings` (default value: `0`)

  All headings will be shifted by ⟨shift amount⟩, which can be both positive and negative. Headings will not be shifted beyond level 6 or below level 1.

##### Plain TeX Example

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

    ## A section

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

    \input markdown

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

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

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

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

    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> # A section

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \begin{filecontents}[overwrite,nosearch,noheader]{example.md}
    ## A section
    \end{filecontents}
    \begin{document}
    \markdownInput[shiftHeadings=-1]{example.md}
    \markdownInput{example.md}
    \markdownInput[shiftHeadings=+1]{example.md}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> # A section

##### ConTeXt Example

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

    ## A section

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

    \usemodule[t][markdown]
    \starttext

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> # A section

#### 2.2.1.55 Option `slice`

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

  Two space-separated selectors that specify the slice of a document that will be processed, whereas the remainder of the document will be ignored. The following selectors are recognized:

  - The circumflex (`^`) selects the beginning of a document.
  - The dollar sign (`$`) selects the end of a document.
  - `^`⟨identifier⟩ selects the beginning of a section or a fenced div with the HTML attribute `#`⟨identifier⟩.
  - `$`⟨identifier⟩ selects the end of a section with the HTML attribute `#`⟨identifier⟩.
  - ⟨identifier⟩ corresponds to `^`⟨identifier⟩ for the first selector and to `$`⟨identifier⟩ for the second selector.

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

##### Plain TeX Example

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

    # The Tragedy of Hamlet
    Shakespeare's longest play.

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

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

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

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

    \input markdown
    \def\markdownOptionHeaderAttributes{true}

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

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

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

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

    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> # The Tragedy of Hamlet

> Shakespeare’s longest play.

> ## Act I

> Hamlet talks to ghost.

> ## Act III

> Hamlet kills Polonius.

> ## Act V

> Hamlet dies.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[headerAttributes]{markdown}
    \begin{filecontents}[overwrite,nosearch,noheader]{hamlet.md}
    # The Tragedy of Hamlet
    Shakespeare's longest play.

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

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

    ## Act I   {#act-1}
    Hamlet talks to ghost.
    \end{filecontents}
    \begin{document}
    \markdownInput[slice=^ ^act-3]{hamlet.md}
    \markdownInput[slice=act-1]{hamlet.md}
    \markdownInput[slice=act-3 act-5]{hamlet.md}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> # The Tragedy of Hamlet

> Shakespeare’s longest play.

> ## Act I

> Hamlet talks to ghost.

> ## Act III

> Hamlet kills Polonius.

> ## Act V

> Hamlet dies.

##### ConTeXt Example

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

    # The Tragedy of Hamlet
    Shakespeare's longest play.

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

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

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

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

    \usemodule[t][markdown]
    \setupmarkdown[headerAttributes = yes]
    \starttext

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> # The Tragedy of Hamlet

> Shakespeare’s longest play.

> ## Act I

> Hamlet talks to ghost.

> ## Act III

> Hamlet kills Polonius.

> ## Act V

> Hamlet dies.

#### 2.2.1.56 Option `smartEllipses`

`smartEllipses` (default value: `false`)
  true

    Convert any ellipses in the input to the `markdownRendererEllipsis` TeX macro.

  false

    Preserve all ellipses in the input.

##### Lua Module Example

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

    \input markdown
    \input lmfonts
    \def\markdownRendererEllipsis{. . .}
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \directlua{
      local markdown = require("markdown")
      local convert = markdown.new()
      local input = "These are just three regular dots ..."
      tex.sprint(convert(input)) }
    \par
    \directlua{
      local markdown = require("markdown")
      local convert = markdown.new({smartEllipses = true})
      local input = "... and this is a victorian ellipsis."
      tex.sprint(convert(input)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    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

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

    \input markdown
    \input lmfonts
    \def\markdownRendererEllipsis{. . .}
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input optionfalse
    \par
    \input optiontrue
    \endgroup
    \bye

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

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

Next, invoke LuaTeX from the terminal:

    markdown2tex -- content.md optionfalse.tex
    markdown2tex smartEllipses=true -- content.md optiontrue.tex
    luatex document.tex

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

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

    \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:

    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

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

    \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:

    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

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

    \usemodule[t][markdown]
    \def\markdownRendererEllipsis{. . .}
    \starttext

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

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --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.

#### 2.2.1.57 Option `startNumber`

`startNumber` (default value: `true`)
  true

    Make the number in the first item of an ordered lists significant. The item numbers will be passed to the `markdownRendererOlItemWithNumber` TeX macro.

  false

    Ignore the numbers in the ordered list items. Each item will only produce a `markdownRendererOlItem` TeX macro.

##### LaTeX Example

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

    \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:

    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

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

    \usemodule[t][markdown]
    \starttext

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

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

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

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

Next, invoke LuaTeX from the terminal:

    context --luatex 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

#### 2.2.1.58 Option `strikeThrough`

`strikeThrough` (default value: `false`)
  true

    Enable the Pandoc strike-through syntax extension:

        This ~~is deleted text.~~

  false

    Disable the Pandoc strike-through syntax extension.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionStrikeThrough{true}
    \input soul.sty
    \def\markdownRendererStrikeThrough#1{\st{#1}}
    \markdownBegin
    This is ~~a lunar roving vehicle~~ strike-through text.
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

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

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[strikeThrough]{markdown}
    \usepackage{soul}
    \markdownSetup{
      renderers = {
        strikeThrough = {\st{#1}},
      },
    }
    \begin{document}
    \begin{markdown}
    This is ~~a lunar roving vehicle~~ strike-through text.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

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

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[strikeThrough = yes]
    \def\markdownRendererStrikeThrough#1{\overstrikes{#1}}
    \starttext
    \startmarkdown
    This is ~~a lunar roving vehicle~~ strike-through text.
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

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

#### 2.2.1.59 Option `stripIndent`

`stripIndent` (default value: `false`)
  true

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

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

  false

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

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionStripIndent{true}
    \markdownBegin
        Hello *world*!
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

##### LaTeX Example

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

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

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[stripIndent = yes]
    \starttext
        \startmarkdown
            Hello *world*!
        \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

#### 2.2.1.60 Option `subscripts`

`subscripts` (default value: `false`)
  true

    Enable the Pandoc subscript syntax extension:

        H~2~O is a liquid.

  false

    Disable the Pandoc subscript syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[subscripts]{markdown}
    \begin{document}
    \begin{markdown}
    H~2~O is a liquid.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> H2O is a liquid.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[subscripts = yes]
    \starttext
    \startmarkdown
    H~2~O is a liquid.
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> H2O is a liquid.

#### 2.2.1.61 Option `superscripts`

`superscripts` (default value: `false`)
  true

    Enable the Pandoc superscript syntax extension:

        2^10^ is 1024.

  false

    Disable the Pandoc superscript syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[superscripts]{markdown}
    \begin{document}
    \begin{markdown}
    2^10^ is 1024.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> 210 is 1024.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[superscripts = yes]
    \starttext
    \startmarkdown
    2^10^ is 1024.
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> 210 is 1024.

#### 2.2.1.62 Option `tableAttributes`

`tableAttributes` (default value: `false`)
  true

    Enable the assignment of HTML attributes to table captions:

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

          : Demonstration of pipe table syntax. {#example-table}

  false

    Disable the assignment of HTML attributes to table captions.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[
      pipeTables,
      tableCaptions,
      tableAttributes,
      relativeReferences,
    ]{markdown}
    \usepackage{expl3}
    \ExplSyntaxOn
    \markdownSetup{
      renderers = {
        tableAttributeContextBegin = {
          \group_begin:
          \markdownSetup{
            renderers = {
              attributeIdentifier = {
                \markdownSetup{
                  renderers = {
                    tableAttributeContextEnd = {
                      \label{##1}
                      \group_end:
                    },
                  },
                }
              },
            },
          }
        },
        tableAttributeContextEnd = {
          \group_end:
        },
      },
    }
    \ExplSyntaxOff
    \begin{document}
    \begin{markdown}
    See Table <#example-table>.

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

      : Demonstration of pipe table syntax. {#example-table}
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> See Table 1.

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

#### 2.2.1.63 Option `tableCaptions`

`tableCaptions` (default value: `false`)
  true

    Enable the Pandoc table caption syntax extension for pipe tables:

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

          : Demonstration of pipe table syntax.

  false

    Disable the Pandoc table caption syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[pipeTables, tableCaptions]{markdown}
    \begin{document}
    \begin{markdown}
    | Right | Left | Default | Center |
    |------:|:-----|---------|:------:|
    |   12  |  12  |    12   |    12  |
    |  123  |  123 |   123   |   123  |
    |    1  |    1 |     1   |     1  |

    : Demonstration of pipe table syntax.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

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

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown
      [
        pipeTables = yes,
        tableCaptions = yes,
      ]
    \starttext
    \startmarkdown
    | Right | Left | Default | Center |
    |------:|:-----|---------|:------:|
    |   12  |  12  |    12   |    12  |
    |  123  |  123 |   123   |   123  |
    |    1  |    1 |     1   |     1  |

    : Demonstration of pipe table syntax.
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

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

#### 2.2.1.64 Option `taskLists`

`taskLists` (default value: `false`)
  true

    Enable the Pandoc task list syntax extension:

        - [ ] an unticked task list item
        - [X] a ticked task list item

    Our implementation also supports half-ticked task list items:

        - [/] a half-checked task list item
        - [.] another half-checked task list item

  false

    Disable the Pandoc task list syntax extension.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[taskLists]{markdown}
    \markdownSetup{
      renderers = {
        untickedBox = No,
        halfTickedBox = Maybe,
        tickedBox = Yes,
      },
    }
    \begin{document}
    \begin{markdown}
    - [ ] you can't.
    - [/] I can?
    - [X] I can!
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> - No you can’t.
> - Maybe I can?
> - Yes I can!

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[taskLists = yes]
    \def\markdownRendererUntickedBox{No}
    \def\markdownRendererHalftickedBox{Maybe}
    \def\markdownRendererTickedBox{Yes}
    \starttext
    \startmarkdown
    - [ ] you can't.
    - [/] I can?
    - [X] I can!
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> - No you can’t.
> - Maybe I can?
> - Yes I can!

#### 2.2.1.65 Option `texComments`

`texComments` (default value: `false`)
  true

    Strip TeX-style comments.

        \documentclass{article}
        \usepackage[texComments]{markdown}
        \begin{document}
        \begin{markdown}
        Hel%  this is a comment
           lo *world*!
        \end{markdown}
        \end{document}

    Always enabled when `hybrid` is enabled.

  false

    Do not strip TeX-style comments.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionTexComments{true}
    \markdownBegin
    Hel%  this is a comment
       lo *world*!
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[texComments]{markdown}
    \begin{document}
    \begin{markdown}
    Hel%  this is a comment
       lo *world*!
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[texComments = yes]
    \starttext
    \startmarkdown
    Hel%  this is a comment
       lo *world*!
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

#### 2.2.1.66 Option `texMathDollars`

`texMathDollars` (default value: `false`)
  true

    Enable the Pandoc dollar math syntax extension:

        inline math: $E=mc^2$

        display math: $$E=mc^2$$

  false

    Disable the Pandoc dollar math syntax extension.

##### Lua Module Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \directlua{
      local markdown = require("markdown")
      local newline = [[^^J^^J]]
      local convert = markdown.new({texMathDollars = true})
      local input =
        [[$E=mc^2$]] .. newline .. newline ..
        [[$$\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx$$]]
      tex.sprint(convert(input)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    luatex document.tex

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

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### Lua CLI Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input optionfalse
    \par
    \input optiontrue
    \endgroup
    \bye

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

    $E=mc^2$

    $$\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx$$

Next, invoke LuaTeX from the terminal:

    markdown2tex -- content.md optionfalse.tex
    markdown2tex texMathDollars=true -- content.md optiontrue.tex
    luatex document.tex

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

> $E=mc^2$

> $$\hat{f} \left ( \xi \right )= \int_{-\infty}^{\infty} f\left ( x \right ) e^{-i2\pi \xi x} dx$$

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### Plain TeX Example

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

    \input markdown

    \def\markdownOptionTexMathDollars{true}
    \markdownBegin
    $E=mc^2$

    $$\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx$$
    \markdownEnd

    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[texMathDollars]{markdown}
    \begin{document}

    \begin{markdown}
    $E=mc^2$

    $$\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx$$
    \end{markdown}

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[texMathDollars = yes]
    \starttext

    \startmarkdown
    $E=mc^2$

    $$\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx$$
    \stopmarkdown

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

#### 2.2.1.67 Option `texMathDoubleBackslash`

`texMathDoubleBackslash` (default value: `false`)
  true

    Enable the Pandoc double backslash math syntax extension:

        inline math: \\(E=mc^2\\)

        display math: \\[E=mc^2\\]

  false

    Disable the Pandoc double backslash math syntax extension.

##### Lua Module Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \directlua{
      local markdown = require("markdown")
      local newline = [[^^J^^J]]
      local convert = markdown.new({texMathDoubleBackslash = true})
      local input =
        [[\\(E=mc^2\\)]] .. newline .. newline ..
        [[\\[\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx\\]]]
      tex.sprint(convert(input)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    luatex document.tex

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

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### Lua CLI Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input optionfalse
    \par
    \input optiontrue
    \endgroup
    \bye

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

    \\(E=mc^2\\)

    \\[\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx\\]

Next, invoke LuaTeX from the terminal:

    markdown2tex -- content.md optionfalse.tex
    markdown2tex texMathDoubleBackslash=true -- content.md optiontrue.tex
    luatex document.tex

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

> \(E=mc^2\)

> \[\hat{f} \left ( \xi \right )= \int_{-\infty}^{\infty} f\left ( x \right ) e^{-i2\pi \xi x} dx\]

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### Plain TeX Example

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

    \input markdown

    \def\markdownOptionTexMathDoubleBackslash{true}
    \markdownBegin
    \\(E=mc^2\\)

    \\[\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx\\]
    \markdownEnd

    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[texMathDoubleBackslash]{markdown}
    \begin{document}

    \begin{markdown}
    \\(E=mc^2\\)

    \\[\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx\\]
    \end{markdown}

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[texMathDoubleBackslash = yes]
    \starttext

    \startmarkdown
    \\(E=mc^2\\)

    \\[\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx\\]
    \stopmarkdown

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

#### 2.2.1.68 Option `texMathSingleBackslash`

`texMathSingleBackslash` (default value: `false`)
  true

    Enable the Pandoc single backslash math syntax extension:

        inline math: \(E=mc^2\)

        display math: \[E=mc^2\]

  false

    Disable the Pandoc single backslash math syntax extension.

##### Lua Module Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \directlua{
      local markdown = require("markdown")
      local newline = [[^^J^^J]]
      local convert = markdown.new({texMathSingleBackslash = true})
      local input =
        [[\(E=mc^2\)]] .. newline .. newline ..
        [[\[\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx\]]]
      tex.sprint(convert(input)) }
    \endgroup
    \bye

Then, invoke LuaTeX from the terminal:

    luatex document.tex

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

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### Lua CLI Example

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

    \input markdown
    \input lmfonts
    \begingroup
    \catcode`\%=12
    \catcode`\#=12
    \input optionfalse
    \par
    \input optiontrue
    \endgroup
    \bye

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

    \(E=mc^2\)

    \[\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx\]

Next, invoke LuaTeX from the terminal:

    markdown2tex -- content.md optionfalse.tex
    markdown2tex texMathSingleBackslash=true -- content.md optiontrue.tex
    luatex document.tex

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

> (E=mc^2)

> [\hat{f} \left ( \xi \right )= \int_{-\infty}^{\infty} f\left ( x \right ) e^{-i2\pi \xi x} dx]

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### Plain TeX Example

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

    \input markdown

    \def\markdownOptionTexMathSingleBackslash{true}
    \markdownBegin
    \(E=mc^2\)

    \[\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx\]
    \markdownEnd

    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[texMathSingleBackslash]{markdown}
    \begin{document}

    \begin{markdown}
    \(E=mc^2\)

    \[\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx\]
    \end{markdown}

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[texMathSingleBackslash = yes]
    \starttext

    \startmarkdown
    \(E=mc^2\)

    \[\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx\]
    \stopmarkdown

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> E=mc2

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

#### 2.2.1.69 Option `tightLists`

`tightLists` (default value: `true`)
  true

    Unordered and ordered lists whose items do not consist of multiple paragraphs will be considered tight. Tight lists will produce tight renderers that may produce different output than lists that are not tight:

        - This is
        - a tight
        - unordered list.

        - This is

          not a tight

        - unordered list.

  false

    Unordered and ordered lists whose items consist of multiple paragraphs will be treated the same way as lists that consist of multiple paragraphs.

##### LaTeX Example

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

    \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:

    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

#### 2.2.1.70 Option `underscores`

`underscores` (default value: `true`)
  true

    Both underscores and asterisks can be used to denote emphasis and strong emphasis:

        *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 `hybrid` option without the need to constantly escape subscripts.

##### Plain TeX Example

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

    \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:

    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

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

    \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:

    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

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

    \usemodule[t][markdown]
    \setupmarkdown[hybrid = yes]
    \starttext

    \startmarkdown
    This is _emphasized text_ and this is a math subscript: $m\_n$.
    \stopmarkdown

    \setupmarkdown[underscores = yes]
    \startmarkdown
    This is *emphasized text* and this is a math subscript: $m_n$.
    \stopmarkdown

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --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ₙ.

### 2.2.2 Plain TeX

Plain TeX options control the communication between the TeX interface and the `markdown` Lua module. They are supported by all higher-level interfaces of the Markdown package, i.e. the plain TeX, LaTeX and ConTeXt interfaces.

#### 2.2.2.1 Setting Lua options from plain TeX

As a rule of thumb, you can set all Lua options directly from plain TeX. For example, to set the `taskLists` Lua option to `true`, you would include the following code in your plain TeX document:

    \def\markdownOptionTaskLists{true}

Alternatively, you can also set plain TeX options using the `\markdownSetup` TeX macro. For example, to set the `taskLists` Lua option to `true`, you would include the following code in your plain TeX document:

    \markdownSetup{taskLists = true}

#### 2.2.2.2 Finalizing and Freezing the Cache

The `markdownOptionFrozenCache` option uses the mapping previously created by the Lua interface `finalizeCache` option, and uses it to typeset the plain TeX document without invoking Lua. As a result, the plain TeX document becomes more portable, but further changes in the order and the content of markdown documents will not be reflected. It defaults to `false`.

The standard usage of the `finalizeCache` and `frozenCache` options is as follows:

1. Remove the `cacheDir` cache directory with stale auxiliary cache files.
2. Enable the `finalizeCache` option.
3. Typeset the plain TeX document to populate and finalize the cache.
4. Enable the `frozenCache` option.
5. Publish the source code of the plain TeX document and the `cacheDir` directory.

For more information, see the examples for the `finalizeCache` option.

#### 2.2.2.3 File and Directory Names

The plain TeX interface provides the following commands that you can use to specify the location of temporary files produced during the conversion from Markdown to TeX:

- `\markdownOptionInputTempFileName`,
- `\markdownOptionOutputDir`,
- `\markdownOptionCacheDir`, and
- `\markdownOptionFrozenCacheFileName`.

The `\markdownOptionCacheDir` and `\markdownOptionFrozenCacheFileName` commands correspond to the `cacheDir` and `frozenCacheFileName` Lua options.

Using a text editor, create a folder named `output-directory` and a text document named `document.tex` with the following content:

    \input lmfonts
    \input markdown
    \def\markdownOptionInputTempFileName{temporary-input.md}
    \def\markdownOptionOutputDir{output-directory}
    \def\markdownOptionCacheDir{output-directory/cache-directory}
    \def\markdownOptionEagerCache{true}
    \def\markdownOptionFinalizeCache{true}
    \def\markdownOptionFrozenCacheFileName{output-directory/cache-directory/frozen-cache.tex}
    \markdownBegin
    Hello *world*!
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex --output-directory output-directory document.tex

A text document named `temporary-input.md` should be produced in the folder named `output-directory` and contain the following text:

> Hello *world*!

A folder named `output-directory/cache-directory` should also be produced and contain fragments of the converted markdown document. LuaTeX does not need other temporary files to perform the conversion from markdown to TeX. To produce the remaining temporary files, invoke pdfTeX from the terminal:

    pdftex --output-directory output-directory --shell-escape document.tex

Text document named `temporary-output.md` should be produced in the folder named `output-directory`. The document will contain the input markdown document converted to TeX.

#### 2.2.2.4 No default token renderer prototypes

The Markdown package provides default definitions for token renderer prototypes using the `witiko/markdown/defaults` theme. Although these default definitions provide a useful starting point for authors, they use extra resources, especially with higher-level TeX formats such as LaTeX and ConTeXt. Furthermore, the default definitions may change at any time, which may pose a problem for maintainers of Markdown themes and templates who may require a stable output.

The `markdownOptionPlain` macro specifies whether higher-level TeX formats should only use the plain TeX default definitions or whether they should also use the format-specific default definitions. Whereas plain TeX default definitions only provide definitions for simple elements such as emphasis, strong emphasis, and paragraph separators, format-specific default definitions add support for more complex elements such as lists, tables, and citations. On the flip side, plain TeX default definitions load no extra resources and are rather stable, whereas format-specific default definitions load extra resources and are subject to a more rapid change.

Here is how you would enable the macro in a LaTeX document:

    \usepackage[plain]{markdown}

Here is how you would enable the macro in a ConTeXt document:

    \def\markdownOptionPlain{true}
    \usemodule[t][markdown]

The macro must be set before or during the loading of the package. Setting the macro after loading the package has no effect.

The `markdownOptionNoDefaults` macro specifies whether we should prevent the loading of default definitions or not. This is useful in contexts, where we want to have total control over how all elements are rendered.

Here is how you would enable the macro in a LaTeX document:

    \usepackage[noDefaults]{markdown}

Here is how you would enable the macro in a ConTeXt document:

    \def\markdownOptionNoDefaults{true}
    \usemodule[t][markdown]

The macro must be set before or during the loading of the package. Setting the macro after loading the package has no effect.

#### 2.2.2.5 Package Documentation

The `markdownOptionStripPercentSigns` macro controls whether a percent sign (`\%`) at the beginning of a line will be discarded when reading Markdown input from a TeX document. This enables the use of markdown when writing TeX package documentation using the Doc LaTeX package by Frank Mittelbach. The recognized values of the macro are `true` (discard) and `false` (retain). It defaults to `false`.

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

    % \iffalse
    \documentclass{ltxdoc}
    \usepackage[stripPercentSigns]{markdown}
    \begin{document}
    \DocInput{document.dtx}
    \end{document}
    % \fi
    %
    % \begin{markdown}
    % Hello *world*!
    % \end{markdown}

Next, invoke LuaTeX from the terminal:

    lualatex document.dtx

A PDF document named `document.pdf` should be produced and contain the text “Hello world!”

#### 2.2.2.6 Themes

User-defined themes for the Markdown package provide a domain-specific interpretation of Markdown tokens. Themes allow the authors to achieve a specific look and other high-level goals without low-level programming.

Built-in plain TeX themes provided with the Markdown package include:

`witiko/diagrams`

  A theme that typesets fenced code blocks with the infostrings `dot`, `mermaid`, and `plantuml` as figures with diagrams produced with the command `dot` from Graphviz tools, the command `mmdc` from the npm package `@mermaid-js/mermaid-cli`, and the command `plantuml` from the package PlantUML, respectively.

  The key-value attribute `caption` can be used to specify the caption of the figure and for the infostrings `dot` and `plantuml`, the key-value attribute `format` can be used to specify the output image format. The remaining attributes are treated as image attributes.

           format=svg width=12cm #dot}
               width=9cm #mermaid}
                width=7cm #plantuml}

  The theme requires a Unix-like operating system with GNU Diffutils, Graphviz, the npm package `@mermaid-js/mermaid-cli`, and PlantUML installed. All these packages are already included in the Docker image `witiko/markdown`; consult `Dockerfile` to see how they are installed. The theme also requires shell access unless the `frozenCache` plain TeX option is enabled.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[import=witiko/diagrams@v2, relativeReferences]{markdown}
    \begin{document}
    \begin{markdown}
    ``` dot {caption="An example directed graph" width=12cm #dot}
    digraph tree {
      margin = 0;
      rankdir = "LR";

      latex -> pmml;
      latex -> cmml;
      pmml -> slt;
      cmml -> opt;
      cmml -> prefix;
      cmml -> infix;
      pmml -> mterms [style=dashed];
      cmml -> mterms;

      latex [label = "LaTeX"];
      pmml [label = "Presentation MathML"];
      cmml [label = "Content MathML"];
      slt [label = "Symbol Layout Tree"];
      opt [label = "Operator Tree"];
      prefix [label = "Prefix"];
      infix [label = "Infix"];
      mterms [label = "M-Terms"];
    }
    ```

    ``` mermaid {caption="An example mindmap" width=9cm #mermaid}
    mindmap
        root )base-idea(
            sub<br/>idea 1
                ((?))
            sub<br/>idea 2
                ((?))
            sub<br/>idea 3
                ((?))
            sub<br/>idea 4
                ((?))
    ```

    ``` plantuml {caption="An example UML sequence diagram" width=7cm #plantuml}
    @startuml
    ' Define participants (actors)
    participant "Client" as C
    participant "Server" as S
    participant "Database" as DB

    ' Diagram title
    title Simple Request-Response Flow

    ' Messages
    C -> S: Send Request
    note over S: Process request

    alt Request is valid
        S -> DB: Query Data
        DB -> S: Return Data
        S -> C: Respond with Data
    else Request is invalid
        S -> C: Return Error
    end
    @enduml
    ```

    See the diagrams in figures <#dot>, <#mermaid>, and <#plantuml>.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex --shell-escape document.tex

A PDF document named `document.pdf` should be produced and contain three diagrams.

`witiko/glossaries`

  A theme that defines snippets with integrations for the LaTeX package `glossaries`.

`witiko/graphicx/http`

  A theme that adds support for downloading images whose URL has the HTTP or HTTPS protocol. The theme requires the `catchfile` LaTeX package and a Unix-like operating system with GNU Coreutils `md5sum` and either GNU Wget or cURL installed. The theme also requires shell access unless the `frozenCache` plain TeX option is enabled.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[import=witiko/graphicx/http, link_attributes]{markdown}
    \begin{document}
    \begin{markdown}
    ![img](https://github.com/witiko/markdown/raw/main/markdown.png
           "The banner of the Markdown package"){width=5in}
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex --shell-escape document.tex

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

> Figure 1: The banner of the Markdown package

`witiko/tilde`

  A theme that makes tilde (`~`) always typeset the non-breaking space even when the `hybrid` Lua option is disabled.

##### Plain TeX Example

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

    \input markdown
    \markdownSetup{import=witiko/tilde}
    \markdownBegin
    Bartel~Leendert van~der~Waerden
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

A PDF document named `document.pdf` should be produced and contain the following text, where the middot (`·`) denotes a non-breaking space:

> Bartel·Leendert van·der·Waerden

`witiko/markdown/defaults`

  A plain TeX theme with the default definitions of token renderer prototypes for plain TeX. This theme is loaded automatically together with the package and explicitly loading it has no effect.

#### 2.2.2.7 Snippets

User-defined themes provide global control over high-level goals. However, it is often desirable to change only some local aspects of a document. Snippets provide syntactic sugar for defining and invoking various options locally.

Here is how we can use snippets to store options and invoke them later in LaTeX:

    \markdownSetupSnippet{romanNumerals}{
      renderers = {
          olItemWithNumber = {%
              \item[\romannumeral#1\relax.]%
          },
      },
    }
    \begin{markdown}

    The following ordered list will be preceded by arabic numerals:

    1. wahid
    2. aithnayn

    \end{markdown}
    \begin{markdown}[snippet=romanNumerals]

    The following ordered list will be preceded by roman numerals:

    3. tres
    4. quattuor

    \end{markdown}

If the `romanNumerals` snippet were defined in the `jdoe/lists` theme, we could import the `jdoe/lists` theme and use the qualified name `jdoe/lists/romanNumerals` to invoke the snippet:

    \markdownSetup{import=jdoe/lists}
    \begin{markdown}[snippet=jdoe/lists/romanNumerals]

    The following ordered list will be preceded by roman numerals:

    3. tres
    4. quattuor

    \end{markdown}

Alternatively, we can use the extended variant of the `import` LaTeX option that allows us to import the `romanNumerals` snippet to the current namespace for easier access:

    \markdownSetup{
      import = {
        jdoe/lists = romanNumerals,
      },
    }
    \begin{markdown}[snippet=romanNumerals]

    The following ordered list will be preceded by roman numerals:

    3. tres
    4. quattuor

    \end{markdown}

Furthermore, we can also specify the name of the snippet in the current namespace, which can be different from the name of the snippet in the `jdoe/lists` theme. For example, we can make the snippet `jdoe/lists/romanNumerals` available under the name `roman`.

    \markdownSetup{
      import = {
        jdoe/lists = romanNumerals as roman,
      },
    }
    \begin{markdown}[snippet=roman]

    The following ordered list will be preceded by roman numerals:

    3. tres
    4. quattuor

    \end{markdown}

Several themes and/or snippets can be loaded at once using the extended variant of the `import` LaTeX option:

    \markdownSetup{
      import = {
        jdoe/longpackagename/lists = {
          arabic as arabic1,
          roman,
          alphabetic,
        },
        jdoe/anotherlongpackagename/lists = {
          arabic as arabic2,
        },
        jdoe/yetanotherlongpackagename,
      },
    }

### 2.2.3 LaTeX

LaTeX options allow us to disable the redefinition of the default renderer prototypes from plain TeX, load user-defined themes, and invoke user-defined set-up snippets.

#### 2.2.3.1 Setting Lua and plain TeX options from LaTeX

As a rule of thumb, we can set all Lua options directly from LaTeX. For example, to set the `taskLists` Lua option to `true`, we would include the following code in our LaTeX document:

    \markdownSetup{
      taskLists = true,
    }

We can also set all plain TeX options directly from LaTeX. For example, to set the `\markdownOptionInputTempFileName` plain TeX option to `helper-script.lua`, we would include the following code in our LaTeX document:

    \markdownSetup{
      inputTempFileName = temporary-input.md,
    }

#### 2.2.3.2 Themes

In LaTeX, we expand on the concept of themes by allowing a theme to be a full-blown LaTeX package. Specifically, the key–values `theme`=⟨theme name⟩ and `import`=⟨theme name⟩ load a LaTeX package named `markdowntheme`⟨munged theme name⟩`.sty` if it exists and a TeX document named `markdowntheme`\meta{munged theme name}`.tex` otherwise.

Having the Markdown package automatically load either the generic `.tex` theme file or the LaTeX-specific `.sty` theme file allows developers to have a single theme file, when the theme is small or the difference between TeX formats is unimportant, and scale up to separate theme files native to different TeX formats for large multi-format themes, where different code is needed for different TeX formats. To enable code reuse, developers can load the `.tex` theme file from the `.sty` theme file using the `markdownLoadPlainTeXTheme` macro.

For example, to load themes named `witiko/example/foo` and `witiko/example/bar`, you would use the following code in the preamble of your document:

    \usepackage[
      import=witiko/example/foo,
      import=witiko/example/bar,
    ]{markdown}

Due to limitations of LaTeX, themes may not be loaded after the beginning of a LaTeX document.

Built-in LaTeX themes provided with the Markdown package include:

`witiko/markdown/defaults`

  A LaTeX theme with the default definitions of token renderer prototypes for plain TeX. This theme is loaded automatically together with the package and explicitly loading it has no effect.

#### 2.2.3.3 Snippets

Built-in LaTeX snippets provided with the Markdown package include:

`witiko/glossaries/import-acronyms`

  Imports all acronyms from the LaTeX package `glossaries`, appends them to the `acronyms` option and updates the corresponding renderers to recognize these acronyms in running text and link them to the corresponding glossary entries.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{microtype, hyperref}
    \usepackage[acronym]{glossaries}
    \makeglossaries
    \newacronym{html}{HTML}{hypertext markup language}
    \newacronym{yaml}{YAML}{yet another markup language}
    \usepackage{markdown}
    \markdownSetup{
       import = witiko/glossaries@v1,
      snippet = witiko/glossaries/import-acronyms,
    }
    \begin{document}
    \begin{markdown}

    HTML and YAML are two staples of modern tooling that often get mentioned
    in the same breath, even though they live in very different layers of the stack.

    \end{markdown}
    \printacronyms
    \end{document}

Next, invoke LuaTeX and the `makeglossaries` command from the terminal:

    lualatex document.tex
    makeglossaries document
    lualatex document.tex

A PDF document named `document.pdf` should be produced and contain the following text followed by a list of acronyms with HTML and YAML being correctly linked to the corresponding list entries.

### 2.2.4 ConTeXt

#### 2.2.4.1 Themes

In ConTeXt, we expand on the concept of themes by allowing a theme to be a full-blown ConTeXt module. Specifically, the key–values `theme`=⟨theme name⟩ and `import`=⟨theme name⟩ load a ConTeXt module named `t-markdowntheme`⟨munged theme name⟩`.tex` if it exists and a TeX document named `markdowntheme`\meta{munged theme name}`.tex` otherwise.

Having the Markdown package automatically load either the generic `.tex` theme file or the ConTeXt-specific `t-*.tex` theme file allows developers to have a single theme file, when the theme is small or the difference between TeX formats is unimportant, and scale up to separate theme files native to different TeX formats for large multi-format themes, where different code is needed for different TeX formats. To enable code reuse, developers can load the `.tex` theme file from the `t-*.tex` theme file using the `markdownLoadPlainTeXTheme` macro.

For example, to load a theme named `witiko/tilde` in your document:

    \usemodule[t][markdown]
    \setupmarkdown[import=witiko/tilde]

Built-in ConTeXt themes provided with the Markdown package include:

`witiko/markdown/defaults`

  A ConTeXt theme with the default definitions of token renderer prototypes for plain TeX. This theme is loaded automatically together with the package and explicitly loading it has no effect.

## 2.3 Markdown Tokens

A key feature of the Markdown package is the support for manipulating markdown tokens, such as headings, emphasized text, links, and lists, in TeX. Instead of reducing TeX to a PDF document producer, the Markdown package allows the user to specify how every markdown token should be processed and rendered.

### 2.3.1 Token Renderers

Token renderers are user-defined TeX macros, which render markdown tokens. In this section, I will describe the individual token renderers.

#### 2.3.1.1 Acronym Renderers

The following macro is only produced when the option `acronyms` is non-empty.

`markdownRendererAcronym` represents an acronym, initialism, or another all-caps sequence. The macro receives a single attribute that corresponds to the sequence.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup {
      % Format the following words as acronyms.
      acronyms = {HTML, YAML},
      renderers = {
        % Format acronyms as small caps.
        acronym = \textsc{\MakeLowercase{#1}},
      },
    }
    \begin{document}
    \begin{markdown}

    HTML and YAML are two staples of modern tooling that often get mentioned
    in the same breath, even though they live in very different layers of the stack.

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex --shell-escape document.tex

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

> HTML and YAML are two staples of modern tooling that often get mentioned in the same breath, even though they live in very different layers of the stack.

#### 2.3.1.2 Attribute Renderers

The following macros are only produced, when at least one of the following options for markdown attributes on different elements is enabled:

- `autoIdentifiers`
- `fencedCodeAttributes`
- `gfmAutoIdentifiers`
- `headerAttributes`
- `inlineCodeAttributes`
- `linkAttributes`

`markdownRendererAttributeIdentifier` represents the ⟨identifier⟩ of a markdown element (`id="`⟨identifier⟩`"` in HTML and `#`⟨identifier⟩ in markdown attributes). The macro receives a single attribute that corresponds to the ⟨identifier⟩.

`markdownRendererAttributeClassName` represents the ⟨class name⟩ of a markdown element (`class="`⟨class name⟩ …`"` in HTML and `.`⟨class name⟩ in markdown attributes). The macro receives a single attribute that corresponds to the ⟨class name⟩.

`markdownRendererAttributeKeyValue` represents an HTML attribute in the form ⟨key⟩`=`⟨value⟩ that is neither an identifier nor a class name. The macro receives two attributes that correspond to the ⟨key⟩ and the ⟨value⟩, respectively.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[headerAttributes, underscores=false]{markdown}
    \markdownSetup{
      renderers = {
        attributeIdentifier = {%
          \par
          \emph{(Identifier: #1)}
          \par
        },
        attributeClassName = {%
          \par
          \emph{(Class name: #1)}
          \par
        },
        attributeKeyValue = {%
          \par
          \emph{(Key: #1, Value: #2)}
          \par
        },
      },
    }
    \begin{document}
    \begin{markdown}

    # First top-level heading {jane=doe}

    ## A subheading {#identifier}

    # Second top-level heading {.class_name}

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> # First top-level heading

> (Key: Jane, Value: Doe)

> ## A subheading

> (Identifier: identifier)

> # Second top-level heading

> (Class name: class_name)

#### 2.3.1.3 Basic HTML Renderers

The `markdownRendererInlineHtmlComment` macro represents the contents of an inline HTML comment. The macro receives a single argument that corresponds to the contents of the HTML comment.

The `markdownRendererInlineHtmlTag` macro represents an opening, closing, or empty inline HTML tag. The macro receives a single argument that corresponds to the contents of the HTML tag.

The `markdownRendererInputBlockHtmlElement` macro represents a block HTML element. This macro will only be produced, when the `html` option is enabled. The macro receives a single argument that filename of a file containing the contents of the HTML element.

These macros will only be produced when the `html` option is enabled and the `htmlOutput` option is set to `basic`.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \usepackage[blankBeforeHtmlBlock]{marginnote}
    \usepackage{verbatim}
    \markdownSetup{
      renderers = {
        inlineHtmlComment = \marginnote{#1},
        inlineHtmlTag = \textbf{#1},
        inputBlockHtmlElement = \verbatiminput{#1},
      },
    }
    \begin{document}
    \begin{markdown}
    A useful use of inline HTML comments are side notes.
    <!-- Side notes are displayed in the horizontal margins next to the relevant
    passages, which makes them *easier for the reader to find* than notes. -->

    <b>_Hello,_ world!</b><br/>

    <div>_Hello,_ world!</div>
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex
    lualatex document.tex

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

> A useful use of HTML comments are side notes.

> <b>Hello, world!</b><br/>

>     <div>_Hello,_ world!</div>

The horizontal margins should contain the following text:

> Side notes are displayed in the horizontal margins next to the relevant passages, which makes them easier for the reader to find than notes.

#### 2.3.1.4 Block Quote Renderers

The `markdownRendererBlockQuoteBegin` macro represents the beginning of a block quote. The macro receives no arguments.

The `markdownRendererBlockQuoteEnd` macro represents the end of a block quote. The macro receives no arguments.

##### Plain TeX Example

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

    \input markdown
    \def\markdownRendererBlockQuoteBegin{%
      \begingroup
      \vskip\parindent
      \leftskip=2\parindent
      \parindent=0pt
    }
    \def\markdownRendererBlockQuoteEnd{%
      \par
      \vskip\parindent
      \endgroup
    }
    \markdownBegin
    A quote from William Shakespeare's King Lear:

    > This is the excellent foppery of the world that when we are
    > sick in fortune---often the surfeit of our own behavior---we
    > make guilty of our disasters the sun, the moon, and the
    > stars [...]
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> A quote from William Shakespeare’s King Lear:

> > This is the excellent foppery of the world that when we are sick in fortune—often the surfeit of our own behavior—we make guilty of our disasters the sun, the moon, and the stars […]

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup{
      renderers = {
        blockQuoteBegin = {\begin{quote}},
        blockQuoteEnd = {\end{quote}},
      },
    }
    \begin{document}
    \begin{markdown}
    A quote from William Shakespeare's King Lear:

    > This is the excellent foppery of the world that when we are
    > sick in fortune---often the surfeit of our own behavior---we
    > make guilty of our disasters the sun, the moon, and the
    > stars [...]
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> A quote from William Shakespeare’s King Lear:

> > This is the excellent foppery of the world that when we are sick in fortune—often the surfeit of our own behavior—we make guilty of our disasters the sun, the moon, and the stars […]

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \def\markdownRendererBlockQuoteBegin{\startquotation}
    \def\markdownRendererBlockQuoteEnd{\stopquotation}
    \starttext
    \startmarkdown
    A quote from William Shakespeare's King Lear:

    > This is the excellent foppery of the world that when we are
    > sick in fortune---often the surfeit of our own behavior---we
    > make guilty of our disasters the sun, the moon, and the
    > stars [...]
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> A quote from William Shakespeare’s King Lear:

> > This is the excellent foppery of the world that when we are sick in fortune—often the surfeit of our own behavior—we make guilty of our disasters the sun, the moon, and the stars […]

#### 2.3.1.5 Bracketed Spans

The following macros are only produced, when the `bracketedSpans` option is enabled.

The `markdownRendererBracketedSpan` macro represents an inline bracketed span. It receives a single argument that corresponds to the inline bracketed span.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[bracketedSpans]{markdown}
    \markdownSetup{
      renderers = {
        bracketedSpan = {(#1)},
      },
    }
    \begin{document}
    \begin{markdown}

    [foo [bar]{#identifier}]{key=value} [baz]{.class_name}

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> (foo (bar)) (baz)

#### 2.3.1.6 Bracketed Span Attribute Context Renderers

The following macros are only produced, when the `bracketedSpans` option is enabled.

The `markdownRendererBracketedSpanAttributeContextBegin` and `markdownRendererBracketedSpanAttributeContextEnd` macros represent the beginning and the end of a context in which the attributes of an inline bracketed span apply. The macros receive no arguments.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[bracketedSpans]{markdown}
    \markdownSetup{
      renderers = {
        bracketedSpanAttributeContextBegin = {(},
        bracketedSpanAttributeContextEnd = {)},
      },
    }
    \begin{document}
    \begin{markdown}

    [foo [bar]{#identifier}]{key=value} [baz]{.class_name}

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> (foo (bar)) (baz)

#### 2.3.1.7 Bullet List Renderers

The `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.

The `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 `tightLists` option is disabled. The macro receives no arguments.

The `markdownRendererUlItem` macro represents an item in a bulleted list. The macro receives no arguments.

The `markdownRendererUlItemEnd` macro represents the end of an item in a bulleted list. The macro receives no arguments.

The `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.

The `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 `tightLists` option is disabled. The macro receives no arguments.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionTightLists{true}

    \def\markdownRendererInterblockSeparator{}
    \def\markdownRendererUlBeginTight{ (}
    \def\markdownRendererUlItem{%
      \def\markdownRendererUlItem{%
        ,
        \def\markdownRendererUlItem{, and }%
      }%
    }
    \def\markdownRendererUlItemEnd{}
    \def\markdownRendererUlEndTight{).}

    \markdownBegin
    This is a tight list

    - the first item
    - the second item
    - the third item
    \markdownEnd

    \def\markdownRendererInterblockSeparator{%
      :\par
      \def\markdownRendererInterblockSeparator{\par}%
    }
    \def\markdownRendererUlBegin{}
    \def\markdownRendererUlItem{--\kern 0.5em}
    \def\markdownRendererUlItemEnd{.\par}
    \def\markdownRendererUlEnd{}

    \markdownBegin
    This is a loose list

    - This is the first item

    - This is the second item

    - This is the third item
    \markdownEnd

    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> This is a tight list (the first item, the second item, and the third item).

> This is a loose list:

> - This is the first item.

> - This is the second item.

> - This is the third item.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[tightLists]{markdown}
    \begin{document}

    \begin{markdown}[
      renderers = {
        interblockSeparator = {},
        ulBeginTight = { (},
        ulItem = {%
          \def\markdownRendererUlItem{%
            ,
            \def\markdownRendererUlItem{, and }%
          }%
        },
        ulItemEnd = {},
        ulEndTight = {).},
      },
    ]
    This is a tight list

    - the first item
    - the second item
    - the third item
    \end{markdown}

    \begin{markdown}[
      renderers = {
        interblockSeparator = {%
          :\par
          \def\markdownRendererInterblockSeparator{\par}%
        },
        ulBeginTight = {\begin{itemize}},
        ulItem = {\item},
        ulItemEnd = {.},
        ulEnd = {\end{itemize}},
      },
    ]
    This is a loose list

    - This is the first item

    - This is the second item

    - This is the third item
    \end{markdown}

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> This is a tight list (the first item, the second item, and the third item).

> This is a loose list:

> - This is the first item.

> - This is the second item.

> - This is the third item.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[tightLists = yes]
    \starttext

    \def\markdownRendererInterblockSeparator{}
    \def\markdownRendererUlBeginTight{ (}
    \def\markdownRendererUlItem{%
      \def\markdownRendererUlItem{%
        ,
        \def\markdownRendererUlItem{, and }%
      }%
    }
    \def\markdownRendererUlItemEnd{}
    \def\markdownRendererUlEndTight{).}

    \startmarkdown
    This is a tight list

    - the first item
    - the second item
    - the third item
    \stopmarkdown

    \def\markdownRendererInterblockSeparator{%
      :\par
      \def\markdownRendererInterblockSeparator{\par}%
    }
    \def\markdownRendererUlBegin{\startitemize}
    \def\markdownRendererUlItem{\item}
    \def\markdownRendererUlItemEnd{.}
    \def\markdownRendererUlEnd{\stopitemize}

    \startmarkdown
    This is a loose list

    - This is the first item

    - This is the second item

    - This is the third item
    \stopmarkdown

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> This is a tight list (the first item, the second item, and the third item).

> This is a loose list:

> - This is the first item.

> - This is the second item.

> - This is the third item.

#### 2.3.1.8 Citation Renderers

The `markdownRendererCite` macro represents a string of one or more parenthetical citations. This macro will only be produced, when the `citations` option is enabled. The macro receives the parameter `{`⟨number of citations⟩`}` followed by ⟨suppress author⟩ `{`⟨prenote⟩`}{`⟨postnote⟩`}{`⟨name⟩`}` repeated ⟨number of citations⟩ times. The ⟨suppress author⟩ parameter is either the token `-`, when the author’s name is to be suppressed, or `+` otherwise.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[citations]{markdown}
    \newcount\citationsCounter
    \newcount\citationsTotal
    \makeatletter
    \def\citations#1#2#3#4{%
      a parenthesized citation \emph{#4}
      \advance\citationsCounter by 1\relax
      \ifx\relax#2\relax
        \ifx\relax#3\relax\else
          with a postfix \emph{#3}%
        \fi
      \else
        with a prefix \emph{#2}%
        \ifx\relax#3\relax\else
          \ and a postfix \emph{#3}%
        \fi
      \fi
      \ifnum\citationsCounter>\citationsTotal\relax
        .%
        \expandafter\@gobble
      \else
        , and
      \fi\citations}
    \makeatother
    \markdownSetup{
      renderers = {
        cite = {%
          \citationsCounter=1%
          \citationsTotal=#1%
          This is
          \expandafter\citations
        },
      },
    }
    \begin{document}
    \begin{markdown}
    [see @abrahams90, pp. 12; @eijkhout91, pp. 34]
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> This is a parenthesized citation abrahams90 with a prefix see and a postfix pp. 12, and a citation eijkhout91 with a postfix pp. 34.

The `markdownRendererTextCite` macro represents a string of one or more text citations. This macro will only be produced, when the `citations` option is enabled. The macro receives parameters in the same format as the `markdownRendererCite` macro.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[citations]{markdown}
    \newcount\citationsCounter
    \newcount\citationsTotal
    \makeatletter
    \def\citations#1#2#3#4{%
      a text citation \emph{#4}
      \advance\citationsCounter by 1\relax
      \ifx\relax#2\relax
        \ifx\relax#3\relax\else
          with a postfix \emph{#3}%
        \fi
      \else
        with a prefix \emph{#2}%
        \ifx\relax#3\relax\else
          \ and a postfix \emph{#3}%
        \fi
      \fi
      \ifnum\citationsCounter>\citationsTotal\relax
        .%
        \expandafter\@gobble
      \else
        , and
      \fi\citations}
    \makeatother
    \markdownSetup{
      renderers = {
        textCite = {%
          \citationsCounter=1%
          \citationsTotal=#1%
          This is
          \expandafter\citations
        },
      },
    }
    \begin{document}
    \begin{markdown}
    @abrahams90 [pp. 12; also @eijkhout91]
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> This is a text citation abrahams90 with a postfix pp. 12, and a citation eijkhout91 with a prefix also.

#### 2.3.1.9 Code Block Renderers

The `markdownRendererInputVerbatim` macro represents a code block. The macro receives a single argument that corresponds to the filename of a file containing the code block contents.

The `markdownRendererInputFencedCode` macro represents a fenced code block. This macro will only be produced, when the `fencedCode` option is enabled. The macro receives three arguments that correspond to the filename of a file containing the code block contents, the fully escaped code fence infostring that can be directly typeset, and the raw code fence infostring that can be used outside typesetting.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{verbatim}
    \usepackage[hyphens]{url}
    \usepackage[fencedCode]{markdown}
    \markdownSetup{
      renderers = {
        interblockSeparator = {
          \def\markdownRendererInterblockSeparator{%
            \par
            \def\markdownRendererInterblockSeparator{%
              \def\markdownRendererInterblockSeparator{%
                \par
              }%
            }%
          }%
        },
        inputVerbatim = {
          is contained in file \url{#1}:%
          \verbatiminput{#1}%
        },
        inputFencedCode = {
          in #2 \markdownRendererInputVerbatim{#1}%
        },
      },
    }
    \begin{document}
    \begin{markdown}
    The following code

        def foo(bar):
          if len(bar) <= 1:
            return bar[0]
          elif len(bar) == 2:
            return sorted(bar)
          else:
            baz = len(bar) // 2
            return foo(bar[baz:], bar[:baz])

    The following code

    ~~~ Python
    >>> foo([4, 2, 1, 3])
    [1, 2, 3, 4]
    ~~~~~~~~~~
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

A PDF document named `document.pdf` should be produced and contain the following text except for the filename, which may differ:

> The following code is contained in file `./_markdown_document/882453149edcf288976647f6fe147ada.verbatim`:

>     def foo(bar):
>       if len(bar) <= 1:
>         return bar[:1]
>       elif len(bar) == 2:
>         return sorted(bar)
>       else:
>         baz = bar[len(bar) // 2]
>         return (
>           foo([qux for qux in bar if qux < baz]) + [baz] +
>           foo([qux for qux in bar if qux > baz])
>         )

> The following code in Python contained in file `./_markdown_document/cf2a96e2120cef5b1fae5fea36fcc27b.verbatim`:

>     >>> foo([4, 2, 1, 3])
>     [1, 2, 3, 4]

#### 2.3.1.10 Code Span Renderer

The `markdownRendererCodeSpan` macro represents inline code span in the input text. It receives a single argument that corresponds to the inline code span.

##### Plain TeX Example

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

    \input markdown
    \input lmfonts

    \def\markdownRendererCodeSpan#1{#1}

    \markdownBegin
    `$\sqrt{-1}$ *equals* $i$`

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

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

    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

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

> $\sqrt{-1}$ equals $i$.

> −1 equals i.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[smartEllipses]{markdown}
    \markdownSetup{
      renderers = {
        codeSpan = {#1},
      },
    }
    \begin{document}

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

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

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

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

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

> $\sqrt{-1}$ equals $i$.

> −1 equals i.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \def\markdownRendererCodeSpan#1{#1}
    \starttext

    \startmarkdown
    `$\sqrt{-1}$ *equals* $i$`

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

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

    \bye

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

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

> $\sqrt{-1}$ equals $i$.

> −1 equals i.

#### 2.3.1.11 Code Span Attribute Context Renderers

The following macros are only produced, when the `inlineCodeAttributes` option is enabled.

The `markdownRendererCodeSpanAttributeContextBegin` and `markdownRendererCodeSpanAttributeContextEnd` macros represent the beginning and the end of a context in which the attributes of an inline code span apply. The macros receive no arguments.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[inlineCodeAttributes]{markdown}
    \markdownSetup{
      renderers = {
        codeSpanAttributeContextBegin = {(},
        codeSpan = {#1},
        codeSpanAttributeContextEnd = {)},
      },
    }
    \begin{document}
    \begin{markdown}

    foo `bar`{key=value} baz

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> foo (bar) baz

#### 2.3.1.12 CommonMark Block HTML Renderers

When the `html` option is enabled and `htmlOutput` is set to \opt{commonmark}, the following fine-grained renderers are produced instead of `markdownRendererInputBlockHtmlElement` to distinguish between different top-level non-terminal elements of CommonMark’s grammar for raw HTML:

1. `markdownRendererInputBlockHtmlCdataElement` – A CDATA block-level HTML element such as `<script>`, `<pre>`, `<style>`, or `<textarea>` that starts on a line of its own
2. `markdownRendererBlockHtmlComment` – A comment that starts on a line of its own
3. `markdownRendererInputBlockHtmlProcessingInstruction` – A processing instruction that starts on a line of its own
4. `markdownRendererInputBlockHtmlDeclaration` – A declaration that starts on a line of its own
5. `markdownRendererInputBlockHtmlCdataSection` – A CDATA section that starts on a line of its own
6. `markdownRendererInputBlockHtmlPcdataElement` – A PCDATA block-level HTML element that starts on a line of its own
7. `markdownRendererBlockHtmlStandaloneTag` – A non-CDATA HTML tag on a line of its own

Each of these macros receive a single argument. For all macros except 2 and 7, it is the filename of a file containing the corresponding HTML text. In contrast, macros 2 and 7 receive the text within the HTML comment and the HTML text, respectively.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \usepackage{marginnote}
    \usepackage{verbatim}
    \markdownSetup{
      htmlOutput = commonmark,
      renderers = {
        blockHtmlComment = \marginnote{#1},
      },
    }
    \begin{document}
    \begin{markdown}
    A useful use of block HTML comments are side notes.

    <!-- Side notes are displayed in the horizontal margins next to the relevant
    passages, which makes them *easier for the reader to find* than notes. -->
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex
    lualatex document.tex

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

> A useful use of HTML comments are side notes.

The horizontal margins should contain the following text:

> Side notes are displayed in the horizontal margins next to the relevant passages, which makes them easier for the reader to find than notes.

#### 2.3.1.13 CommonMark Raw HTML Renderers

When the `html` option is enabled and `htmlOutput` is set to \opt{commonmark}, the following renderers are produced instead of `markdownRendererInlineHtmlTag` to distinguish between different top-level non-terminal elements of CommonMark’s grammar for raw HTML:

- `markdownRendererInlineHtmlProcessingInstruction` – A processing instruction
- `markdownRendererInlineHtmlDeclaration` – A declaration
- `markdownRendererInlineHtmlCdataSection` – A CDATA section
- `markdownRendererInlineHtmlOpenTag` – An opening tag
- `markdownRendererInlineHtmlCloseTag` – A closing tag
- `markdownRendererInlineHtmlEmptyTag` – An empty tag

Each of these macros receives a single argument with the HTML text.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \usepackage{verbatim}
    \markdownSetup{
      htmlOutput = commonmark,
      renderers = {
        inlineHtmlOpenTag = {\textit{#1}},
        inlineHtmlCloseTag = {\textbf{#1}},
        inlineHtmlEmptyTag = {\texttt{#1}},
      },
    }
    \begin{document}
    \begin{markdown}
    <b>_Hello,_ world!</b><br/>
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex
    lualatex document.tex

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

> <b>Hello, world!</b>`<br/>`

#### 2.3.1.14 Content Block Renderers

The `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 URI that can be directly typeset, the raw URI that can be used outside typesetting, and the title of the content block.

The `markdownRendererContentBlockOnlineImage` macro represents an iA Writer online image content block. The macro receives the same arguments as `markdownRendererContentBlock`.

The `markdownRendererContentBlockCode` macro represents an iA Writer content block that was recognized as a file in a known programming language by its filename extension s. If any `markdown-languages.json` file found by `kpathsea`4 contains a record (k,v), then a non-online-image content block with the filename extension s,s`:lower()`=k is considered to be in a known programming language v. The macro receives five arguments: the local file name extension s cast to the lower case, the language v, the fully escaped URI that can be directly typeset, the raw URI that can be used outside typesetting, and the title of the content block.

Note that you will need to place place a `markdown-languages.json` file inside your working directory or inside your local TeX directory structure. In this file, you will define a mapping between filename extensions and the language names recognized by your favorite syntax highlighter; there may exist other creative uses beside syntax highlighting. The `Languages.json` file provided by Anton Sotkov is a good starting point.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionContentBlocks{true}
    \def\markdownRendererContentBlock#1#2#3#4{%
      This is {\tt #2}, #4.
    }
    \def\markdownRendererContentBlockOnlineImage#1#2#3#4{%
      This is the image {\tt #2}, #4.
    }
    \def\markdownRendererContentBlockCode#1#2#3#4#5{%
      This is the #2 (\uppercase{#1}) document {\tt #3}, #5.
    }
    \markdownBegin
    /document.tex (the document that we are currently typesetting)
    /markdown-languages.json (the mapping between filename extensions
                              and programming language names)
    https://tug.org/tugboat/noword.jpg (the logotype of TUGboat)
    \markdownEnd
    \bye

Create also a text document named `markdown-languages.json` with the following content:

    {
      "json": "JavaScript Object Notation",
    }

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> This is `document.tex`, the document that we are currently typesetting.

> This is the JavaScript Object Notation (JSON) document `markdown-languages.json`, the mapping between filename extensions and programming language names.

> This is the image `https://tug.org/tugboat/noword.jpg`, the logotype of TUGboat.

##### LaTeX Example

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

    \documentclass{article}
    \begin{filecontents}[overwrite,nosearch,noheader]{markdown-languages.json}
    {
      "json": "JavaScript Object Notation",
    }
    \end{filecontents}
    \usepackage[contentBlocks]{markdown}
    \markdownSetup{
      renderers = {
        contentBlock = {This is \texttt{#2}, #4.},
        contentBlockOnlineImage = {This is the image \texttt{#2}, #4.},
        contentBlockCode = {%
          This is the #2 (\MakeUppercase{#1}) document \texttt{#3}, #5.
        },
      },
    }
    \begin{document}
    \begin{markdown}
    /document.tex (the document that we are currently typesetting)
    /markdown-languages.json (the mapping between filename extensions
                              and programming language names)
    https://tug.org/tugboat/noword.jpg (the logotype of TUGboat)
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> This is `document.tex`, the document that we are currently typesetting.

> This is the JavaScript Object Notation (JSON) document `markdown-languages.json`, the mapping between filename extensions and programming language names.

> This is the image `https://tug.org/tugboat/noword.jpg`, the logotype of TUGboat.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[contentBlocks = yes]
    \def\markdownRendererContentBlock#1#2#3#4{%
      This is {\tt #2}, #4.
    }
    \def\markdownRendererContentBlockOnlineImage#1#2#3#4{%
      This is the image {\tt #2}, #4.
    }
    \def\markdownRendererContentBlockCode#1#2#3#4#5{%
      This is the #2 (\uppercase{#1}) document {\tt #3}, #5.
    }
    \starttext
    \startmarkdown
    /document.tex (the document that we are currently typesetting)
    /markdown-languages.json (the mapping between filename extensions
                              and programming language names)
    https://tug.org/tugboat/noword.jpg (the logotype of TUGboat)
    \stopmarkdown
    \stoptext

Create also a text document named `markdown-languages.json` with the following content:

    {
      "json": "JavaScript Object Notation",
    }

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> This is `document.tex`, the document that we are currently typesetting.

> This is the JavaScript Object Notation (JSON) document `markdown-languages.json`, the mapping between filename extensions and programming language names.

> This is the image `https://tug.org/tugboat/noword.jpg`, the logotype of TUGboat.

#### 2.3.1.15 Definition List Renderers

The following macros are only produced, when the `definitionLists` option is enabled.

The `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.

The `markdownRendererDlBeginTight` macro represents the beginning 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 `tightLists` option is disabled. The macro receives no arguments.

The `markdownRendererDlItem` macro represents a term in a definition list. The macro receives a single argument that corresponds to the term being defined.

The `markdownRendererDlItemEnd` macro represents the end of a list of definitions for a single term.

The `markdownRendererDlDefinitionBegin` macro represents the beginning of a definition in a definition list. There can be several definitions for a single term.

The `markdownRendererDlDefinitionEnd` macro represents the end of a definition in a definition list. There can be several definitions for a single term.

The `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.

The `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 `tightLists` option is disabled. The macro receives no arguments.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionDefinitionLists{true}
    \def\markdownOptionTightLists{true}

    \def\markdownRendererInterblockSeparator{%
      :%
      \def\markdownRendererInterblockSeparator{\par}%
    }
    \def\markdownRendererDlBeginTight{%
      \begingroup
      \parindent=0pt
    }
    \def\markdownRendererDlItem#1{%
      \par{\bf#1}%
      \def\markdownRendererDlDefinitionEnd{%
        ,
        \def\markdownRendererDlDefinitionEnd{%
          , and
          \def\markdownRendererDlDefinitionEnd{.}%
        }%
      }%
    }
    \def\markdownRendererDlItemEnd{}
    \def\markdownRendererDlDefinitionBegin{\par--\kern 0.5em}
    \def\markdownRendererDlEndTight{\endgroup}

    \markdownBegin
    This is a tight definition list

    Coffee
    :   black hot drink
    :   prepared from roasted coffee beans
    :   one of the most traded agricultural commodities in the world

    Milk
    :   white cold drink
    :   nutrient-rich
    :   produced on an industrial scale
    \markdownEnd

    \def\markdownRendererInterblockSeparator{%
      \def\markdownRendererInterblockSeparator{\par}%
    }
    \def\markdownRendererDlBegin{}
    \def\markdownRendererDlItem#1{%
      . #1 is a
      \def\markdownRendererDlDefinitionBegin{%
        \def\markdownRendererDlDefinitionBegin{%
          ,
          \def\markdownRendererDlDefinitionBegin{, and }%
        }%
      }%
    }
    \def\markdownRendererDlItemEnd{}
    \def\markdownRendererDlDefinitionEnd{}
    \def\markdownRendererDlEnd{.}

    \markdownBegin
    This is a loose definition list

    Coffee

    :   black hot drink

    :   prepared from roasted coffee beans

    :   one of the most traded agricultural commodities in the world

    Milk

    :   white cold drink

    :   nutrient-rich

    :   produced on an industrial scale
    \markdownEnd

    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> This is a tight definition list:

> Coffee

> - black hot drink,
> - prepared from roasted coffee beans, and
> - one of the most traded agricultural commodities in the world.

> Milk

> - white cold drink,
> - nutrient-rich, and
> - produced on an industrial scale.

> This is a loose definition list. Coffee is a black hot drink, prepared from roasted coffee beans, and one of the most traded agricultural commodities in the world. Milk is a white cold drink, nutrient-rich, and produced on an industrial scale.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[definitionLists, tightLists]{markdown}
    \begin{document}

    \begin{markdown}[
      renderers = {
        interblockSeparator = {%
          :%
          \def\markdownRendererInterblockSeparator{\par}%
        },
        dlBeginTight = {\begin{description}},
        dlItem = {%
          \item[#1]
          \begin{itemize}
          \def\markdownRendererDlDefinitionEnd{%
            ,
            \def\markdownRendererDlDefinitionEnd{%
              , and
              \def\markdownRendererDlDefinitionEnd{.}%
            }%
          }%
        },
        dlItemEnd = {\end{itemize}},
        dlDefinitionBegin = \item,
        dlEndTight = {\end{description}},
      },
    ]
    This is a tight definition list

    Coffee
    :   black hot drink
    :   prepared from roasted coffee beans
    :   one of the most traded agricultural commodities in the world

    Milk
    :   white cold drink
    :   nutrient-rich
    :   produced on an industrial scale
    \end{markdown}

    \begin{markdown}[
      renderers = {
        interblockSeparator = {%
          \def\markdownRendererInterblockSeparator{\par}%
        },
        dlBegin = {},
        dlItem = {%
          . #1 is a
          \def\markdownRendererDlDefinitionBegin{%
            \def\markdownRendererDlDefinitionBegin{%
              ,
              \def\markdownRendererDlDefinitionBegin{, and }%
            }%
          }%
        },
        dlItemEnd = {},
        dlDefinitionEnd = {},
        dlEnd = {.},
      },
    ]
    This is a loose definition list

    Coffee

    :   black hot drink

    :   prepared from roasted coffee beans

    :   one of the most traded agricultural commodities in the world

    Milk

    :   white cold drink

    :   nutrient-rich

    :   produced on an industrial scale
    \end{markdown}

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> This is a tight definition list:

> Coffee

> - black hot drink,
> - prepared from roasted coffee beans, and
> - one of the most traded agricultural commodities in the world.

> Milk

> - white cold drink,
> - nutrient-rich, and
> - produced on an industrial scale.

> This is a loose definition list. Coffee is a black hot drink, prepared from roasted coffee beans, and one of the most traded agricultural commodities in the world. Milk is a white cold drink, nutrient-rich, and produced on an industrial scale.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown
      [
        definitionLists = yes,
        tightLists = yes,
      ]
    \starttext

    \def\markdownRendererInterblockSeparator{%
      :%
      \def\markdownRendererInterblockSeparator{\par}%
    }
    \def\markdownRendererDlBeginTight{}
    \def\markdownRendererDlItem#1{%
      \par{\bf#1}%
      \startitemize
      \def\markdownRendererDlDefinitionEnd{%
        ,
        \def\markdownRendererDlDefinitionEnd{%
          , and
          \def\markdownRendererDlDefinitionEnd{.}%
        }%
      }%
    }
    \def\markdownRendererDlItemEnd{\stopitemize}
    \def\markdownRendererDlDefinitionBegin{\item}
    \def\markdownRendererDlEndTight{}

    \startmarkdown
    This is a tight definition list

    Coffee
    :   black hot drink
    :   prepared from roasted coffee beans
    :   one of the most traded agricultural commodities in the world

    Milk
    :   white cold drink
    :   nutrient-rich
    :   produced on an industrial scale
    \stopmarkdown

    \def\markdownRendererInterblockSeparator{%
      \def\markdownRendererInterblockSeparator{\par}%
    }
    \def\markdownRendererDlBegin{}
    \def\markdownRendererDlItem#1{%
      . #1 is a
      \def\markdownRendererDlDefinitionBegin{%
        \def\markdownRendererDlDefinitionBegin{%
          ,
          \def\markdownRendererDlDefinitionBegin{, and }%
        }%
      }%
    }
    \def\markdownRendererDlItemEnd{}
    \def\markdownRendererDlDefinitionEnd{}
    \def\markdownRendererDlEnd{.}

    \startmarkdown
    This is a loose definition list

    Coffee

    :   black hot drink

    :   prepared from roasted coffee beans

    :   one of the most traded agricultural commodities in the world

    Milk

    :   white cold drink

    :   nutrient-rich

    :   produced on an industrial scale
    \stopmarkdown

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> This is a tight definition list:

> Coffee

> - black hot drink,
> - prepared from roasted coffee beans, and
> - one of the most traded agricultural commodities in the world.

> Milk

> - white cold drink,
> - nutrient-rich, and
> - produced on an industrial scale.

> This is a loose definition list. Coffee is a black hot drink, prepared from roasted coffee beans, and one of the most traded agricultural commodities in the world. Milk is a white cold drink, nutrient-rich, and produced on an industrial scale.

#### 2.3.1.16 Ellipsis Renderer

The `markdownRendererEllipsis` macro replaces any occurrence of ASCII ellipses in the input text. This macro will only be produced, when the `smartEllipses` option is enabled. The macro receives no arguments.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionSmartEllipses{true}
    \def\markdownRendererEllipsis{{\it SHAZAM}!}
    \markdownBegin
    The secret word is ...
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> The secret word is SHAZAM!

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[smartEllipses]{markdown}
    \markdownSetup{
      renderers = {
        ellipsis = \emph{SHAZAM}!,
      },
    }
    \begin{document}
    \begin{markdown}
    The secret word is ...
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> The secret word is SHAZAM!

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[smartEllipses = yes]
    \def\markdownRendererEllipsis{\emph{SHAZAM}!}
    \starttext
    \startmarkdown
    The secret word is ...
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> Hello world!

> (The end of a block)

> Foo bar!

#### 2.3.1.17 Emphasis Renderers

The `markdownRendererEmphasis` macro represents an emphasized span of text. The macro receives a single argument that corresponds to the emphasized span of text.

The `markdownRendererStrongEmphasis` macro represents a strongly emphasized span of text. The macro receives a single argument that corresponds to the emphasized span of text.

##### Plain TeX Example

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

    \input markdown
    \def\markdownRendererEmphasis#1{{\it#1}}
    \def\markdownRendererStrongEmphasis#1{{\bf#1}}
    \markdownBegin
    This is *emphasis*.

    This is **strong emphasis**.
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> This is emphasis.

> This is strong emphasis.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup{
      renderers = {
        emphasis = {\emph{#1}},
        strongEmphasis = {\textbf{#1}},
      },
    }
    \begin{document}
    \begin{markdown}
    This is *emphasis*.

    This is **strong emphasis**.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> This is emphasis.

> This is strong emphasis.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \def\markdownRendererEmphasis#1{\emph{#1}}
    \def\markdownRendererStrongEmphasis#1{\bold{#1}}
    \starttext
    \startmarkdown
    This is *emphasis*.

    This is **strong emphasis**.
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> This is emphasis.

> This is strong emphasis.

#### 2.3.1.18 Fenced Code Attribute Context Renderers

The following macros are only produced, when the `fencedCode` and `fencedCodeAttributes` options are enabled.

The `markdownRendererFencedCodeAttributeContextBegin` and `markdownRendererFencedCodeAttributeContextEnd` macros represent the beginning and the end of a context in which the attributes of a fenced code apply. The macros receive no arguments.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[fencedCode,
                fencedCodeAttributes]{markdown}
    \usepackage{minted}
    \markdownSetup{
      renderers = {
        fencedCodeAttributeContextBegin = {%
          \begingroup
          \markdownSetup{
            renderers = {
              attributeKeyValue = {%
                \setminted{{#1} = {#2}}%
              },
            },
          }%
        },
        fencedCodeAttributeContextEnd = {%
          \endgroup
        },
      },
    }
    \begin{document}
    \begin{markdown}
    ~~~ js {linenos=true}
    if (a > 3) {
        moveShip(5 * gravity, DOWN);
    }
    ~~~~~~
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex --shell-escape document.tex

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

>     1. if (a > 3) {
>     2.     moveShip(5 * gravity, DOWN);
>     3. }

#### 2.3.1.19 Fenced Div Attribute Context Renderers

The following macros are only produced, when the `fencedDivs` option is enabled.

The `markdownRendererFencedDivAttributeContextBegin` and `markdownRendererFencedDivAttributeContextEnd` macros represent the beginning and the end of a context in which the attributes of a div apply. The macros receive no arguments.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[fencedDivs]{markdown}
    \markdownSetup{
      renderers = {
        fencedDivAttributeContextBegin = {%
          \par
          \emph{(The beginning of a fenced div attribute context)}
          \par
        },
        fencedDivAttributeContextEnd = {%
          \par
          \emph{(The end of a fenced div attribute context)}
          \par
        },
      },
    }
    \begin{document}
    \begin{markdown}

    ::: {key=value}

    foo

    :::: {#identifier}

    bar

    ::::

    :::

    ::: {.class_name}

    baz

    :::

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> (The beginning of a fenced div attribute context)

> foo

> (The beginning of a fenced div attribute context)

> bar

> (The end of a fenced div attribute context)

> (The end of a fenced div attribute context)

> (The beginning of a fenced div attribute context)

> baz

> (The end of a fenced div attribute context)

#### 2.3.1.20 Header Attribute Context Renderers

The following macros are only produced, when the `autoIdentifiers`, `gfmAutoIdentifiers`, or `headerAttributes` options are enabled.

The `markdownRendererHeaderAttributeContextBegin` and `markdownRendererHeaderAttributeContextEnd` macros represent the beginning and the end of a context in which the attributes of a heading apply. The macros receive no arguments.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[headerAttributes]{markdown}
    \markdownSetup{
      renderers = {
        headerAttributeContextBegin = {%
          \par
          \emph{(The beginning of a header attribute context)}
          \par
        },
        headerAttributeContextEnd = {%
          \par
          \emph{(The end of a header attribute context)}
          \par
        },
      },
    }
    \begin{document}
    \begin{markdown}

    # First top-level heading

    ## A subheading {#identifier}

    # Second top-level heading {.class_name}

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> # First top-level heading

> (The beginning of a header attribute context)

> ## A subheading

> (The end of a header attribute context)

> (The beginning of a header attribute context)

> # Second top-level heading

> (The end of a header attribute context)

#### 2.3.1.21 Heading Renderers

The `markdownRendererHeadingOne` macro represents a first level heading. The macro receives a single argument that corresponds to the heading text.

The `markdownRendererHeadingTwo` macro represents a second level heading. The macro receives a single argument that corresponds to the heading text.

The `markdownRendererHeadingThree` macro represents a third level heading. The macro receives a single argument that corresponds to the heading text.

The `markdownRendererHeadingFour` macro represents a fourth level heading. The macro receives a single argument that corresponds to the heading text.

The `markdownRendererHeadingFive` macro represents a fifth level heading. The macro receives a single argument that corresponds to the heading text.

The `markdownRendererHeadingSix` macro represents a sixth level heading. The macro receives a single argument that corresponds to the heading text.

##### Plain TeX Example

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

    \input markdown
    \def\markdownRendererInterblockSeparator{}
    \def\markdownRendererHeadingOne{1}
    \def\markdownRendererHeadingTwo{2}
    \def\markdownRendererHeadingThree{3}
    \def\markdownRendererHeadingFour{4}
    \def\markdownRendererHeadingFive{5}
    \def\markdownRendererHeadingSix{6}
    \markdownBegin
    ######
    #####
    #####
    ###
    ######
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> 65536

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup{
      renderers = {
        interblockSeparator = {},
        headingOne = 1,
        headingTwo = 2,
        headingThree = 3,
        headingFour = 4,
        headingFive = 5,
        headingSix = 6,
      },
    }
    \begin{document}
    \begin{markdown}
    ######
    #####
    #####
    ###
    ######
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> 65536

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \def\markdownRendererInterblockSeparator{}
    \def\markdownRendererHeadingOne{1}
    \def\markdownRendererHeadingTwo{2}
    \def\markdownRendererHeadingThree{3}
    \def\markdownRendererHeadingFour{4}
    \def\markdownRendererHeadingFive{5}
    \def\markdownRendererHeadingSix{6}
    \starttext
    \startmarkdown
    ######
    #####
    #####
    ###
    ######
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> 65536

#### 2.3.1.22 Image Renderer

The `markdownRendererImage` macro represents an image. It receives four arguments: the label, the fully escaped URI that can be directly typeset, the raw URI that can be used outside typesetting, and the title of the link.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \begingroup
    \catcode`\@=11
    \catcode`\%=12
    \catcode`\^^A=14
    \global\def\markdownRendererImage#1#2#3#4{^^A
      \immediate\write18{^^A

        if printf '%s' "#3" | grep -q ^http; then
          OUTPUT="$(printf '%s' "#3" | md5sum | cut -d' ' -f1).^^A
                  $(printf '%s' "#3" | sed 's/.*[.]//')";
          if ! [ -e "$OUTPUT" ]; then
            wget -O "$OUTPUT" '#3' || rm "$OUTPUT";
            convert "$OUTPUT" png:"$OUTPUT";
          fi;
          printf '%s%%' "$OUTPUT" > \jobname.fetched;
        else
          printf '%s%%' "#3"      > \jobname.fetched;
        fi^^A

      }^^A
      {^^A
        \everyeof={\noexpand}^^A
        \edef\filename{\@@input"\jobname.fetched" }^^A
        \includegraphics[width=\textwidth]{\filename}^^A
      }^^A
    }
    \endgroup
    \begin{document}
    \begin{markdown}
    ![TUGboat](https://tug.org/tugboat/noword.jpg)
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex --shell-escape document.tex

A PDF document named `document.pdf` should be produced and contain the following content. This assumes that you use a Unix-like operating system with Bourne or Bourne again shell as the default shell of the current user. It also assumes that the `md5sum`, `wget`, and `convert` binaries are installed and that the TeX engine has shell access.

> TUGboat

#### 2.3.1.23 Image Attribute Context Renderers

The following macros are only produced, when the `linkAttributes` option is enabled.

The `markdownRendererImageAttributeContextBegin` and `markdownRendererImageAttributeContextEnd` macros represent the beginning and the end of a context in which the attributes of an image apply. The macros receive no arguments.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[linkAttributes]{markdown}
    \markdownSetup{
      renderers = {
        imageAttributeContextBegin = {(},
        image = {#1},
        imageAttributeContextEnd = {)},
      },
    }
    \begin{document}
    \begin{markdown}

    foo ![bar](#bar){key=value} baz

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> foo (bar) baz

#### 2.3.1.24 Interblock Separator Renderers

The `markdownRendererInterblockSeparator` macro represents an interblock separator between two markdown block elements. The macro receives no arguments.

##### Plain TeX Example

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

    \input markdown
    \def\markdownRendererInterblockSeparator{%
      \par
      {\it(The end of a block)}%
      \par
    }
    \markdownBegin
    - Hello *world*!

    _Foo_ bar!
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> - Hello world!

> (The end of a block)

> Foo bar!

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup{
      renderers = {
        interblockSeparator = {%
          \par
          \emph{(The end of a block)}%
          \par
        },
      },
    }
    \begin{document}
    \begin{markdown}
    - Hello *world*!

    _Foo_ bar!
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> - Hello world!

> (The end of a block)

> Foo bar!

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \def\markdownRendererInterblockSeparator{%
      \par
      \emph{(The end of a block)}%
      \par
    }
    \starttext
    \startmarkdown
    - Hello *world*!

    _Foo_ bar!
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> - Hello world!

> (The end of a block)

> Foo bar!

Users can use more than one blank line to delimit two block to indicate the end of a series of blocks that make up a logical paragraph. This produces a paragraph separator instead of an interblock separator. Between some blocks, such as markdown paragraphs, a paragraph separator is always produced.

The `markdownRendererParagraphSeparator` macro represents a paragraph separator. The macro receives no arguments.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup{
      renderers = {
        paragraphSeparator = {%
          \par
          \emph{(The end of a paragraph)}%
          \par
        },
      },
    }
    \begin{document}
    \begin{markdown}
    Hello *world*!

    _Foo_ bar!
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> Hello world!

> (The end of a paragraph)

> Foo bar!

#### 2.3.1.25 Line Block Renderers

The following macros are only produced, when the `lineBlocks` option is enabled.

The `markdownRendererLineBlockBegin` and `markdownRendererLineBlockEnd` macros represent the beginning and the end of a line block. The macros receive no arguments.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionLineBlocks{true}
    \markdownBegin
    | I would spread the cloths under your feet:
    | But I, being poor, have only my dreams;
    | I have spread my dreams under your feet;
    | Tread softly because you tread on my dreams.
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> I would spread the cloths under your feet:
> But I, being poor, have only my dreams;
> I have spread my dreams under your feet;
> Tread softly because you tread on my dreams.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[lineBlocks]{markdown}
    \begin{document}
    \begin{markdown}
    | I would spread the cloths under your feet:
    | But I, being poor, have only my dreams;
    | I have spread my dreams under your feet;
    | Tread softly because you tread on my dreams.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> I would spread the cloths under your feet:
> But I, being poor, have only my dreams;
> I have spread my dreams under your feet;
> Tread softly because you tread on my dreams.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[lineBlocks = yes]
    \starttext
    \startmarkdown
    | I would spread the cloths under your feet:
    | But I, being poor, have only my dreams;
    | I have spread my dreams under your feet;
    | Tread softly because you tread on my dreams.
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> I would spread the cloths under your feet:
> But I, being poor, have only my dreams;
> I have spread my dreams under your feet;
> Tread softly because you tread on my dreams.

#### 2.3.1.26 Line Break Renderers

The `markdownRendererSoftLineBreak` macro represents a soft line break. The macro receives no arguments.

##### Plain TeX Example

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

    \input markdown
    \def\markdownRendererSoftLineBreak{%
      \par
      {\it(A soft line break)}%
      \par
    }
    \markdownInput{example.md}
    \bye

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

    Hello world!
    _Foo_ bar!

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> Hello world!

> (A soft line break)

> Foo bar!

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup{
      renderers = {
        softLineBreak = {%
          \par
          \emph{(A soft line break)}%
          \par
        },
      },
    }
    \begin{document}
    \markdownInput{example.md}
    \end{document}

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

    Hello world!
    _Foo_ bar!

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> Hello world!

> (A soft line break)

> Foo bar!

The `markdownRendererHardLineBreak` macro represents a hard line break. The macro receives no arguments.

##### Plain TeX Example

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

    \input markdown
    \def\markdownRendererHardLineBreak{%
      \par
      {\it(A hard line break)}%
      \par
    }
    \markdownInput{example.md}
    \bye

Using a text editor, create a text document named `example.md` with the following content. Note the two spaces at the end of the first line, which specify a hard line break. Due to the limitations of the TeX input processor, hard line breaks would be ignored if we typed them directly into the `document.tex` document.

    Hello world!
    _Foo_ bar!

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> Hello world!

> (A hard line break)

> Foo bar!

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup{
      renderers = {
        hardLineBreak = {%
          \par
          \emph{(A hard line break)}%
          \par
        },
      },
    }
    \begin{document}
    \markdownInput{example.md}
    \end{document}

Using a text editor, create a text document named `example.md` with the following content. Note the two spaces at the end of the first line, which specify a hard line break. Due to the limitations of the TeX input processor, hard line breaks would be ignored if we typed them directly into the `document.tex` document.

    Hello world!
    _Foo_ bar!

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> Hello world!

> (A hard line break)

> Foo bar!

#### 2.3.1.27 Link Renderer

The `markdownRendererLink` macro represents a hyperlink. It receives four arguments: the label, the fully escaped URI that can be directly typeset, the raw URI that can be used outside typesetting, and the title of the link.

##### Plain TeX Example

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

    \input markdown
    \def\markdownRendererLink#1#2#3#4{%
      #1 {\tt#2} titled {\it#4}%
    }
    \markdownBegin
    Please visit [the link][ctan].

     [ctan]: https://ctan.org/
             (the Comprehensive TeX Archive Network)
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> Please visit the link https://ctan.org/ titled the Comprehensive TeX Archive Network.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup{
      renderers = {
        link = {%
          #1 \texttt{#2} titled \emph{#4}%
        },
      },
    }
    \begin{document}
    \begin{markdown}
    Please visit [the link][ctan].

     [ctan]: https://ctan.org/
             (the Comprehensive TeX Archive Network)
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> Please visit the link https://ctan.org/ titled the Comprehensive TeX Archive Network.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \def\markdownRendererLink#1#2#3#4{%
      #1 {\tt#2} titled \emph{#4}%
    }
    \starttext
    \startmarkdown
    Please visit [the link][ctan].

     [ctan]: https://ctan.org/
             (the Comprehensive TeX Archive Network)
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> Please visit the link https://ctan.org/ titled the Comprehensive TeX Archive Network.

#### 2.3.1.28 Link Attribute Context Renderers

The following macros are only produced, when the `linkAttributes` option is enabled.

The `markdownRendererLinkAttributeContextBegin` and `markdownRendererLinkAttributeContextEnd` macros represent the beginning and the end of a context in which the attributes of a hyperlink apply. The macros receive no arguments.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[linkAttributes]{markdown}
    \markdownSetup{
      renderers = {
        linkAttributeContextBegin = {(},
        link = {#1},
        linkAttributeContextEnd = {)},
      },
    }
    \begin{document}
    \begin{markdown}

    foo [bar](#bar){key=value} baz

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> foo (bar) baz

#### 2.3.1.29 Marked Text Renderer

The following macro is only produced, when the `mark` option is enabled.

The `markdownRendererMark` macro represents a span of marked or highlighted text. The macro receives a single argument that corresponds to the marked text.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[mark]{markdown}
    \usepackage{soul}
    \markdownSetup{
      renderers = {
        mark = {\hl{#1}},
      },
    }
    \begin{document}
    \begin{markdown}

    This ==is highlighted text.==

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> This is highlighted text.

#### 2.3.1.30 Markdown Document Renderers

The `markdownRendererDocumentBegin` and `markdownRendererDocumentEnd` macros represent the beginning and the end of a markdown document. The macros receive no arguments.

A TeX document may contain any number of markdown documents. Additionally, markdown documents may appear not only in a sequence, but several markdown documents may also be nested. Redefinitions of the macros should take this into account.

##### LaTeX Example

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

    This is a *nested* markdown document.

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

    \documentclass{article}
    \usepackage[contentBlocks]{markdown}
    \markdownSetup{
      renderers = {
        contentBlock = {%
          \markdownInput{#3}%
        },
        documentBegin = {%
          \par
          \emph{(The beginning of a document)}
          \par
          \begingroup
          \markdownSetup{snippet=first-nesting-level}%
        },
        documentEnd = {%
          \endgroup
          \par
          \emph{(The end of a document)}
          \par
        },
      },
    }
    \markdownSetupSnippet{first-nesting-level}{
      renderers = {
        documentBegin = {
          \par
          \emph{(The beginning of a nested document)}
          \par
          \begingroup
          \markdownSetup{snippet=second-nesting-level-and-below}
        },
      },
    }
    \markdownSetupSnippet{second-nesting-level-and-below}{
      renderers = {
        documentBegin = {
          \par
          \emph{(The beginning of a nested document)}
          \par
          \begingroup
        },
        documentEnd = {
          \endgroup
          \par
          \emph{(The end of a nested document)}
          \par
        },
      },
    }
    \begin{document}
    \begin{markdown}
    Hello *world*!

    /nested.md

    _Foo_ bar!
    \end{markdown}
    \begin{markdown}

    Bar baz!

    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> (The beginning of a document)

> Hello world!

> (The beginning of a nested document)

> This is a nested markdown document.

> (The end of a nested document)

> Foo bar!

> (The end of a document)

> (The beginning of a document)

> Bar baz!

> (The end of a document)

#### 2.3.1.31 Non-Breaking Space Renderer

The `markdownRendererNbsp` macro represents a non-breaking space.

##### LaTeX Example

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

    @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:

    \documentclass{article}
    \usepackage[
      citations,
      citationNbsps,
    ]{markdown}
    \markdownSetup{
      renderers = {
        nbsp = {$\cdot$},
      },
    }
    \begin{document}

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

    \bibliographystyle{plain}
    \bibliography{document.bib}

    \end{document}

Next, invoke LuaTeX and BibTeX from the terminal:

    lualatex document.tex
    bibtex document.aux
    lualatex document.tex
    lualatex document.tex

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

> The TeXbook [1, p.·123·and·130] is good.

> ### References

> [1] Donald Ervin Knuth. The TeXbook, volume A of Computers and typesetting. Addison-Wesley, 1984.

#### 2.3.1.32 Note Renderer

The `markdownRendererNote` macro represents a note. This macro will only be produced, when the `notes` option is enabled. The macro receives a single argument that corresponds to the note text.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionNotes{true}
    \def\markdownRendererNote#1{ (and \lowercase{#1})}
    \markdownBegin
    This is some text[^1] and this is some other text[^2].

     [^1]: this is a note

     [^2]: this is some other note
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> This is some text (and this is a note) and this is some other text (and this is some other note).

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[notes]{markdown}
    \markdownSetup{
      renderers = {
        note = { (and \MakeLowercase{#1})},
      },
    }
    \begin{document}
    \begin{markdown}
    This is some text[^1] and this is some other text[^2].

     [^1]: this is a note

     [^2]: this is some other note
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> This is some text (and this is a note) and this is some other text (and this is some other note).

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[notes = yes]
    \def\markdownRendererNote#1{ (and \lowercase{#1})}
    \starttext
    \startmarkdown
    This is some text[^1] and this is some other text[^2].

     [^1]: this is a note

     [^2]: this is some other note
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> This is some text (and this is a note) and this is some other text (and this is some other note).

#### 2.3.1.33 Ordered List Renderers

The `markdownRendererOlBegin` macro represents the beginning of an ordered list that contains an item with several paragraphs of text (the list is not tight). This macro will only be produced, when the `fancyLists` option is disabled. The macro receives no arguments.

The `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 `tightLists` option is enabled and the `fancyLists` option is disabled. The macro receives no arguments.

The `markdownRendererFancyOlBegin` macro represents the beginning of a fancy ordered list that contains an item with several paragraphs of text (the list is not tight). This macro will only be produced, when the `fancyLists` option is enabled. The macro receives two arguments: the style of the list item labels (`Decimal`, `LowerRoman`, `UpperRoman`, `LowerAlpha`, and `UpperAlpha`), and the style of delimiters between list item labels and texts (`Default`, `OneParen`, and `Period`).

The `markdownRendererFancyOlBeginTight` macro represents the beginning of a fancy ordered list that contains no item with several paragraphs of text (the list is tight). This macro will only be produced, when the `fancyLists` and `tightLists` options are enabled. The macro receives two arguments: the style of the list item labels, and the style of delimiters between list item labels and texts. See the `markdownRendererFancyOlBegin` macro for the valid style values.

The `markdownRendererOlItem` macro represents an item in an ordered list. This macro will only be produced, when the `startNumber` option is disabled and the `fancyLists` option is disabled. The macro receives no arguments.

The `markdownRendererOlItemEnd` macro represents the end of an item in an ordered list. This macro will only be produced, when the `fancyLists` option is disabled. The macro receives no arguments.

The `markdownRendererOlItemWithNumber` macro represents an item in an ordered list. This macro will only be produced, when the `startNumber` option is enabled and the `fancyLists` option is disabled. The macro receives a single numeric argument that corresponds to the item number.

The `markdownRendererFancyOlItem` macro represents an item in a fancy ordered list. This macro will only be produced, when the `startNumber` option is disabled and the `fancyLists` option is enabled. The macro receives no arguments.

The `markdownRendererFancyOlItemEnd` macro represents the end of an item in a fancy ordered list. This macro will only be produced, when the `fancyLists` option is enabled. The macro receives no arguments.

The `markdownRendererFancyOlItemWithNumber` macro represents an item in a fancy ordered list. This macro will only be produced, when the `startNumber` and `fancyLists` options are enabled. The macro receives a single numeric argument that corresponds to the item number.

The `markdownRendererOlEnd` macro represents the end of an ordered list that contains an item with several paragraphs of text (the list is not tight). This macro will only be produced, when the `fancyLists` option is disabled. The macro receives no arguments.

The `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 `tightLists` option is enabled and the `fancyLists` option is disabled. The macro receives no arguments.

The `markdownRendererFancyOlEnd` macro represents the end of a fancy ordered list that contains an item with several paragraphs of text (the list is not tight). This macro will only be produced, when the `fancyLists` option is enabled. The macro receives no arguments.

The `markdownRendererFancyOlEndTight` macro represents the end of a fancy ordered list that contains no item with several paragraphs of text (the list is tight). This macro will only be produced, when the `fancyLists` and `tightLists` options are enabled. The macro receives no arguments.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionTightLists{true}
    \def\markdownOptionStartNumber{true}

    \def\markdownRendererInterblockSeparator{}
    \def\markdownRendererOlBeginTight{ (}
    \def\markdownRendererOlItemWithNumber#1{%
      \ifnum #1=1\relax
        the first
      \else
        \ifnum #1=2\relax
          , the second
        \else
          , and the third
        \fi
      \fi
    }
    \def\markdownRendererOlItemEnd{}
    \def\markdownRendererOlEndTight{).}

    \markdownBegin
    This is a tight list

    1. item
    2. item
    3. item
    \markdownEnd

    \def\markdownRendererInterblockSeparator{%
      :\par
      \def\markdownRendererInterblockSeparator{\par}%
    }
    \def\markdownRendererOlBegin{}
    \def\markdownRendererOlItemWithNumber#1{%
      #1.\kern 0.5em%
      This is the
      \ifnum #1=1\relax
        first
      \else
        \ifnum #1=2\relax
          second
        \else
          third
        \fi
      \fi
    }
    \def\markdownRendererOlItemEnd{.\par}
    \def\markdownRendererOlEnd{}

    \markdownBegin
    This is a loose list

    1. item

    2. item

    3. item
    \markdownEnd

    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> This is a tight list (the first item, the second item, and the third item).

> This is a loose list:

> 1. This is the first item.

> 2. This is the second item.

> 3. This is the third item.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[tightLists, startNumber]{markdown}
    \begin{document}

    \begin{markdown}[
      renderers = {
        interblockSeparator = {},
        olBeginTight = { (},
        olItemWithNumber = {%
          \ifnum #1=1\relax
            the first
          \else
            \ifnum #1=2\relax
              , the second
            \else
              , and the third
            \fi
          \fi
        },
        olItemEnd = {},
        olEndTight = {).},
      },
    ]
    This is a tight list

    1. item
    2. item
    3. item
    \end{markdown}

    \begin{markdown}[
      renderers = {
        interblockSeparator = {%
          :\par
          \def\markdownRendererInterblockSeparator{\par}%
        },
        olBeginTight = {\begin{enumerate}},
        olItemWithNumber = {%
          \item This is the
          \ifnum #1=1\relax
            first
          \else
            \ifnum #1=2\relax
              second
            \else
              third
            \fi
          \fi
        },
        olItemEnd = {.},
        olEnd = {\end{enumerate}},
      },
    ]
    This is a loose list

    1. item

    2. item

    3. item
    \end{markdown}

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> This is a tight list (the first item, the second item, and the third item).

> This is a loose list:

> 1. This is the first item.

> 2. This is the second item.

> 3. This is the third item.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown
      [
        tightLists = yes,
        startNumber = yes,
      ]
    \starttext

    \def\markdownRendererInterblockSeparator{}
    \def\markdownRendererOlBeginTight{ (}
    \def\markdownRendererOlItemWithNumber#1{%
      \ifnum #1=1\relax
        the first
      \else
        \ifnum #1=2\relax
          , the second
        \else
          , and the third
        \fi
      \fi
    }
    \def\markdownRendererOlItemEnd{}
    \def\markdownRendererOlEndTight{).}

    \startmarkdown
    This is a tight list

    1. item
    2. item
    3. item
    \stopmarkdown

    \def\markdownRendererInterblockSeparator{%
      :\par
      \def\markdownRendererInterblockSeparator{\par}%
    }
    \def\markdownRendererOlBegin{\startitemize}
    \def\markdownRendererOlItemWithNumber#1{%
      \sym{#1.}
      This is the
      \ifnum #1=1\relax
        first
      \else
        \ifnum #1=2\relax
          second
        \else
          third
        \fi
      \fi
    }
    \def\markdownRendererOlItemEnd{.\par}
    \def\markdownRendererOlEnd{\stopitemize}

    \startmarkdown
    This is a loose list

    1. item

    2. item

    3. item
    \stopmarkdown

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> This is a tight list (the first item, the second item, and the third item).

> This is a loose list:

> 1. This is the first item.

> 2. This is the second item.

> 3. This is the third item.

#### 2.3.1.34 Raw Content Renderers

The `markdownRendererInputRawInline` macro represents an inline raw span. The macro receives two arguments: the filename of a file containing the inline raw span contents and the raw attribute that designates the format of the inline raw span. This macro will only be produced, when the `rawAttribute` option is enabled.

The `markdownRendererInputRawBlock` macro represents a raw block. The macro receives two arguments: the filename of a file containing the raw block and the raw attribute that designates the format of the raw block. This macro will only be produced, when the `rawAttribute` and `fencedCode` options are enabled.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[rawAttribute, fencedCode]{markdown}
    \usepackage{expl3}
    \ExplSyntaxOn
    \cs_new:Nn
      \display_raw_content:nn
      {
        % If the raw attribute is TeX, execute the content as a TeX document.
        \str_if_eq:nnTF
          { #2 }
          { tex }
          { \markdownEscape { #1 } }
          % Otherwise, ignore the content.
          { }
      }
    \markdownSetup{
      renderers = {
        rawInline = { \display_raw_content:nn { #1 } { #2 } },
        rawBlock  = { \display_raw_content:nn { #1 } { #2 } }
      },
    }
    \ExplSyntaxOff
    \begin{document}
    \begin{markdown}
    `$H_2 O$`{=tex} is a liquid.

    ``` {=html}
    <p>Here is some HTML content that will be ignored.</p>
    ```
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> H2O is a liquid.

#### 2.3.1.35 Section Renderers

The `markdownRendererSectionBegin` and `markdownRendererSectionEnd` macros represent the beginning and the end of a section based on headings.

#### 2.3.1.36 Replacement Character Renderers

The `markdownRendererReplacementCharacter` macro represents the U+0000 and U+FFFD Unicode characters. The macro receives no arguments.

#### 2.3.1.37 Special Character Renderers

The following macros replace any special plain TeX characters, including the active pipe character (`|`) of ConTeXt, in the input text:

- `markdownRendererAmpersand` replaces the ampersand (`&`).
- `markdownRendererBackslash` replaces the backslash (`\`).
- `markdownRendererCircumflex` replaces the circumflex (`^`).
- `markdownRendererDollarSign` replaces the dollar sign (`$`).
- `markdownRendererHash` replaces the hash sign (`#`).
- `markdownRendererLeftBrace` replaces the left brace (`{`).
- `markdownRendererPercentSign` replaces the percent sign (`%`).
- `markdownRendererPipe` replaces the pipe character (`|`).
- `markdownRendererRightBrace` replaces the right brace (`}`).
- `markdownRendererTilde` replaces the tilde (`~`).
- `markdownRendererUnderscore` replaces the underscore (`_`).

##### Plain TeX Example

Using a text editor, create a text document named `document.tex` with the following content. We will make the tilde behave as if it were written in TeX, where it represents a non-breaking space.

    \input markdown
    \def\markdownRendererTilde{~}
    \markdownBegin
    Bartel~Leendert van~der~Waerden
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

A PDF document named `document.pdf` should be produced and contain the following text, where the middot (`·`) denotes a non-breaking space:

> Bartel·Leendert van·der·Waerden

##### LaTeX Example

Using a text editor, create a text document named `document.tex` with the following content. We will make the tilde behave as if it were written in TeX, where it represents a non-breaking space.

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup{
      renderers = {
        tilde = ~,
      },
    }
    \begin{document}
    \begin{markdown}
    Bartel~Leendert van~der~Waerden
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

A PDF document named `document.pdf` should be produced and contain the following text, where the middot (`·`) denotes a non-breaking space:

> Bartel·Leendert van·der·Waerden

##### ConTeXt Example

Using a text editor, create a text document named `document.tex` with the following content. We will make the tilde behave as if it were written in TeX, where it represents a non-breaking space.

    \usemodule[t][markdown]
    \def\markdownRendererTilde{~}
    \starttext
    \startmarkdown
    Bartel~Leendert van~der~Waerden
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

A PDF document named `document.pdf` should be produced and contain the following text, where the middot (`·`) denotes a non-breaking space:

> Bartel·Leendert van·der·Waerden

#### 2.3.1.38 Strike-Through Renderer

The `markdownRendererStrikeThrough` macro represents a strike-through span of text. The macro receives a single argument that corresponds to the striked-out span of text. This macro will only be produced, when the `strikeThrough` option is enabled.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionStrikeThrough{true}
    \input soul.sty
    \def\markdownRendererStrikeThrough#1{\st{#1}}
    \markdownBegin
    This is ~~a lunar roving vehicle~~ strike-through text.
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

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

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[strikeThrough]{markdown}
    \usepackage{soul}
    \markdownSetup{
      renderers = {
        strikeThrough = {\st{#1}},
      },
    }
    \begin{document}
    \begin{markdown}
    This is ~~a lunar roving vehicle~~ strike-through text.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

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

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[strikeThrough = yes]
    \def\markdownRendererStrikeThrough#1{\overstrikes{#1}}
    \starttext
    \startmarkdown
    This is ~~a lunar roving vehicle~~ strike-through text.
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

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

#### 2.3.1.39 Subscript Renderer

The `markdownRendererSubscript` macro represents a subscript span of text. The macro receives a single argument that corresponds to the subscript span of text. This macro will only be produced, when the `subscripts` option is enabled.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionSubscripts{true}
    \def\markdownRendererSubscript#1{ (#1 moles) and }
    \markdownBegin
    H~2~O is a liquid.
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> H (2 moles) and O is a liquid.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[subscripts]{markdown}
    \markdownSetup{
      renderers = {
        subscript = { (#1 moles) and },
      },
    }
    \begin{document}
    \begin{markdown}
    H~2~O is a liquid.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> H (2 moles) and O is a liquid.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[subscripts = yes]
    \def\markdownRendererSubscript#1{ (#1 moles) and }
    \starttext
    \startmarkdown
    H~2~O is a liquid.
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> H (2 moles) and O is a liquid.

#### 2.3.1.40 Superscript Renderer

The `markdownRendererSuperscript` macro represents a superscript span of text. The macro receives a single argument that corresponds to the superscript span of text. This macro will only be produced, when the `superscripts` option is enabled.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionSuperscripts{true}
    \def\markdownRendererSuperscript#1{ taken to the power of #1}
    \markdownBegin
    2^10^ is 1024.
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> 2 taken to the power of 10 is 1024.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[superscripts]{markdown}
    \markdownSetup{
      renderers = {
        superscript = { taken to the power of #1},
      },
    }
    \begin{document}
    \begin{markdown}
    2^10^ is 1024.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> 2 taken to the power of 10 is 1024.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[superscripts = yes]
    \def\markdownRendererSuperscript#1{ taken to the power of #1}
    \starttext
    \startmarkdown
    2^10^ is 1024.
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> 2 taken to the power of 10 is 1024.

#### 2.3.1.41 Table Attribute Context Renderers

The following macros are only produced, when the `tableCaptions` and `tableAttributes` options are enabled.

The `markdownRendererTableAttributeContextBegin` and `markdownRendererTableAttributeContextEnd` macros represent the beginning and the end of a context in which the attributes of a table apply. The macros receive no arguments.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[
      pipeTables,
      tableCaptions,
      tableAttributes,
      relativeReferences,
    ]{markdown}
    \usepackage{expl3}
    \ExplSyntaxOn
    \markdownSetup{
      renderers = {
        tableAttributeContextBegin = {
          \group_begin:
          \markdownSetup{
            renderers = {
              attributeIdentifier = {
                \markdownSetup{
                  renderers = {
                    tableAttributeContextEnd = {
                      \label{##1}
                      \group_end:
                    },
                  },
                }
              },
            },
          }
        },
        tableAttributeContextEnd = {
          \group_end:
        },
      },
    }
    \ExplSyntaxOff
    \begin{document}
    \begin{markdown}
    See Table <#example-table>.

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

      : Demonstration of pipe table syntax. {#example-table}
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> See Table 1.

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

#### 2.3.1.42 Table Renderer

The `markdownRendererTable` macro represents a table. This macro will only be produced, when the `pipeTables` option is enabled. The macro receives the parameters `{`⟨caption⟩`}{`⟨number of rows⟩`}{`⟨number of columns⟩`}` followed by `{`⟨alignments⟩`}` and then by `{`⟨row⟩`}` repeated ⟨number of rows⟩ times, where ⟨row⟩ is `{`⟨column⟩`}` repeated ⟨number of columns⟩ times, ⟨alignments⟩ is ⟨alignment⟩ repeated ⟨number of columns⟩ times, and ⟨alignment⟩ is one of the following:

- `d` – The corresponding column has an unspecified (default) alignment.
- `l` – The corresponding column is left-aligned.
- `c` – The corresponding column is centered.
- `r` – The corresponding column is right-aligned.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[pipeTables, tableCaptions]{markdown}
    \newcount\rowCounter
    \newcount\columnCounter
    \makeatletter
    \def\processRow#1{%
      \columnCounter=1%
      \ifnum\rowCounter=0\relax
        As for the alignment,
      \else
        In row \the\rowCounter,
      \fi
      \processColumn#1
      \advance\rowCounter by 1\relax
      \ifnum\rowCounter>\rowTotal\relax
        \expandafter\@gobble
      \fi\processRow}%
    \def\processColumn#1{%
      column number \the\columnCounter{}
      \ifnum\rowCounter=0\relax
        \if#1d{}has default alignment\fi
        \if#1l{}is left-aligned\fi
        \if#1c{}is centered\fi
        \if#1r{}is right-aligned\fi
      \else
        says \emph{#1}%
      \fi
      \advance\columnCounter by 1\relax
      \ifnum\columnCounter<\columnTotal\relax, \fi
      \ifnum\columnCounter=\columnTotal\relax, and \fi
      \ifnum\columnCounter>\columnTotal\relax
        .\expandafter\@gobble
      \fi\processColumn}%
    \makeatother
    \markdownSetup{
      renderers = {
        table = {%
          This is a table with caption \emph{#1} that is #3 columns wide
          and #2 rows long.
          \rowCounter=0%
          \def\rowTotal{#2}%
          \def\columnTotal{#3}%
          \processRow
        },
      },
    }
    \begin{document}
    \begin{markdown}
    | Right | Left | Default | Center |
    |------:|:-----|---------|:------:|
    |   12  |  12  |    12   |    12  |
    |  123  |  123 |   123   |   123  |
    |    1  |    1 |     1   |     1  |

      : Demonstration of pipe table syntax
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> This is a table with caption Demonstration of pipe table syntax that is 4 columns wide and 4 rows long. As for the alignment, column number 1 is right-aligned, column number 2 is left-aligned, column number 3 has default alignment, and column number 4 is centered. In row 1, column number 1 says Right, column number 2 says Left, column number 3 says Default, and column number 4 says Center. In row 2, column number 1 says 12, column number 2 says 12, column number 3 says 12, and column number 4 says 12. In row 3, column number 1 says 123, column number 2 says 123, column number 3 says 123, and column number 4 says 123. In row 4, column number 1 says 1, column number 2 says 1, column number 3 says 1, and column number 4 says 1.

#### 2.3.1.43 TeX Math Renderers

The `markdownRendererInlineMath` and `markdownRendererDisplayMath` macros represent inline and display TeX math. Both macros receive a single argument that corresponds to the TeX math content. These macros will only be produced, when the `texMathDollars`, `texMathSingleBackslash`, or `texMathDoubleBackslash` option are enabled.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionTexMathDollars{true}
    \def\markdownRendererInlineMath#1{$#1\dots$}
    \def\markdownRendererDisplayMath#1{$$#1$$}
    \markdownBegin
    $E=mc^2$

    $$\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx$$
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> E=mc2…

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[texMathDollars]{markdown}
    \usepackage{amsmath}
    \def\markdownRendererInlineMath#1{\begin{math}#1\dots\end{math}}
    \def\markdownRendererDisplayMath#1{\begin{equation}#1\end{equation}}
    \begin{document}
    \begin{markdown}
    $E=mc^2$

    $$\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx$$
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> E=mc2…

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx(1)

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[texMathDollars = yes]
    \def\markdownRendererInlineMath#1{$#1\dots$}%
    \def\markdownRendererDisplayMath#1{\placeformula\startformula#1\stopformula}%
    \starttext
    \startmarkdown
    $E=mc^2$

    $$\hat{f} \left ( \xi  \right )= \int_{-\infty}^{\infty} f\left ( x  \right ) e^{-i2\pi \xi x} dx$$
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> E=mc2…

> f̂(ξ) = ∫−∞∞f(x)e−i2πξxdx(1)

#### 2.3.1.44 Thematic Break Renderer

The `markdownRendererThematicBreak` macro represents a thematic break. The macro receives no arguments.

##### Plain TeX Example

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

    \input markdown
    \def\markdownRendererThematicBreak{\vfil\break}
    \markdownBegin
    This is the first page.

    ***

    This is the second page.
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> This is the first page.

> This is the second page.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup{
      renderers = {
        thematicBreak = \newpage,
      },
    }
    \begin{document}
    \begin{markdown}
    This is the first page.

    ***

    This is the second page.
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> This is the first page.

> This is the second page.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \def\markdownRendererThematicBreak{\page[yes]}
    \starttext
    \startmarkdown
    This is the first page.

    ***

    This is the second page.
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> This is the first page.

> This is the second page.

#### 2.3.1.45 Tickbox Renderers

The macros named `markdownRendererTickedBox`, `markdownRendererHalfTickedBox`, and `markdownRendererUntickedBox` represent ticked and unticked boxes, respectively. These macros will either be produced, when the `taskLists` option is enabled, or when the Ballot Box with X (☒, U+2612), Hourglass (⌛, U+231B) or Ballot Box (☐, U+2610) Unicode characters are encountered in the markdown input, respectively.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[taskLists]{markdown}
    \markdownSetup{
      renderers = {
        untickedBox = No,
        tickedBox = Yes,
      },
    }
    \begin{document}
    \begin{markdown}
    - [ ] you can't.
    - [x] I can!
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> - No you can’t.
> - Yes I can!

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[taskLists = yes]
    \def\markdownRendererUntickedBox{No}
    \def\markdownRendererTickedBox{Yes}
    \starttext
    \startmarkdown
    - [ ] you can't.
    - [x] I can!
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> - No you can’t.
> - Yes I can!

#### 2.3.1.46 Warning and Error Renderers

The `markdownRendererWarning` and `markdownRendererError` macros represent warnings and errors produced by the markdown parser. Both macros receive four parameters:

1. The fully escaped text of the warning or error that can be directly typeset
2. The raw text of the warning or error that can be used outside typesetting for e.g. logging the warning or error.
3. The fully escaped text with more details about the warning or error that can be directly typeset. Can be empty, unlike the first two parameters.
4. The raw text with more details about the warning or error that can be used outside typesetting for e.g. logging the warning or error. Can be empty, unlike the first two parameters.

#### 2.3.1.47 YAML Metadata Renderers

The `markdownRendererJekyllDataBegin` macro represents the beginning of a YAML document. This macro will only be produced when the `jekyllData` option is enabled. The macro receives no arguments.

The `markdownRendererJekyllDataEnd` macro represents the end of a YAML document. This macro will only be produced when the `jekyllData` option is enabled. The macro receives no arguments.

The `markdownRendererJekyllDataMappingBegin` macro represents the beginning of a mapping in a YAML document. This macro will only be produced when the `jekyllData` option is enabled. The macro receives two arguments: the scalar key in the parent structure, cast to a string following YAML serialization rules, and the number of items in the mapping.

The `markdownRendererJekyllDataMappingEnd` macro represents the end of a mapping in a YAML document. This macro will only be produced when the `jekyllData` option is enabled. The macro receives no arguments.

The `markdownRendererJekyllDataSequenceBegin` macro represents the beginning of a sequence in a YAML document. This macro will only be produced when the `jekyllData` option is enabled. The macro receives two arguments: the scalar key in the parent structure, cast to a string following YAML serialization rules, and the number of items in the sequence.

The `markdownRendererJekyllDataSequenceEnd` macro represents the end of a sequence in a YAML document. This macro will only be produced when the `jekyllData` option is enabled. The macro receives no arguments.

The `markdownRendererJekyllDataBoolean` macro represents a boolean scalar value in a YAML document. This macro will only be produced when the `jekyllData` option is enabled. The macro receives two arguments: the scalar key in the parent structure, and the scalar value, both cast to a string following YAML serialization rules.

The `markdownRendererJekyllDataNumber` macro represents a numeric scalar value in a YAML document. This macro will only be produced when the `jekyllData` option is enabled. The macro receives two arguments: the scalar key in the parent structure, and the scalar value, both cast to a string following YAML serialization rules.

The `markdownRendererJekyllDataTypographicString` and `markdownRendererJekyllDataProgrammaticString` macros represent string scalar values in a YAML document. This macro will only be produced when the `jekyllData` option is enabled. The macro receives two arguments: the scalar key in the parent structure, cast to a string following YAML serialization rules, and the scalar value.

For each string scalar value, both macros are produced. Whereas `markdownRendererJekyllDataTypographicString` receives the scalar value after all markdown markup and special TeX characters in the string have been replaced by TeX macros, `markdownRendererJekyllDataProgrammaticString` receives the raw scalar value. Therefore, whereas the `markdownRendererJekyllDataTypographicString` macro is more appropriate for texts that are supposed to be typeset with TeX, such as document titles, author names, or exam questions, the `markdownRendererJekyllDataProgrammaticString` macro is more appropriate for identifiers and other programmatic text that won’t be typeset by TeX.

Before Markdown 3.7.0, the `markdownRendererJekyllDataTypographicString` macro was named `markdownRendererJekyllDataString` and the `markdownRendererJekyllDataProgrammaticString` macro was not produced. The `markdownRendererJekyllDataString` macro has been deprecated and will be removed in Markdown 4.0.0.

The `markdownRendererJekyllDataEmpty` macro represents an empty scalar value in a YAML document. This macro will only be produced when the `jekyllData` option is enabled. The macro receives one argument: the scalar key in the parent structure, cast to a string following YAML serialization rules.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionJekyllData{true}
    \def\markdownRendererJekyllDataTypographicString#1#2{\gdef\name{#2}}
    \def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}}
    \def\markdownRendererJekyllDataEnd{%
      \name{} is \age{} years old.}
    \markdownBegin
    ---
    name: Jane Doe
    age:  99
    ---
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> Jane Doe is 99 years old.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[jekyllData]{markdown}
    \markdownSetup{
      renderers = {
        jekyllDataTypographicString = {\gdef\name{#2}},
        jekyllDataNumber = {\gdef\age{#2}},
        jekyllDataEnd = {\name{} is \age{} years old.},
      }
    }
    \begin{document}

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

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> Jane Doe is 99 years old.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[jekyllData = yes]
    \def\markdownRendererJekyllDataTypographicString#1#2{\gdef\name{#2}}
    \def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}}
    \def\markdownRendererJekyllDataEnd{%
      \name{} is \age{} years old.}
    \starttext

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> Jane Doe is 99 years old.

### 2.3.2 Token Renderer Prototypes

By default, token renderers point to package-defined TeX macros, further referred to as prototypes, which provide useful default definitions.

##### Plain TeX Example

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

    \input markdown
    \def\markdownRendererTildePrototype{%
      Packages can specify token renderer prototypes.%
    }
    \markdownBegin
    ~
    \markdownEnd

    \def\markdownRendererTilde{%
      User-defined token renderers take precedence.%
    }
    \markdownBegin
    ~
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> Packages can specify token renderer prototypes.

> User-defined token renderers take precedence.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \markdownSetup{
      rendererPrototypes = {
        tilde = {Packages can specify token renderer prototypes.},
      },
    }
    \begin{document}
    \begin{markdown}
    ~
    \end{markdown}

    \begin{markdown}[
      renderers = {
        tilde = {User-defined token renderers take precedence.},
      },
    ]
    ~
    \end{markdown}
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> Packages can specify token renderer prototypes.

> User-defined token renderers take precedence.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \def\markdownRendererTildePrototype{%
      Packages can specify token renderer prototypes.%
    }
    \starttext
    \startmarkdown
    ~
    \stopmarkdown

    \def\markdownRendererTilde{%
      User-defined token renderers take precedence.%
    }
    \startmarkdown
    ~
    \stopmarkdown
    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> Packages can specify token renderer prototypes.

> User-defined token renderers take precedence.

#### 2.3.2.1 YAML Metadata Renderer Prototypes

For simple YAML metadata, a simple high-level interface is provided that can be programmed by setting the expl3 key–values [@latex25] for the module `markdown/jekyllData`.

##### Plain TeX Example

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

    \input markdown
    \def\markdownOptionJekyllData{true}
    \ExplSyntaxOn
    \keys_define:nn
      { markdown/jekyllData }
      {
        name .code:n = { \gdef\name{#1} },
        age  .code:n = { \gdef\age{#1}  },
      }
    \ExplSyntaxOff
    \def\markdownRendererJekyllDataEnd{%
      \name{} is \age{} years old.}
    \markdownBegin
    ---
    name: Jane Doe
    age:  99
    ---
    \markdownEnd
    \bye

Next, invoke LuaTeX from the terminal:

    luatex document.tex

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

> Jane Doe is 99 years old.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage[jekyllData]{markdown}
    \markdownSetup{
      jekyllDataRenderers = {
        name = {\gdef\name{#1}},
        code = {\gdef\age{#1}},
      },
      renderers = {
        jekyllDataEnd = {\name{} is \age{} years old.},
      }
    }
    \begin{document}

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

    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> Jane Doe is 99 years old.

##### ConTeXt Example

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

    \usemodule[t][markdown]
    \setupmarkdown[jekyllData = yes]
    \ExplSyntaxOn
    \keys_define:nn
      { markdown/jekyllData }
      {
        name .code:n = { \gdef\name{#1} },
        age  .code:n = { \gdef\age{#1}  },
      }
    \ExplSyntaxOff
    \def\markdownRendererJekyllDataEnd{%
      \name{} is \age{} years old.}
    \starttext

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

    \stoptext

Next, invoke LuaTeX from the terminal:

    context --luatex document.tex

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

> Jane Doe is 99 years old.

##### LaTeX Example

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

    \documentclass{article}
    \usepackage{markdown}
    \ExplSyntaxOn
    \str_new:N \g_markdown_example_title_str
    \seq_new:N \g_markdown_example_authors_seq
    \keys_define:nn
      { markdown / example / module }
      {  % Define a key--value that processes YAML metadata.
        title / programmaticString .str_gset:N = \g_markdown_example_title_str,  % Store the raw title in a variable.
        title .code:n = { \title { #1 } },  % Set the title. This is the same as writing `title / typographicString`.
        authors / unknown .code:n = {  % Store a variable-length list of authors in an array variable.
          \seq_put_right:Nn
            \g_markdown_example_authors_seq
            { #1 }
        },
      }
    \markdownSetupSnippet
      { metadata }
      {  % Define a snippet that routes YAML metadata to the above key key–value.
        jekyllDataKeyValue = markdown / example / module,
        renderers = {
          jekyllDataEnd = {  % At the end of the YAML metadata, ...
            \clist_set_from_seq:NN  % ... set the list of authors and
              \l_tmpa_clist
              \g_markdown_example_authors_seq
            \exp_args:Nx
              \author
              { \clist_use:Nn \l_tmpa_clist { ,~ } }
            \AtBeginDocument { \maketitle }  % ... typeset the title page.
          },
        }
      }
    \ExplSyntaxOff
    \begin{yaml}[snippet=metadata]
    title: Some title that includes _markup_
    authors: [Jane Doe, John Moe]
    \end{yaml}
    \begin{document}
    The raw title of the document is:
    \ExplSyntaxOn
    \str_use:N \g_markdown_example_title_str
    \ExplSyntaxOff
    \end{document}

Next, invoke LuaTeX from the terminal:

    lualatex document.tex

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

> ### Some title that includes markup

> ##### Jane Doe, John Moe

> ##### ⟨Current date⟩

> The raw title of the document is: Some title that includes _markup_

1. To support `-output-directory` in MikTeX with engines other than LuaTeX, you set either the environmental variable `TEXMF_OUTPUT_DIRECTORY` or the TeX macro `\markdownOptionOutputDir` to the same value.↩︎

2. Inline notes are easier to write, since you don’t have to pick an identifier and move down to type the note.↩︎

3. Inline notes are easier to write, since you don’t have to pick an identifier and move down to type the note.↩︎

4. Filenames other than `markdown-languages.json` may be specified using the `contentBlocksLanguageMap` Lua option.↩︎