From 4bbd57bdc027806eece856e6fcbb62b92924899e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 18 Nov 2024 06:39:26 +0000 Subject: [PATCH] Deploy to GitHub pages --- index.html | 12962 +++++++++++++++++++++++++++++++++++++++++++++++++ markdown.css | 360 ++ 2 files changed, 13322 insertions(+) create mode 100644 index.html create mode 100644 markdown.css diff --git a/index.html b/index.html new file mode 100644 index 000000000..4d8f99824 --- /dev/null +++ b/index.html @@ -0,0 +1,12962 @@ + + + + + + + + Markdown Package User Manual + + + + +
+

Markdown Package User Manual

+

Vít Starý Novotný, Andrej Genčur

+

3.8.1-11-g80a1a29e 2024-11-06

+
+ +

+

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 ≥ 2022 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.

+

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

+ +

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:

+ +

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

+

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:

+ +

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

+

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:

+
texlua ⟨CLI pathname⟩ -- hello.md hello.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

A PDF document named document.pdf should be produced and +contain the text “Hello world!” Invoking pdfTeX should have the +same effect:

+
texlua ⟨CLI pathname⟩ -- 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:

+
texlua ⟨CLI pathname⟩ -- example.md nomath.tex
+texlua ⟨CLI pathname⟩ tex_math_dollars=true -- example.md math.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+

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

+

−1 equals +i.

+
+

Invoking pdfTeX should have the same effect:

+
texlua ⟨CLI pathname⟩ -- example.md nomath.tex
+texlua ⟨CLI pathname⟩ 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 and obscures the output of the Lua command-line +interface when it is used for plumbing.

+

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:

+
texlua ⟨CLI pathname⟩ eagerCache=false -- hello.md hello.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
Hello \markdownRendererEmphasis{world}!\relax
+
+

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

+
texlua ⟨CLI pathname⟩ 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 just means that the version +experimental of the theme +witiko/markdown/defaults will be loaded and warnings for +hard-deprecated features will become errors. However, the effects may +extend to other areas in the future 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.

+
+
+
+
+
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 convert1 = markdown.new({})
+  local convert2 = markdown.new({singletonCache=false})
+  local convert3 = markdown.new({singletonCache=true})
+  local newline = [[^^J^^J]]
+  tex.print(tostring(convert1) .. ", ")
+  tex.print(tostring(convert2) .. ", ")
+  tex.print(tostring(convert3))
+}
+\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:

+
+

function: 0x1a4a038, function: 0x1a52b18, function: 0x1a4a038

+
+

As you can see, the caching causes convert1 and +convert3 to be the same conversion function.

+

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:

+
texlua ⟨CLI pathname⟩ cacheDir=cache -- hello.md hello.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
Plain TeX Example
+

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:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
NameSurnameBorn
AlbertEinstein1879
MarieCurie1867
ThomasEdison1847
+

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:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
NameSurnameBorn
AlbertEinstein1879
MarieCurie1867
ThomasEdison1847
+

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:

+
texlua ⟨CLI pathname⟩ finalizeCache=true frozenCacheFileName=cache.tex -- hello.md hello.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
Plain TeX Example
+

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 +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.11 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:

+
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
+texlua ⟨CLI pathname⟩ blankBeforeBlockquote=true -- content.md optiontrue.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+

A paragraph.

+
+

A quote?

+
+

A paragraph. > A quote?

+
+
Plain TeX Example
+

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

+
texlua ⟨CLI pathname⟩ fencedCode=true -- content.md optionfalse.tex
+texlua ⟨CLI pathname⟩ fencedCode=true blankBeforeCodeFence=true  -- content.md optiontrue.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+

A paragraph.

+
A code fence?
+

A paragraph. A code fence?

+
+
Plain TeX Example
+

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.13 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.14 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:

+
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
+texlua ⟨CLI pathname⟩ blankBeforeHeading=true  -- content.md optiontrue.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+

A paragraph.

+

A heading?

+

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

+
+
Plain TeX Example
+

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

+
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
+texlua ⟨CLI pathname⟩ blankBeforeList=true  -- content.md optiontrue.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+

A paragraph.

+ +

A 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 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 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 paragraph. - not a list

+
+

2.2.1.16 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.17 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:

+
texlua ⟨CLI pathname⟩ breakableBlockquotes=false -- content.md optionfalse.tex
+texlua ⟨CLI pathname⟩  -- content.md optiontrue.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+
+

A single block quote or two block quotes?

+
+
+

A single block quote

+
+
+

or two block quotes?

+
+
+
Plain TeX Example
+

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.18 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.19 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.20 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:

+
texlua ⟨CLI pathname⟩ codeSpans=false -- content.md optionfalse.tex
+texlua ⟨CLI pathname⟩ -- content.md optiontrue.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+

“Is this a code span?” “Or a quote?”

+

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

+
+
Plain TeX Example
+

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

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
NameSurnameBorn
AlbertEinstein1879
MarieCurie1867
ThomasEdison1847
+

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:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
NameSurnameBorn
AlbertEinstein1879
MarieCurie1867
ThomasEdison1847
+

Table 1: An example table

+
This is an example code listing in \ConTeXt.
+

This is a transcluded markdown document.

+
+

2.2.1.22 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 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 text

+
+

2.2.1.23 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.24 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.25 Option +ensureJekyllData

+
+
ensureJekyllData (default value: +false)
+
+
+
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.

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

+
+
+
+
+

2.2.1.26 Option +expectJekyllData

+
+
expectJekyllData (default value: +false)
+
+
+
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}
+
+
+
+
+
+
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}
+
+
+
+
+
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.27 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.28 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. +
  2. second item
    3. +
  3. third item
    4. +
+
+
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. +
  2. second item
    3. +
  3. third item
    4. +
+
+

2.2.1.29 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.30 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.31 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.32 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.33 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.34 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.35 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. +
  2. McHale
    3. +
  3. Parish
    4. +
+
+
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. +
  2. McHale
    3. +
  3. Parish
    4. +
+
+

2.2.1.36 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.37 Option +html

+
+
html (default value: true)
+
+
+
true
+
+

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

+
+
+
+
+
+
false
+
+

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

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

+
texlua ⟨CLI pathname⟩ html=false -- content.md optionfalse.tex
+texlua ⟨CLI pathname⟩ -- content.md optiontrue.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+

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

+

Is there support? Is there support? Is there support?

+
+
Plain TeX Example
+

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

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

+
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
+texlua ⟨CLI pathname⟩ hybrid=true -- content.md optiontrue.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+

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

+

−1 equals +i.

+
+
Plain TeX Example
+

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.39 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.40 Option +inlineNotes

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

Enable the Pandoc inline note +syntax extension:

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

Disable the Pandoc inline note syntax extension.

+
+
+
+
+
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.^[Inlines notes are easier to
+write, since you don't have to pick an identifier and
+move down to type the note.]
+\end{markdown}
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
lualatex document.tex
+

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

+
+

Here is an inline note.1

+
+
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.^[Inlines notes are easier to
+write, since you don't have to pick an identifier and
+move down to type the note.]
+\stopmarkdown
+\stoptext
+

Next, invoke LuaTeX from the terminal:

+
context --luatex document.tex
+

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

+
+

Here is an inline note.2

+
+

2.2.1.41 Option +jekyllData

+
+
jekyllData (default value: false)
+
+
+
true
+
+

Enable the Pandoc yaml +metadata block syntax extension for entering metadata in +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.42 Option +linkAttributes

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

Enable the Pandoc link and +image attribute syntax extension:

+
An inline ![image](foo.jpg){#id .class width=30 height=20px}
+and a reference ![image][ref] with attributes.
+
+[ref]: foo.jpg "optional title" {#id .class key=val key2=val2}
+
+
+
+
+
+
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.43 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.44 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.45 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.46 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:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RightLeftDefaultCenter
12121212
123123123123
1111
+
+
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:

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RightLeftDefaultCenter
12121212
123123123123
1111
+
+

2.2.1.47 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.48 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.49 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.50 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. Instead, those headings will be shifted to level 6, +when ⟨shift amount⟩ is positive, and to level 1, when +⟨shift amount⟩ is negative.

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

+

A section

+

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

+

A section

+

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

+

A section

+

A section

+
+

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

+ +

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

+
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
+texlua ⟨CLI pathname⟩ smartEllipses=true -- content.md optiontrue.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+

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

+

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

+
+
Plain TeX Example
+

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

+
    +
  1. third item
    2. +
  2. fourth item
    3. +
  3. fifth item
    4. +
+

The following list does not respect the numbers specified in the +markup:

+
    +
  1. third item
    2. +
  2. fourth item
    3. +
  3. fifth item
    4. +
+
+
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:

+
    +
  1. third item
    2. +
  2. fourth item
    3. +
  3. fifth item
    4. +
+

The following list does not respect the numbers specified in the +markup:

+
    +
  1. third item
    2. +
  2. fourth item
    3. +
  3. fifth item
    4. +
+
+

2.2.1.54 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 soulutf8.sty
+\def\markdownRendererStrikeThrough#1{\st{#1}}
+\markdownBegin
+This is ~~a lunar roving vehicle~~ strike-through text.
+\markdownEnd
+\bye
+

Next, invoke LuaTeX from the terminal:

+
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{soulutf8}
+\markdownSetup{
+  renderers = {
+    strikeThrough = {\st{#1}},
+  },
+}
+\begin{document}
+\begin{markdown}
+This is ~~a lunar roving vehicle~~ strike-through text.
+\end{markdown}
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
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.55 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.56 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.57 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.58 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.
RightLeftDefaultCenter
12121212
123123123123
1111
+
+

2.2.1.59 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.
RightLeftDefaultCenter
12121212
123123123123
1111
+
+
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.
RightLeftDefaultCenter
12121212
123123123123
1111
+
+

2.2.1.60 Option +taskLists

+
+
taskLists (default value: false)
+
+
+
true
+
+

Enable the Pandoc task list +syntax extension:

+
- [ ] an unticked task list item
+- [/] a half-checked task list item
+- [X] a ticked 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:

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

+
+ +
+

2.2.1.61 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.62 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:

+
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
+texlua ⟨CLI pathname⟩ texMathDollars=true -- content.md optiontrue.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+

$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.63 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:

+
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
+texlua ⟨CLI pathname⟩ texMathDoubleBackslash=true -- content.md optiontrue.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+

\(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.64 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:

+
texlua ⟨CLI pathname⟩ -- content.md optionfalse.tex
+texlua ⟨CLI pathname⟩ texMathSingleBackslash=true -- content.md optiontrue.tex
+luatex document.tex
+

where ⟨CLI pathname⟩ corresponds to the location of the Lua +CLI script file, such as +~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems +or C:\Users\⟨Your +username⟩\texmf\scripts\markdown\markdown-cli.lua on +Windows systems. Use the command +kpsewhich -a markdown-cli.lua to locate the Lua CLI script +file using Kpathsea.

+

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

+
+

(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.65 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:

+ +

The following list is loose:

+ +

The following list is now also loose:

+ +
+

2.2.1.66 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. +
  2. Enable the finalizeCache option.
    3. +
  3. Typeset the plain TeX document +to populate and finalize the cache.
    4. +
  4. Enable the frozenCache option.
    5. +
  5. Publish the source code of the plain TeX document and the +cacheDir directory.
    6. +
+

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:

+ +

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.3 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/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.4 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.5 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.5.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.6 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/beamer/MU and +witiko/dot, you would use the following code in the +preamble of your document:

+
\usepackage[
+  import=witiko/beamer/MU,
+  import=witiko/dot,
+]{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/dot
+
+

A theme that typesets fenced code blocks with the dot … +infostring as images of directed graphs rendered by the Graphviz tools. +The right tail of the infostring is used as the image title. The theme +requires a Unix-like operating system with GNU Diffutils and Graphviz +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/dot]{markdown}
+\setkeys{Gin}{
+  width=\columnwidth,
+  height=0.65\paperheight,
+  keepaspectratio}
+\begin{document}
+\begin{markdown}
+``` dot Various formats of mathemathical formulae
+digraph tree {
+  margin = 0;
+  rankdir = "LR";
+
+  latex -> pmml;
+  latex -> cmml;
+  pmml -> slt;
+  cmml -> opt;
+  cmml -> prefix;
+  cmml -> infix;
+  pmml -> mterms [style=dashed];
+  cmml -> mterms;
+
+  latex [label = "LaTeX"];
+  pmml [label = "Presentation MathML"];
+  cmml [label = "Content MathML"];
+  slt [label = "Symbol Layout Tree"];
+  opt [label = "Operator Tree"];
+  prefix [label = "Prefix"];
+  infix [label = "Infix"];
+  mterms [label = "M-Terms"];
+}
+```
+\end{markdown}
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
lualatex document.tex
+

A PDF document named document.pdf should be produced and +contain a drawing of a directed graph similar to Figure 1 from the +following conference article:

+
+

NOVOTNÝ, Vít, Petr SOJKA, Michal ŠTEFÁNIK and Dávid LUPTÁK. Three is +Better than One: Ensembling Math Information Retrieval Systems. CEUR +Workshop Proceedings. Thessaloniki, Greece: M. Jeusfeld c/o +Redaktion Sun SITE, Informatik V, RWTH Aachen., 2020, vol. 2020, No +2696, p. 1-30. ISSN 1613-0073. http://ceur-ws.org/Vol-2696/paper_235.pdf

+
+
+
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]{markdown}
+\begin{document}
+\begin{markdown}
+![img](https://github.com/witiko/markdown/raw/main/markdown.png
+       "The banner of the Markdown package")
+\end{markdown}
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
lualatex document.tex
+

A PDF document named document.pdf should be produced and +contain the following image:

+
+
+img + +
+
+
+
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.7 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 Attribute Renderers

+

The following macros are only produced, when at least one of the +following options for markdown attributes on different elements is +enabled:

+ +

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 a 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.2 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.3 Bracketed Spans 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.4 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:

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

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

+ +
+

2.3.1.5 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.6 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.7 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.8 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.9 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 +kpathsea3 +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.10 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

+ +

Milk

+ +

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

+ +

Milk

+ +

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

+ +

Milk

+ +

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.11 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.12 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.13 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.14 Fenced Div Attribute +Context Renderers

+

The following macros are only produced, when the +fencedDiv 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.15 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.16 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.17 Inline HTML Comment +Renderer

+

The markdownRendererInlineHtmlComment macro represents +the contents of an inline HTML comment. This macro will +only be produced, when the html option is +enabled. The macro receives a single argument that corresponds to the +contents of the HTML comment.

+
LaTeX Example
+

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

+
\documentclass{article}
+\usepackage[html]{markdown}
+\usepackage{marginnote}
+\markdownSetup{
+  renderers = {
+    inlineHtmlComment = {\marginnote{#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. -->
+\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.18 HTML Tag and Element +Renderers

+

The markdownRendererInlineHtmlTag macro represents an +opening, closing, or empty inline HTML tag. This macro will +only be produced, when the html option is +enabled. 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.

+
LaTeX Example
+

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

+
\documentclass{article}
+\usepackage[html]{markdown}
+\usepackage{marginnote}
+\usepackage{verbatim}
+\markdownSetup{
+  renderers = {
+    inlineHtmlTag = {\textbf{#1}},
+    inputBlockHtmlElement = {\verbatiminput{#1}},
+  },
+}
+\begin{document}
+\begin{markdown}
+<b>_Hello,_ world!</b><br/>
+
+<div>_Hello,_ world!</div>
+\end{markdown}
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
lualatex document.tex
+lualatex document.tex
+

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

+
+

_Hello,_ world!

+
<div>_Hello,_ world!</div>
+
+

2.3.1.19 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.20 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.21 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:

+
+ +

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

+
+ +

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

+
+ +

(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.22 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.23 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!

+
+ +

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.

+
+ +

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.26 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.27 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.28 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.29 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.30 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. +

  2. This is the second item.

    3. +

  3. This is the third item.

    4. +
+
+
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. +

  2. This is the second item.

    3. +

  3. This is the third item.

    4. +
+
+
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. +

  2. This is the second item.

    3. +

  3. This is the third item.

    4. +
+
+

2.3.1.31 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.32 Section Renderers

+

The markdownRendererSectionBegin and +markdownRendererSectionEnd macros represent the beginning +and the end of a section based on headings.

+

2.3.1.33 Replacement Character +Renderers

+

The markdownRendererReplacementCharacter macro +represents the U+0000 and U+FFFD Unicode characters. The macro receives +no arguments.

+

2.3.1.34 Special Character +Renderers

+

The following macros replace any special plain TeX characters, including the active pipe +character (|) of ConTeXt, in the input text:

+ +
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.35 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 soulutf8.sty
+\def\markdownRendererStrikeThrough#1{\st{#1}}
+\markdownBegin
+This is ~~a lunar roving vehicle~~ strike-through text.
+\markdownEnd
+\bye
+

Next, invoke LuaTeX from the terminal:

+
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{soulutf8}
+\markdownSetup{
+  renderers = {
+    strikeThrough = {\st{#1}},
+  },
+}
+\begin{document}
+\begin{markdown}
+This is ~~a lunar roving vehicle~~ strike-through text.
+\end{markdown}
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
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.36 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.37 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.38 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.
RightLeftDefaultCenter
12121212
123123123123
1111
+
+

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

+ +
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.40 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\nonumber$$}
+\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.41 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.42 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:

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

+
+ +
+

2.3.1.43 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. +
  2. The raw text of the warning or error that can be used outside +typesetting for e.g. logging the warning or error.
    3. +
  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. +
  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.
    5. +
+

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

+

By default, the renderer prototypes for YAML metadata provide a +high-level interface that can be programmed using the +markdown/jekyllData key–values from the l3keys module of +the LaTeX3 kernel.

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

+
+
+
+
    +

  1. Inlines notes are easier to write, since you don’t have +to pick an identifier and move down to type the note.↩︎

    2. +

  2. Inlines notes are easier to write, since you don’t have +to pick an identifier and move down to type the note.↩︎

    3. +

  3. Filenames other than +markdown-languages.json may be specified using the +contentBlocksLanguageMap Lua option.↩︎

    4. +
+
+ + diff --git a/markdown.css b/markdown.css new file mode 100644 index 000000000..8a27734fc --- /dev/null +++ b/markdown.css @@ -0,0 +1,360 @@ + +html { + font-size: 100%; + overflow-y: scroll; + -webkit-text-size-adjust: 100%; + -ms-text-size-adjust: 100%; +} + +body { + color: #444; + font-family: Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif; + font-size: 12px; + line-height: 1.7; + padding: 1em; + margin: auto; + max-width: 42em; + background: #fefefe; +} + +a { + color: #0645ad; +} + +a:visited { + color: #0b0080; +} + +a:hover { + color: #06e; +} + +a:active { + color: #faa700; +} + +a:focus { + outline: thin dotted; +} + +*::-moz-selection { + background: rgba(255, 255, 0, 0.3); + color: #000; +} + +*::selection { + background: rgba(255, 255, 0, 0.3); + color: #000; +} + +a::-moz-selection { + background: rgba(255, 255, 0, 0.3); + color: #0645ad; +} + +a::selection { + background: rgba(255, 255, 0, 0.3); + color: #0645ad; +} + +p { + margin: 1em 0; +} + +img { + max-width: 100%; +} + +h1, h2, h3, h4, h5, h6 { + color: #111; + line-height: 125%; + margin-top: 2em; + font-weight: normal; +} + +h4, h5, h6 { + font-weight: bold; +} + +h1 { + font-size: 2.5em; +} + +h2 { + font-size: 2em; +} + +h3 { + font-size: 1.5em; +} + +h4 { + font-size: 1.2em; +} + +h5 { + font-size: 1em; +} + +h6 { + font-size: 0.9em; +} + +blockquote { + color: #666666; + margin: 0; + padding-left: 3em; + border-left: 0.5em #EEE solid; +} + +hr { + display: block; + height: 2px; + border: 0; + border-top: 1px solid #aaa; + border-bottom: 1px solid #eee; + margin: 1em 0; + padding: 0; +} + +pre, code, kbd, samp { + color: #000; + font-family: monospace, monospace; + _font-family: 'courier new', monospace; + font-size: 0.98em; +} + +pre { + white-space: pre; + white-space: pre-wrap; + word-wrap: break-word; + counter-reset: line; +} + +.sourceCode.linenos > span { + counter-increment: line; +} + +.sourceCode.linenos > span:before{ + content: counter(line) " "; +} + +b, strong { + font-weight: bold; +} + +dfn { + font-style: italic; +} + +ins { + background: #ff9; + color: #000; + text-decoration: none; +} + +mark { + background: #ff0; + color: #000; + font-style: italic; + font-weight: bold; +} + +sub, sup { + font-size: 75%; + line-height: 0; + position: relative; + vertical-align: baseline; +} + +sup { + top: -0.5em; +} + +sub { + bottom: -0.25em; +} + +ul, ol { + margin: 1em 0; + padding: 0 0 0 2em; +} + +li p:last-child { + margin-bottom: 0; +} + +ul ul, ol ol { + margin: .3em 0; +} + +dl { + margin-bottom: 1em; +} + +dt { + font-weight: bold; + margin-bottom: .8em; +} + +dd { + margin: 0 0 .8em 2em; +} + +dd:last-child { + margin-bottom: 0; +} + +img { + border: 0; + -ms-interpolation-mode: bicubic; + vertical-align: middle; +} + +figure { + display: block; + text-align: center; + margin: 1em 0; +} + +figure img { + border: none; + margin: 0 auto; +} + +figcaption { + font-size: 0.8em; + font-style: italic; + margin: 0 0 .8em; +} + +table { + margin-bottom: 2em; + border-bottom: 1px solid #ddd; + border-right: 1px solid #ddd; + border-spacing: 0; + border-collapse: collapse; +} + +table th { + padding: .2em 1em; + background-color: #eee; + border-top: 1px solid #ddd; + border-left: 1px solid #ddd; +} + +table td { + padding: .2em 1em; + border-top: 1px solid #ddd; + border-left: 1px solid #ddd; + vertical-align: top; +} + +.author { + font-size: 1.2em; + text-align: center; +} + +@media only screen and (min-width: 480px) { + body { + font-size: 14px; + } +} +@media only screen and (min-width: 768px) { + body { + font-size: 16px; + } +} +@media print { + * { + background: transparent !important; + color: black !important; + filter: none !important; + -ms-filter: none !important; + } + + body { + font-size: 12pt; + max-width: 100%; + } + + a, a:visited { + text-decoration: underline; + } + + hr { + height: 1px; + border: 0; + border-bottom: 1px solid black; + } + + a[href]:after { + content: " (" attr(href) ")"; + } + + abbr[title]:after { + content: " (" attr(title) ")"; + } + + .ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after { + content: ""; + } + + pre, blockquote { + border: 1px solid #999; + padding-right: 1em; + page-break-inside: avoid; + } + + tr, img { + page-break-inside: avoid; + } + + img { + max-width: 100% !important; + } + + @page :left { + margin: 15mm 20mm 15mm 10mm; +} + + @page :right { + margin: 15mm 10mm 15mm 20mm; +} + + p, h2, h3 { + orphans: 3; + widows: 3; + } + + h2, h3 { + page-break-after: avoid; + } +} + +.tex sub, .latex sub, .latex sup { + text-transform: uppercase; +} + +.tex sub, .latex sub { + vertical-align: -0.1ex; + margin-left: -0.1667em; + margin-right: -0.125em; +} + +.tex, .latex, .tex sub, .latex sub { + font-size: 1em; +} + +.latex sup { + font-size: 0.85em; + vertical-align: -0.35em; + margin-left: -0.36em; + margin-right: -0.15em; +} + +abbr { + text-transform: lowercase; + font-variant: small-caps; +} +