Markdown Package User Manual

Vít Novotný

2.19.0-0-g80fcf20 2022-12-23

1 Introduction

The Markdown package converts markdown markup to TeX commands. The functionality is provided both as a Lua module and as plain TeX, LaTeX, and ConTeXt macro packages that can be used to directly typeset TeX documents containing markdown markup. Unlike other convertors, the Markdown package 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 ≥ 2020 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 Markdown is not included in your TeX distribution, you will need to install it.

First, download the package from the repository using Git:

git clone https://github.com/witiko/markdown

Next, enter the directory named markdown and run the make base command using GNU Make:

cd markdown
make base

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

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

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
\input hello
\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 ran_ok, kpse = pcall(require, "kpse")
if ran_ok then kpse.set_program_name("luatex") end
local markdown = require("markdown")
local convert = markdown.new()
print(convert("Hello *world*!"))

Next, invoke LuaTeX from the terminal:

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!” Invoking pdfTeX should have the same effect:

pdftex --shell-escape document.tex

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!” Invoking pdfTeX should have the same effect:

pdflatex --shell-escape document.tex

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

A PDF document named latex.pdf should be produced. Open the text documents latex.tex and example.md in a text editor to see how the example documents are structured. Try changing the documents and typesetting them as follows:

lualatex latex.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 document.tex

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

texexec --passon=--shell-escape document.tex

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 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 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
\input example
\bye

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

#!/usr/bin/env texlua
local ran_ok, kpse = pcall(require, "kpse")
if ran_ok then kpse.set_program_name("luatex") end
local markdown = require("markdown")
local input, convert_safe, convert_unsafe, paragraph

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

print(
  convert_safe(input) .. paragraph ..
  convert_unsafe(input)
)

Next, invoke LuaTeX from the terminal:

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_safe, convert_unsafe, paragraph

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

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

Next, invoke LuaTeX from the terminal:

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
\input safe

\begingroup
\catcode`\%=12
\input unsafe
\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 safe.tex
texlua ⟨CLI pathname⟩ hybrid=true -- example.md unsafe.tex
luatex document.tex

where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\Your username\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -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 safe.tex
texlua ⟨CLI pathname⟩ hybrid=true -- example.md unsafe.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\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.

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*}{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.

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[hybrid = yes]
\startmarkdown
$\sqrt{-1}$ *equals* $i$.
\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:

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

√-̅1̅ equals i.

Invoking pdfTeX should have the same effect:

texexec --passon=--shell-escape document.tex

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 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
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new({cacheDir = "cache"})
  local input = "Hello *world*!"
  tex.sprint(convert(input)) }
\bye

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

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
\input hello
\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 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.2 Option contentBlocksLanguageMap

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

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

LaTeX Example

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

Name,Surname,Born
Albert,Einstein,1879
Marie,Curie,1867
Thomas,Edison,1847

Create also a text document named language-map.json with the following content:

{
  "tex": "LaTeX"
}

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

This is an example code listing in \LaTeX.

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

This is a *transcluded markdown document*.

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

\documentclass{article}
\usepackage{minted}
\usepackage[contentBlocks]{markdown}
\markdownSetup{
  contentBlocksLanguageMap = {language-map.json},
}
\begin{document}
\begin{markdown}
/table.csv  (An example table)
/code.tex   (An example code listing)
/part.md    (A file transclusion example)
\end{markdown}
\end{document}

Next, invoke LuaTeX from the terminal:

lualatex --shell-escape document.tex

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

Name Surname Born
Albert Einstein 1879
Marie Curie 1867
Thomas Edison 1847

Table 1: An example table

This is an example code listing in \LaTeX.

This is a transcluded markdown document.

ConTeXt Example

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

Name,Surname,Born
Albert,Einstein,1879
Marie,Curie,1867
Thomas,Edison,1847

Create also a text document named language-map.json with the following content:

{
  "tex": "ConTeXt"
}

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

This is an example code listing in \ConTeXt.

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

This is a *transcluded markdown document*.

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

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

Next, invoke LuaTeX from the terminal:

context document.tex

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

Name Surname Born
Albert Einstein 1879
Marie Curie 1867
Thomas Edison 1847

Table 1: An example table

This is an example code listing in \ConTeXt.

This is a transcluded markdown document.

2.2.1.3 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.4 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
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new({finalizeCache = true, frozenCacheFileName = "cache.tex"})
  local input = "Hello *world*!"
  tex.sprint(convert(input)) }
\bye

Then, invoke LuaTeX from the terminal:

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
\input hello
\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 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 pdfTeX without shell access from the terminal:

texexec --passon=--no-shell-escape frozen-document.tex

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

2.2.1.5 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
\directlua{
  local markdown = require("markdown")
  local newline = [[^^J^^J]]
  local convert, input

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

  convert = markdown.new({blankBeforeBlockquote = true})
  input = "A paragraph."   .. newline ..
          "> Not a quote." .. newline
  tex.sprint(convert(input)) }
\bye

Then, invoke LuaTeX from the terminal:

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
\input optionfalse
\input optiontrue
\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 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.6 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
\directlua{
  local markdown = require("markdown")
  local newline = [[^^J^^J]]
  local convert, input

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

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

Then, invoke LuaTeX from the terminal:

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
\input optionfalse
\input optiontrue
\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 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.7 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.
```
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.8 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}
\directlua{
  local markdown = require("markdown")
  local newline = [[^^J^^J]]
  local convert, input

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

  convert = markdown.new({blankBeforeHeading = true})
  input = "A paragraph."    .. newline ..
          "Not a heading."  .. newline ..
          "=============="  .. newline
  tex.sprint(convert(input)) }
\bye

Then, invoke LuaTeX from the terminal:

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
\input optionfalse
\input optiontrue
\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 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.9 Option bracketedSpans

bracketedSpans (default value: false)
true

Enable the Pandoc bracketed spans extension:

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

Disable the Pandoc bracketed spans 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 --shell-escape document.tex

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

Here is some colored text.

2.2.1.10 Option breakableBlockquotes

breakableBlockquotes (default value: false)
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}
\directlua{
  local markdown = require("markdown")
  local newline = [[^^J^^J]]
  local convert, input

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

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

Then, invoke LuaTeX from the terminal:

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
\input optionfalse
\input optiontrue
\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⟩ -- content.md optionfalse.tex
texlua ⟨CLI pathname⟩ breakableBlockquotes=true  -- content.md optiontrue.tex
luatex document.tex

where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\Your username\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -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

\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}
> A single

> block quote.
\end{markdown}

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

> Another block quote.
\end{markdown*}

\end{document}

Next, invoke LuaTeX from the terminal:

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

\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 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.11 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.12 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.13 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
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new()
  local input =
    "``This is a code span.'' " ..
    "``This is no longer a code span.''"
  tex.sprint(convert(input)) }
\par
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new({codeSpans = false})
  local input =
    "``This is a quote.'' " ..
    "``This is another quote.''"
  tex.sprint(convert(input)) }
\bye

Then, invoke LuaTeX from the terminal:

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
\input optionfalse
\par
\input optiontrue
\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 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.14 Option contentBlocks

contentBlocks (default value: false)
true

Enable the iA Writer content blocks syntax extension:

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

Disable the iA Writer content blocks syntax extension.

LaTeX Example

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

Name,Surname,Born
Albert,Einstein,1879
Marie,Curie,1867
Thomas,Edison,1847

Create also a text document named markdown-languages.json with the following content:

{
  "tex": "LaTeX"
}

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

This is an example code listing in \LaTeX.

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

This is a *transcluded markdown document*.

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

\documentclass{article}
\usepackage{minted}
\usepackage[contentBlocks]{markdown}
\begin{document}
\begin{markdown}
/table.csv  (An example table)
/code.tex   (An example code listing)
/part.md    (A file transclusion example)
\end{markdown}
\end{document}

Next, invoke LuaTeX from the terminal:

lualatex --shell-escape document.tex

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

Name Surname Born
Albert Einstein 1879
Marie Curie 1867
Thomas Edison 1847

Table 1: An example table

This is an example code listing in \LaTeX.

This is a transcluded markdown document.

ConTeXt Example

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

Name,Surname,Born
Albert,Einstein,1879
Marie,Curie,1867
Thomas,Edison,1847

Create also a text document named markdown-languages.json with the following content:

{
  "tex": "ConTeXt"
}

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

This is an example code listing in \ConTeXt.

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

This is a *transcluded markdown document*.

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

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

Next, invoke LuaTeX from the terminal:

context document.tex

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

Name Surname Born
Albert Einstein 1879
Marie Curie 1867
Thomas Edison 1847

Table 1: An example table

This is an example code listing in \ConTeXt.

This is a transcluded markdown document.

2.2.1.15 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 = 2,
  finalize_grammar = function(reader)
    local nonspacechar = lpeg.P(1) - lpeg.S("\t ")
    local doubleslashes = lpeg.P("//")
    local function between(p, starter, ender)
      ender = lpeg.B(nonspacechar) * ender
      return (starter * #nonspacechar
             * lpeg.Ct(p * (p - ender)^0) * ender)
    end

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

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

return strike_through

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

\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",
        "ThematicBreak",
        "BulletList",
        "OrderedList",
        "Heading",
        "DisplayHtml",
        "Paragraph",
        "Plain"
    ],
    "Inline": [
        "Str",
        "Space",
        "Endline",
        "UlOrStarLine",
        "Strong",
        "Emph",
        "StrikeThrough (user-defined \"./strike-through.lua\" syntax extension)",
        "Link",
        "Image",
        "Code",
        "AutoLinkUrl",
        "AutoLinkEmail",
        "AutoLinkRelativeReference",
        "InlineHtml",
        "HtmlEntity",
        "EscapedChar",
        "Smart",
        "Symbol"
    ]
}

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

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

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

Lua Module 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.18 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.19 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 = 2,
  finalize_grammar = function(reader)
    local nonspacechar = lpeg.P(1) - lpeg.S("\t ")
    local doubleslashes = lpeg.P("//")
    local function between(p, starter, ender)
      ender = lpeg.B(nonspacechar) * ender
      return (starter * #nonspacechar
             * lpeg.Ct(p * (p - ender)^0) * ender)
    end

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

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

return strike_through

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

\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.20 Option fancyLists

fancyLists (default value: false)
true

Enable the Pandoc fancy list extension:

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

Disable the Pandoc fancy list extension.

LaTeX Example

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

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

Next, invoke LuaTeX from the terminal:

lualatex --shell-escape document.tex

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

  1. first item
  2. second item
  3. third item
ConTeXt Example

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

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

Next, invoke LuaTeX from the terminal:

context document.tex

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

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

2.2.1.21 Option fencedCode

fencedCode (default value: false)
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[fencedCode]{markdown}
\begin{document}
\begin{markdown}
~~~ js
if (a > 3) {
    moveShip(5 * gravity, DOWN);
}
~~~~~~

  ``` html
  <pre>
    <code>
      // Some comments
      line 1 of code
      line 2 of code
      line 3 of code
    </code>
  </pre>
  ```
\end{markdown}
\end{document}

Next, invoke LuaTeX from the terminal:

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]
\setupmarkdown[fencedCode = yes]
\definetyping [js]
\definetyping [html]
\setuptyping  [html] [option=XML]
\starttext
\startmarkdown
~~~ js
if (a > 3) {
    moveShip(5 * gravity, DOWN);
}
~~~~~~

  ``` html
  <pre>
    <code>
      // Some comments
      line 1 of code
      line 2 of code
      line 3 of code
    </code>
  </pre>
  ```
\stopmarkdown
\stoptext

Next, invoke LuaTeX from the terminal:

context 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.22 Option fencedDivs

fencedDivs (default value: false)
true

Enable the Pandoc fenced divs extension:

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

And another.
:::::
false

Disable the Pandoc fenced divs 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.23 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 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 pdfTeX without shell access from the terminal:

texexec --passon=--no-shell-escape document.tex

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

2.2.1.24 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 \markdownFrozenCachenumber⟩ 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
\directlua{
  local markdown = require("markdown")
  local firstConvert = markdown.new({finalizeCache = true, frozenCacheCounter = 0})
  local firstInput = "Hello"
  local secondConvert = markdown.new({finalizeCache = true, frozenCacheCounter = 1})
  local secondInput = "*world*!"
  tex.sprint(firstConvert(firstInput) .. [[ ]] .. secondConvert(secondInput)) }
\bye

Then, invoke LuaTeX from the terminal:

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.25 Option hardLineBreaks

hardLineBreaks (default value: false)
true

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

false

Interpret all newlines within a paragraph as spaces.

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}
'Twas brillig, and the slithy toves
Did gyre and gimble in the wabe;
All mimsy were the borogoves,
And the mome raths outgrabe.
\end{markdown}

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

\end{document}

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

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

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

2.2.1.26 Option hashEnumerators

hashEnumerators (default value: false)
true

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

#. Bird
#. McHale
#. Parish
false

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

LaTeX Example

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

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

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

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

\end{document}

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

. Bird

. McHale

. Parish

  1. Bird
  2. McHale
  3. Parish
ConTeXt Example

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

\usemodule[t][markdown]
\starttext

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

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

\stoptext

Next, invoke LuaTeX from the terminal:

context document.tex

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

. Bird

. McHale

. Parish

  1. Bird
  2. McHale
  3. Parish

2.2.1.27 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.28 Option html

html (default value: false)
true

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

false

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

Lua Module Example

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 convert = markdown.new()
  local newline = [[^^J^^J]]
  local input =
    "<div>*There is no block tag support.*</div>"        .. newline ..
    "*There is no <inline tag="tag"></inline> support.*" .. newline ..
    "_There is no <!-- comment --> support._"            .. newline ..
    "_There is no <? HTML instruction ?> support._"
  tex.sprint(convert(input)) }
\par
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new({html = true})
  local input =
    "<div>*There is block tag support.*</div>"        .. newline ..
    "*There is <inline tag="tag"></inline> support.*" .. newline ..
    "_There is <!-- comment --> support._"            .. newline ..
    "_There is <? HTML instruction ?> support._"
  tex.sprint(convert(input)) }
\bye

Then, invoke LuaTeX from the terminal:

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
\input optionfalse
\par
\input optiontrue
\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⟩ -- content.md optionfalse.tex
texlua ⟨CLI pathname⟩ html=true -- content.md optiontrue.tex
luatex document.tex

where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\Your username\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -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

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

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

\end{document}

Next, invoke LuaTeX from the terminal:

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

\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 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.29 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 interpretted by TeX. This is encouraged when typesetting automatically generated content or markdown documents that were not prepared with this package in mind.

Lua Module Example

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_safe, convert_unsafe, paragraph

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

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

Then, invoke LuaTeX from the terminal:

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
\input optionfalse

\begingroup
\catcode`\%=12
\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 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.30 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 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.31 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 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.32 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,3 and another.4

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 document.tex

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

Here is a note reference,5 and another.6

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

2.2.1.33 Option pipeTables

pipeTables (default value: false)
true

Enable the PHP Markdown pipe table syntax extension:

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

Disable the PHP Markdown pipe table syntax extension.

LaTeX Example

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

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

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1
ConTeXt Example

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

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

Next, invoke LuaTeX from the terminal:

context document.tex

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

Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

2.2.1.34 Option preserveTabs

preserveTabs (default value: false)
true

Preserve tabs in code block and fenced code blocks.

false

Convert any tabs in the input to spaces.

2.2.1.35 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.36 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.37 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 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.38 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 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.39 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
\def\markdownRendererEllipsis{. . .}
\input lmfonts
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new()
  local input = "These are just three regular dots ..."
  tex.sprint(convert(input)) }
\par
\directlua{
  local markdown = require("markdown")
  local convert = markdown.new({smartEllipses = true})
  local input = "... and this is a victorian ellipsis."
  tex.sprint(convert(input)) }
\bye

Then, invoke LuaTeX from the terminal:

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
\def\markdownRendererEllipsis{. . .}
\input lmfonts
\input optionfalse
\par
\input optiontrue
\bye

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

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 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.40 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. fourth item
  3. fifth item

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

  1. third item
  2. fourth item
  3. fifth item
ConTeXt Example

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

\usemodule[t][markdown]
\starttext

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

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

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

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

Next, invoke LuaTeX from the terminal:

context 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. fourth item
  3. fifth item

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

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

2.2.1.41 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 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.42 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 document.tex

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

2.2.1.43 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 document.tex

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

H2O is a liquid.

2.2.1.44 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 document.tex

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

210 is 1024.

2.2.1.45 Option tableCaptions

tableCaptions (default value: false)
true

Enable the Pandoc table_captions 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_captions syntax extension.

LaTeX Example

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

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

: Demonstration of pipe table syntax.
\end{markdown}
\end{document}

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

Demonstration of pipe table syntax.
Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1
ConTeXt Example

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

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

: Demonstration of pipe table syntax.
\stopmarkdown
\stoptext

Next, invoke LuaTeX from the terminal:

context document.tex

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

Demonstration of pipe table syntax.
Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

2.2.1.46 Option taskLists

taskLists (default value: false)
true

Enable the Pandoc task_lists syntax extension.

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

Disable the Pandoc task_lists syntax extension.

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 document.tex

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

2.2.1.47 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 document.tex

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

2.2.1.48 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.49 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 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}

2.2.2.2 Finalizing and Freezing the Cache

The \markdownOptionFrozenCache option uses the mapping previously created by the Lua interface finalizeCache option, and uses it to typeset the plain TeX document without invoking Lua. As a result, the plain TeX document becomes more portable, but further changes in the order and the content of markdown documents will not be reflected. It defaults to false.

The standard usage of the finalizeCache and frozenCache options is as follows:

  1. Remove the cacheDir cache directory with stale auxiliary cache files.
  2. Enable the finalizeCache option.
  3. Typeset the plain TeX document to populate and finalize the cache.
  4. Enable the frozenCache option.
  5. Publish the source code of the plain TeX document and the cacheDir directory.

For more information, see the examples for the finalizeCache option.

2.2.2.3 File and Directory Names

The plain TeX interface provides the following commands that you can use to specify the location of temporary files produced during the conversion from Markdown to TeX:

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\markdownOptionHelperScriptFileName{helper-script.lua}
\def\markdownOptionInputTempFileName{temporary-input.md}
\def\markdownOptionOutputTempFileName{temporary-output.tex}
\def\markdownOptionErrorTempFileName{error-output.txt}
\def\markdownOptionOutputDir{output-directory}
\def\markdownOptionCacheDir{output-directory/cache-directory}
\markdownOptionFinalizeCachetrue
\def\markdownOptionFrozenCacheFileName{output-directory/cache-directory/frozen-cache.tex}
\markdownBegin
Hello *world*!
\markdownEnd
\bye

Next, invoke LuaTeX from the terminal:

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 documents named helper-script.lua, and temporary-output.md should be produced in the folder named output-directory. The document named helper-script.lua will contain Lua code that was executed to convert markdown to plain TeX. The document named temporary-output.tex will contain the input markdown document converted to TeX.

No document named error-output.txt should be produced in the folder named output-directory. This document would only be produced if an error had occured while executing the Lua code. If this happens, please file a bug.

2.2.2.4 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 LaTeX

LaTeX options allow us to disable the redefinition of the default renderer prototypes from plain TeX, load user-defined themes, and invoke user-defined setup snippets.

2.2.3.1 Setting Lua and plain TeX options from LaTeX

As a rule of thumb, we can set all Lua options directly from LaTeX. For example, to set the taskLists Lua option to true, we would include the following code in our LaTeX document:

\markdownSetup{
  taskLists = true,
}

We can also set all plain TeX options directly from LaTeX. For example, to set the \markdownOptionHelperScriptFileName plain TeX option to helper-script.lua, we would inclde the following code in our LaTeX document:

\markdownSetup{
  helperScriptFileName = helper-script.lua,
}

2.2.3.2 No default token renderer prototypes

Default token renderer prototypes require LaTeX packages that may clash with other packages used in a document. Additionally, if we redefine token renderers and renderer prototypes ourselves, the default definitions will bring no benefit to us. Using the plain package option, we can keep the default definitions from the plain TeX implementation and prevent the soft LaTeX prerequisites from being loaded: The plain option must be set before or when loading the package. Setting the option after loading the package will have no effect.

\usepackage[plain]{markdown}

2.2.3.3 LaTeX themes

User-defined LaTeX themes for the Markdown package provide a domain-specific interpretation of Markdown tokens. Similarly to LaTeX packages, themes allow the authors to achieve a specific look and other high-level goals without low-level programming.

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[
  theme = witiko/beamer/MU,
  theme = witiko/dot,
]{markdown}

Due to limitations of LaTeX, themes may not be loaded after the beginning of a LaTeX document.

Example 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[theme=witiko/dot]{markdown}
\setkeys{Gin}{
  width=\columnwidth,
  height=0.65\paperheight,
  keepaspectratio}
\begin{document}
\begin{markdown}
``` dot Various formats of mathemathical formulae
digraph tree {
  margin = 0;
  rankdir = "LR";

  latex -> pmml;
  latex -> cmml;
  pmml -> slt;
  cmml -> opt;
  cmml -> prefix;
  cmml -> infix;
  pmml -> mterms [style=dashed];
  cmml -> mterms;

  latex [label = "LaTeX"];
  pmml [label = "Presentation MathML"];
  cmml [label = "Content MathML"];
  slt [label = "Symbol Layout Tree"];
  opt [label = "Operator Tree"];
  prefix [label = "Prefix"];
  infix [label = "Infix"];
  mterms [label = "M-Terms"];
}
```
\end{markdown}
\end{document}

Next, invoke LuaTeX from the terminal:

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

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

img
witiko/tilde

A theme that makes tilde (~) always typeset the non-breaking space even when the hybrid Lua option is disabled.

LaTeX Example

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

\documentclass{article}
\usepackage[theme=witiko/tilde]{markdown}
\begin{document}
\begin{markdown}
Bartel~Leendert van~der~Waerden
\end{markdown}
\end{document}

Next, invoke LuaTeX from the terminal:

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

2.2.3.4 LaTeX setup snippets

User-defined LaTeX themes provide global control over high-level goals. However, it is often desirable to change only some local aspects of a document. LaTeX setup snippets provide syntactic sugar for defining and invoking various options locally.

Here is how we can use setup snippets to store options and invoke them later:

\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*}

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 the headerAttributes option is enabled.

\markdownRendererAttributeIdentifier represents the ⟨identifier⟩ of a markdown element (id="identifier" in HTML and #identifier⟩ in Markdown’s headerAttributes syntax extension). 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’s headerAttributes syntax extension). The macro receives a single attribute that corresponds to the .

\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 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 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 an inline bracketed span in which the attributes of the 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 = {
    fencedDivAttributeContextBegin = {(},
    fencedDivAttributeContextEnd = {)},
  },
}
\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 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 Code Block Renderers

The \markdownRendererInputVerbatim macro represents a code block. The macro receives a single argument that corresponds to the filename of a file contaning the code block contents.

The \markdownRendererInputFencedCode macro represents a fenced code block. This macro will only be produced, when the fencedCode option is enabled. The macro receives two arguments that correspond to the filename of a file contaning the code block contents and to the code fence infostring.

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.6 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 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.7 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 kpathsea7 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 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.8 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 an item with several paragraphs of text (the list is not 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 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.9 Ellipsis Renderer

The \markdownRendererEllipsis macro replaces any occurance 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 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.10 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.

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 document.tex

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

This is emphasis.

This is strong emphasis.

The \markdownRendererStrongEmphasis macro represents a strongly emphasized span of text. The macro receives a single argument that corresponds to the emphasized span of text.

2.3.1.11 Fenced Div 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 div in which the attributes of the 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[fencedDiv]{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.12 Header Attribute Context Renderers

The following macros are only produced, when the headerAttributes option is enabled.

The \markdownRendererHeaderAttributeContextBegin and \markdownRendererHeaderAttributeContextEnd macros represent the beginning and the end of a section 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.13 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 document.tex

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

65536

2.3.1.14 HTML Comment Renderers

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.

The \markdownRendererBlockHtmlCommentBegin and \markdownRendererBlockHtmlCommentEnd macros represent the beginning and the end of a block HTML comment. 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[html]{markdown}
\usepackage{marginnote}
\markdownSetup{
  renderers = {
    inlineHtmlComment = {\marginnote{#1}},
    blockHtmlCommentBegin = {\begin{quote}},
    blockHtmlCommentEnd = {\end{quote}},
  },
}
\begin{document}
\begin{markdown}
A useful use of inline HTML comments are side notes.
<!-- Side notes are displayed in the horizontal margins next to the relevant
passages, which makes them *easier for the reader to find* than notes. -->

We can render block HTML comments as blockquotes:

<!--
Here is a block HTML comment with a code example that a programmer might understand:

    foo = bar + baz - 42
-->
\end{markdown}
\end{document}

Next, invoke LuaTeX from the terminal:

lualatex document.tex
lualatex document.tex

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

A useful use of HTML comments are side notes.

We can render block HTML comments as blockquotes:

Here is a block HTML comment with a code example that a programmer might understand:

foo = bar + baz - 42

The horizontal margins should contain the following text:

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

2.3.1.15 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.16 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{\__markdowninput"\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.17 Interblock Separator Renderer

The \markdownRendererInterblockSeparator macro represents a separator between two markdown block elements. The macro receives no arguments.

Plain TeX Example

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

\input markdown
\def\markdownRendererInterblockSeparator{%
  \par
  {\it(The end of a block)}%
  \par
}
\markdownBegin
Hello *world*!

_Foo_ bar!
\markdownEnd
\bye

Next, invoke LuaTeX from the terminal:

luatex document.tex

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

Hello world!

(The end of a block)

Foo bar!

LaTeX Example

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

\documentclass{article}
\usepackage{markdown}
\markdownSetup{
  renderers = {
    interblockSeparator = {%
      \par
      \emph{(The end of a block)}%
      \par
    },
  },
}
\begin{document}
\begin{markdown}
Hello *world*!

_Foo_ bar!
\end{markdown}
\end{document}

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

Hello world!

(The end of a block)

Foo bar!

ConTeXt Example

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

\usemodule[t][markdown]
\def\markdownRendererInterblockSeparator{%
  \par
  \emph{(The end of a block)}%
  \par
}
\starttext
\startmarkdown
Hello *world*!

_Foo_ bar!
\stopmarkdown
\stoptext

Next, invoke LuaTeX from the terminal:

context 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.18 Line Break Renderer

The \markdownRendererLineBreak macro represents a forced 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\markdownRendererLineBreak{%
  \par
  {\it(A forced linebreak)}%
  \par
}
\markdownInput{example.md}
\bye

Using a text editor, create a text document named example.md with the following content. Note the two spaces at the end of the first line, which specify a hard linebreak. Due to the limitations of the TeX input processor, hard linebreaks would be ignored if we typed them directly into the document.tex document.

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 forced linebreak)

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 = {
    lineBreak = {%
      \par
      \emph{(A forced linebreak)}%
      \par
    },
  },
}
\begin{document}
\markdownInput{example.md}
\end{document}

Using a text editor, create a text document named example.md with the following content. Note the two spaces at the end of the first line, which specify a hard linebreak. Due to the limitations of the TeX input processor, hard linebreaks would be ignored if we typed them directly into the document.tex document.

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 forced linebreak)

Foo bar!

ConTeXt Example

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

\usemodule[t][markdown]
\def\markdownRendererLineBreak{%
  \par
  \emph{(A forced linebreak)}%
  \par
}
\starttext
\markdownInput{example.md}
\stoptext

Using a text editor, create a text document named example.md with the following content. Note the two spaces at the end of the first line, which specify a hard linebreak. Due to the limitations of the TeX input processor, hard linebreaks would be ignored if we typed them directly into the document.tex document.

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 forced linebreak)

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 document.tex

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

Please visit the link https://ctan.org/ titled the Comprehensive TeX Archive Network.

2.3.1.20 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.21 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.22 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 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.23 Ordered List Renderers

The \markdownRendererOlBegin macro represents the beginning of an ordered list that contains an item with several paragraphs of text (the list is not tight). This macro will only be produced, when the fancyLists option is disabled. The macro receives no arguments.

The \markdownRendererOlBeginTight macro represents the beginning of an ordered list that contains no item with several paragraphs of text (the list is tight). This macro will only be produced, when the tightLists option is enabled and the fancyLists option is disabled. The macro receives no arguments.

The \markdownRendererFancyOlBegin macro represents the beginning of a fancy ordered list that contains an item with several paragraphs of text (the list is not tight). This macro will only be produced, when the fancyLists option is enabled. The macro receives two arguments: the style of the list item labels (Decimal, LowerRoman, UpperRoman, LowerAlpha, and UpperAlpha), and the style of delimiters between list item labels and texts (Default, OneParen, and Period).

The \markdownRendererFancyOlBeginTight macro represents the beginning of a fancy ordered list that contains no item with several paragraphs of text (the list is tight). This macro will only be produced, when the fancyLists and tightLists options are enabled. The macro receives two arguments: the style of the list item labels, and the style of delimiters between list item labels and texts. See the \markdownRendererFancyOlBegin macro for the valid style values.

The \markdownRendererOlItem macro represents an item in an ordered list. This macro will only be produced, when the startNumber option is disabled and the fancyLists option is disabled. The macro receives no arguments.

The \markdownRendererOlItemEnd macro represents the end of an item in an ordered list. This macro will only be produced, when the fancyLists option is disabled. The macro receives no arguments.

The \markdownRendererOlItemWithNumber macro represents an item in an ordered list. This macro will only be produced, when the startNumber option is enabled and the fancyLists option is disabled. The macro receives a single numeric argument that corresponds to the item number.

The \markdownRendererFancyOlItem macro represents an item in a fancy ordered list. This macro will only be produced, when the startNumber option is disabled and the fancyLists option is enabled. The macro receives no arguments.

The \markdownRendererFancyOlItemEnd macro represents the end of an item in a fancy ordered list. This macro will only be produced, when the fancyLists option is enabled. The macro receives no arguments.

The \markdownRendererFancyOlItemWithNumber macro represents an item in a fancy ordered list. This macro will only be produced, when the startNumber and fancyLists options are enabled. The macro receives a single numeric argument that corresponds to the item number.

The \markdownRendererOlEnd macro represents the end of an ordered list that contains an item with several paragraphs of text (the list is not tight). This macro will only be produced, when the fancyLists option is disabled. The macro receives no arguments.

The \markdownRendererOlEndTight macro represents the end of an ordered list that contains no item with several paragraphs of text (the list is tight). This macro will only be produced, when the tightLists option is enabled and the fancyLists option is disabled. The macro receives no arguments.

The \markdownRendererFancyOlEnd macro represents the end of a fancy ordered list that contains an item with several paragraphs of text (the list is not tight). This macro will only be produced, when the fancyLists option is enabled. The macro receives no arguments.

The \markdownRendererFancyOlEndTight macro represents the end of a fancy ordered list that contains no item with several paragraphs of text (the list is tight). This macro will only be produced, when the fancyLists and tightLists options are enabled. The macro receives no arguments.

Plain TeX Example

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

\input markdown
\def\markdownOptionTightLists{true}
\def\markdownOptionStartNumber{true}

\def\markdownRendererInterblockSeparator{}
\def\markdownRendererOlBeginTight{ (}
\def\markdownRendererOlItemWithNumber#1{%
  \ifnum #1=1\relax
    the first
  \else
    \ifnum #1=2\relax
      , the second
    \else
      , and the third
    \fi
  \fi
}
\def\markdownRendererOlItemEnd{}
\def\markdownRendererOlEndTight{).}

\markdownBegin
This is a tight list

1. item
2. item
3. item
\markdownEnd

\def\markdownRendererInterblockSeparator{%
  :\par
  \def\markdownRendererInterblockSeparator{\par}%
}
\def\markdownRendererOlBegin{}
\def\markdownRendererOlItemWithNumber#1{%
  #1.\kern 0.5em%
  This is the
  \ifnum #1=1\relax
    first
  \else
    \ifnum #1=2\relax
      second
    \else
      third
    \fi
  \fi
}
\def\markdownRendererOlItemEnd{.\par}
\def\markdownRendererOlEnd{}

\markdownBegin
This is a loose list

1. item

2. item

3. item
\markdownEnd

\bye

Next, invoke LuaTeX from the terminal:

luatex document.tex

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

This is a tight list (the first item, the second item, and the third item).

This is a loose list:

  1. This is the first item.

  2. This is the second item.

  3. This is the third item.

LaTeX Example

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

\documentclass{article}
\usepackage[tightLists, startNumber]{markdown}
\begin{document}

\begin{markdown*}{
  renderers = {
    interblockSeparator = {},
    olBeginTight = { (},
    olItemWithNumber = {%
      \ifnum #1=1\relax
        the first
      \else
        \ifnum #1=2\relax
          , the second
        \else
          , and the third
        \fi
      \fi
    },
    olItemEnd = {},
    olEndTight = {).},
  },
}
This is a tight list

1. item
2. item
3. item
\end{markdown*}

\begin{markdown*}{
  renderers = {
    interblockSeparator = {%
      :\par
      \def\markdownRendererInterblockSeparator{\par}%
    },
    olBeginTight = {\begin{enumerate}},
    olItemWithNumber = {%
      \item This is the
      \ifnum #1=1\relax
        first
      \else
        \ifnum #1=2\relax
          second
        \else
          third
        \fi
      \fi
    },
    olItemEnd = {.},
    olEnd = {\end{enumerate}},
  },
}
This is a loose list

1. item

2. item

3. item
\end{markdown*}

\end{document}

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

This is a tight list (the first item, the second item, and the third item).

This is a loose list:

  1. This is the first item.

  2. This is the second item.

  3. This is the third item.

ConTeXt Example

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

\usemodule[t][markdown]
\setupmarkdown
  [
    tightLists = yes,
    startNumber = yes,
  ]
\starttext

\def\markdownRendererInterblockSeparator{}
\def\markdownRendererOlBeginTight{ (}
\def\markdownRendererOlItemWithNumber#1{%
  \ifnum #1=1\relax
    the first
  \else
    \ifnum #1=2\relax
      , the second
    \else
      , and the third
    \fi
  \fi
}
\def\markdownRendererOlItemEnd{}
\def\markdownRendererOlEndTight{).}

\startmarkdown
This is a tight list

1. item
2. item
3. item
\stopmarkdown

\def\markdownRendererInterblockSeparator{%
  :\par
  \def\markdownRendererInterblockSeparator{\par}%
}
\def\markdownRendererOlBegin{\startitemize}
\def\markdownRendererOlItemWithNumber#1{%
  \sym{#1.}
  This is the
  \ifnum #1=1\relax
    first
  \else
    \ifnum #1=2\relax
      second
    \else
      third
    \fi
  \fi
}
\def\markdownRendererOlItemEnd{.\par}
\def\markdownRendererOlEnd{\stopitemize}

\startmarkdown
This is a loose list

1. item

2. item

3. item
\stopmarkdown

\stoptext

Next, invoke LuaTeX from the terminal:

context document.tex

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

This is a tight list (the first item, the second item, and the third item).

This is a loose list:

  1. This is the first item.

  2. This is the second item.

  3. This is the third item.

2.3.1.24 Parenthesized Citations Renderer

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.

2.3.1.25 Raw Content Renderers

The \markdownRendererInputRawInline macro represents an inline raw span. The macro receives two arguments: the filename of a file contaning the inline raw span contents and the raw attribute that designates the format of the inline raw span. This macro will only be produced, when the rawAttribute option is enabled.

The \markdownRendererInputRawBlock macro represents a raw block. The macro receives two arguments: the filename of a file contaning the raw block and the raw attribute that designates the format of the raw block. This macro will only be produced, when the 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.26 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 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.27 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 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.28 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 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.29 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 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.30 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 colums wide
      and #2 rows long.
      \rowCounter=0%
      \def\rowTotal{#2}%
      \def\columnTotal{#3}%
      \processRow
    },
  },
}
\begin{document}
\begin{markdown}
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

  : Demonstration of pipe table syntax
\end{markdown}
\end{document}

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

This is a table with caption Demonstration of pipe table syntax that is 4 colums wide and 4 rows long. As for the alignment, column number 1 is right-aligned, column number 2 is left-aligned, column number 3 has default alignment, and column number 4 is centered. In row 1, column number 1 says Right, column number 2 says Left, column number 3 says Default, and column number 4 says Center. In row 2, column number 1 says 12, column number 2 says 12, column number 3 says 12, and column number 4 says 12. In row 3, column number 1 says 123, column number 2 says 123, column number 3 says 123, and column number 4 says 123. In row 4, column number 1 says 1, column number 2 says 1, column number 3 says 1, and column number 4 says 1.

2.3.1.31 Text Citations Renderer

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.32 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 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.33 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 document.tex

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

2.3.1.34 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 \markdownRendererJekyllDataString macro represents a string 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, cast to a string following yaml serialization rules, and the scalar value.

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\markdownRendererJekyllDataString#1#2{\gdef\name{#2}}
\def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}}
\def\markdownRendererJekyllDataEnd{%
  \name{} is \age{} years old.}
\markdownBegin
---
name: Jane Doe
age:  99
---
\markdownEnd
\bye

Next, invoke LuaTeX from the terminal:

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 = {
    jekyllDataString = {\gdef\name{#2}},
    jekyllDataNumber = {\gdef\age{#2}},
    jekyllDataEnd = {\name{} is \age{} years old.},
  }
}
\begin{document}

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

\end{document}

Next, invoke LuaTeX from the terminal:

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\markdownRendererJekyllDataString#1#2{\gdef\name{#2}}
\def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}}
\def\markdownRendererJekyllDataEnd{%
  \name{} is \age{} years old.}
\starttext

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

\stoptext

Next, invoke LuaTeX from the terminal:

context 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 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 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. Inlines notes are easier to write, since you don’t have to pick an identifier and move down to type the note.↩︎

  3. Here is the note.↩︎

  4. 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.↩︎

  5. Here is the note.↩︎

  6. 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.↩︎

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