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 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 beginner 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 a working TeX distribution. TeX Live ≥ 2013 is known to work and so are recent installation of MikTeX. If you are using a minimal installation of a TeX distribution, please consult the technical documentation for a detailed list of required packages.

1.2 Installation

The package comes pre-installed with TeX Live ≥ 2016 and with recent installations of MikTeX. Unless you explicitly wish to use the latest version of the package, you are encouraged to skip this step.

To install the package, first download the package from the repository using Git:

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

Next, enter the directory named markdown and interpret the file named markdown.ins file using a Unicode-aware TeX engine, such as XeTeX or LuaTeX:

cd markdown
luatex markdown.ins

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.

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.

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 kpse = require("kpse")
kpse.set_program_name("luatex")
local markdown = require("markdown")
local convert = markdown.new()
print(convert("Hello *world*!"))

Next, invoke LuaTeX from the terminal:

texlua hello.lua > hello.tex
luatex document.tex

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

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

1.3.1.2 Using the Lua CLI

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

This section will show how to use the package by example.

2.1 Lua

The Lua part of the package makes it possible to convert a markdown document into TeX commands and typeset it later when convenient. Although the typical user will not find this terribly useful and will instead use the plain TeX, LaTeX, and ConTeXt macro packages to convert and typeset the markdown documents in a single step, they will still benefit from learning the options that control the behavior of the Lua parser.

2.1.1 Interfaces

The Lua part of the package exposes two interfaces – the markdown Lua module, and the Lua command-line interface (CLI).

2.1.1.1 The Lua module

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

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

\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 kpse = require("kpse")
kpse.set_program_name("luatex")
local markdown = require("markdown")
local convert_safe = markdown.new()
local convert_unsafe = markdown.new({hybrid = true})
local input = [[$\sqrt{-1}$ *equals* $i$.]]
print(convert_safe(input) .. " " .. convert_unsafe(input))

Next, invoke LuaTeX from the terminal:

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

A PDF document named document.pdf should be produced and contain the text “$\sqrt{-1}$ equals $i$. √-̅1̅ equals i.” Invoking pdfTeX should have the same effect:

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 convert_safe = markdown.new()
  local convert_unsafe = markdown.new({hybrid = true})
  local input = [[$\noexpand\sqrt{-1}$ *equals* $i$.]]
  tex.sprint(convert_safe(input) .. " " .. convert_unsafe(input)) }
\bye

Next, invoke LuaTeX from the terminal:

luatex document.tex

A PDF document named document.pdf should be produced and contain the text “$\sqrt {-1}$ equals $i$. √-̅1̅ equals i.” In this case, we cannot use pdfTeX, because pdfTeX does not define the \directlua TeX command.

2.1.1.2 The Lua CLI

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

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

\input markdown
\input lmfonts
\input safe\ \input unsafe
\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 markdown-cli.lua to locate the Lua CLI script file using Kpathsea.

A PDF document named document.pdf should be produced and contain the text “$\sqrt{-1}$ equals $i$. √-̅1̅ equals i.” Invoking pdfTeX should have the same effect:

texlua <CLI␣PATHNAME> -- example.md safe.tex
texlua <CLI␣PATHNAME> hybrid=true -- example.md unsafe.tex
pdftex document.tex

2.1.2 Options

This section will cover the options recognized by the Lua interface. The interfaces of the plain TeX, LaTeX, and ConTeXt macro packages recognize these options as well, in addition to their own options.

2.1.2.1 File and Directory Names

2.1.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 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]
\def\markdownOptionCacheDir{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.1.2.2 Parser Options

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

\def\markdownOptionBlankBeforeBlockquote{true}
\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.1.2.2.2 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 code fence."  .. newline ..
          "```"            .. newline
  tex.sprint(convert(input))

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

Then, invoke LuaTeX from the terminal:

luatex document.tex

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

A paragraph.

A code fence.

A paragraph. Not a code fence.

Lua CLI example

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 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 code fence.
```
\markdownEnd

\def\markdownOptionBlankBeforeCodeFence{true}
\markdownBegin
A paragraph.
```
Not a code fence.
```
\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 code fence.

A paragraph. Not a code fence.

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 code fence.
```
\end{markdown}

\begin{markdown*}{blankBeforeCodeFence}
A paragraph.
```
Not a code fence.
```
\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 code fence.

A paragraph. Not a code fence.

ConTeXt example

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

\usemodule[t][markdown]
\def\markdownOptionFencedCode{true}
\starttext

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

\def\markdownOptionBlankBeforeCodeFence{true}
\startmarkdown
A paragraph.
```
Not a code fence.
```
\stopmarkdown

\stoptext

Next, invoke LuaTeX from the terminal:

context document.tex

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

A paragraph.

A code fence.

A paragraph. Not a code fence.

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

\def\markdownOptionBlankBeforeHeading{true}
\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.1.2.2.4 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 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

\def\markdownOptionBreakableBlockquotes{true}
\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.1.2.2.5 Option citationNbsps
citationNbsps (default value: true)
true

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

false

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

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

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

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

References

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

2.1.2.2.6 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.1.2.2.7 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 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

\def\markdownOptionCodeSpans{false}
\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.1.2.2.8 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]
\def\markdownOptionContentBlocks{true}
\definetyping [ConTeXt]
\setuptyping  [ConTeXt] [option=TEX]
\starttext
\startmarkdown
/table.csv  (An example table)
/code.tex   (An example code listing)
/part.md    (A file transclusion example)
\stopmarkdown
\stoptext

Next, invoke LuaTeX from the terminal:

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

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]
\def\markdownOptionContentBlocks{true}
\def\markdownOptionContentBlocksLanguageMap{language-map.json}
\definetyping [ConTeXt]
\setuptyping  [ConTeXt] [option=TEX]
\starttext
\startmarkdown
/table.csv  (An example table)
/code.tex   (An example code listing)
/part.md    (A file transclusion example)
\stopmarkdown
\stoptext

Next, invoke LuaTeX from the terminal:

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.1.2.2.10 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]
\def\markdownOptionDefinitionLists{true}
\starttext
\startmarkdown
Term 1

:   Definition 1

Term 2 with *inline markup*

:   Definition 2

        { some code, part of Definition 2 }

    Third paragraph of definition 2.
\stopmarkdown
\stoptext

Next, invoke LuaTeX from the terminal:

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

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

Next, invoke LuaTeX from the terminal:

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.1.2.2.12 Option footnotes
footnotes (default value: false)
true

Enable the pandoc footnote syntax extension:

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

[^1]: Here is the footnote.

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

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

        { some.code }

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

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

Disable the pandoc footnote syntax extension.

LaTeX example

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

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

[^1]: Here is the footnote.

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

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

        { some.code }

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

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

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

Here is a footnote reference,1 and another.2

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]
\def\markdownOptionFootnotes{true}
\starttext
\startmarkdown
Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.

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

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

        { some.code }

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

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

Next, invoke LuaTeX from the terminal:

context document.tex

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

Here is a footnote reference,3 and another.4

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

2.1.2.2.13 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

\def\markdownOptionHashEnumerators{true}
\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.1.2.2.14 Option html
html (default value: false)
true

Enable the recognition of HTML tags, block elements, comments, HTML instructions, and entities in the input. Tags, block elements (along with contents), HTML instructions, and comments will be ignored and HTML entities will be replaced with the corresponding Unicode codepoints.

false

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

When the option is enabled, HTML entities are currently incorrectly parsed. See the corresponding issue in the package repository.

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

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

\stoptext

Next, invoke LuaTeX from the terminal:

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.1.2.2.15 Option hybrid
hybrid (default value: true)
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 convert_safe = markdown.new()
  local convert_unsafe = markdown.new({hybrid = true})
  local input = [[$\noexpand\sqrt{-1}$ *equals* $i$.]]
  tex.sprint(convert_safe(input) .. " " .. convert_unsafe(input)) }
\bye

Then, invoke LuaTeX from the terminal:

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
\input optiontrue
\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 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
\def\markdownOptionHybrid{true}
\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.1.2.2.16 Option inlineFootnotes
inlineFootnotes (default value: false)
true

Enable the pandoc inline footnote 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 footnote syntax extension.

LaTeX example

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

\documentclass{article}
\usepackage[footnotes, inlineFootnotes]{markdown}
\begin{document}
\begin{markdown}
Here is an inline note.^[Inlines notes are easier to
write, since you don't have to pick an identifier and
move down to type the note.]
\end{markdown}
\end{document}

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

Here is an inline note.5

ConTeXt example

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

\usemodule[t][markdown]
\def\markdownOptionFootnotes{true}
\def\markdownOptionInlineFootnotes{true}
\starttext
\startmarkdown
Here is an inline note.^[Inlines notes are easier to
write, since you don't have to pick an identifier and
move down to type the note.]
\stopmarkdown
\stoptext

Next, invoke LuaTeX from the terminal:

context document.tex

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

Here is an inline note.6

2.1.2.2.17 Option preserveTabs
preserveTabs (default value: false)
true

Preserve all tabs in the input.

false

Convert any tabs in the input to spaces.

This option is currently non-functional. See the corresponding issue in the package repository.

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

Then, invoke LuaTeX from the terminal:

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

\def\markdownOptionSmartEllipses{true}
\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.1.2.2.19 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

\def\markdownOptionStartNumber{false}
\startmarkdown
The following list respects the numbers specified in the markup:

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

Next, invoke LuaTeX from the terminal:

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.1.2.2.20 Option tightLists
tightLists (default value: true)
true

Lists whose bullets do not consist of multiple paragraphs will be passed to the \markdownRendererOlBeginTight, \markdownRendererOlEndTight, \markdownRendererUlBeginTight, \markdownRendererUlEndTight, \markdownRendererDlBeginTight, and \markdownRendererDlEndTight TeX macros.

false

Lists whose bullets do not consist of multiple paragraphs will be treated the same way as lists that do 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.1.2.2.21 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 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]
\def\markdownOptionHybrid{true}
\starttext

\startmarkdown
This is _emphasized text_ and this is a math subscript: $m\_n$.
\stopmarkdown

\def\markdownOptionUnderscores{false}
\startmarkdown
This is *emphasized text* and this is a math subscript: $m_n$.
\stopmarkdown

\stoptext

Next, invoke LuaTeX from the terminal:

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 Plain TeX

The plain TeX macro package provides TeX commands for typesetting markdown documents that invoke the Lua parser in the background. Beside TeX commands that correspond to the Lua options, the macro package also provides commands corresponding to additional plain TeX-specific options, and so-called token renderer commands that define how the individual markdown elements will be typeset.

2.2.1 Interfaces

2.2.2 Options

2.2.3 Token renderers

2.3 LaTeX

The LaTeX macro package provides additional syntactic sugar on top of the plain TeX macro package and provides sane default definitions of the token renderers.

2.3.1 Interfaces

2.3.2 Options

2.3.3 Token renderers

2.4 ConTeXt

The ConTeXt macro package provides additional syntactic sugar on top of the plain TeX macro package and provides sane default definitions of the token renderers.

2.4.1 Interfaces

2.4.2 Options

2.4.3 Token renderers


  1. Here is the footnote.

  2. Here's one with multiple blocks.

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

    { some.code }

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

  3. Here is the footnote.

  4. Here's one with multiple blocks.

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

    { some.code }

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

  5. Inlines notes are easier to write, since you don't have to pick an identifier and move down to type the note.

  6. Inlines notes are easier to write, since you don't have to pick an identifier and move down to type the note.