1 Introduction

The Markdown package converts markdown markup to T_eX commands. The functionality is provided both as a Lua module and as plain T_eX, L^aT_eX, and ConT_eXt macro packages that can be used to directly typeset T_eX 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 T_eX distribution: T_eX Live ≥ 2020 is known to work with the current version of the Markdown package and so are recent versions of MikT_eX. If you are using an older, incomplete, or atypical T_eX distribution, please consult the technical documentation for a detailed list of requirements.

1.2 Installation

If Markdown is not included in your T_eX 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:

• markdown.lua, the Lua module,
• libraries/markdown-tinyyaml.lua, an external library for reading yaml,
• markdown-cli.lua, the Lua command-line interface,
• markdown.tex, the plain T_eX macro package,
• markdown.sty, the L^aT_eX package,
• markdownthemewitiko_dot.sty, the witiko/dot L^aT_eX theme,
• markdownthemewitiko_graphicx_http.sty, the witiko/graphicx/http L^aT_eX theme,
• markdownthemewitiko_tilde.sty, the witiko/tilde L^aT_eX theme, and
• t-markdown.tex, the ConT_eXt module.

1.2.1 Local Installation

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

• ⟨TEXMF⟩/tex/luatex/markdown/markdown.lua
• ⟨TEXMF⟩/tex/luatex/markdown/markdown-tinyyaml.lua
• ⟨TEXMF⟩/scripts/markdown/markdown-cli.lua
• ⟨TEXMF⟩/tex/generic/markdown/markdown.tex
• ⟨TEXMF⟩/tex/latex/markdown/markdown.sty
• ⟨TEXMF⟩/tex/latex/markdown/markdownthemewitiko_dot.sty
• ⟨TEXMF⟩/tex/latex/markdown/markdownthemewitiko_graphicx_http.sty
• ⟨TEXMF⟩/tex/latex/markdown/markdownthemewitiko_tilde.sty
• ⟨TEXMF⟩/tex/context/third/markdown/t-markdown.tex

where ⟨TEXMF⟩ corresponds to a root of your T_eX 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 T_eX distribution.

1.2.2 Portable Installation

Alternatively, you can also store the above files in the same folder as your T_eX document and distribute them together. This way your document can be portably typeset on legacy T_eX 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 T_eX. 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 T_eX

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 L^aT_eX

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

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

lualatex latex-luatex.tex

to see the effect of your changes.

1.3.4 Using ConT_eXt

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

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 L^aT_eX and ConT_eXt interfaces intended for the ordinary user.

2.1.1 Lua

The Lua programming language is what drives the conversion from markdown to T_eX in the Markdown package. Based on the Lunamark Lua library by John MacFarlane, the Lua implementation is largely independent on T_eX, 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 T_eX from within LuaT_eX documents and Lua scripts.

The markdown Lua module exposes the new(⟨options⟩) method, which creates a converter function from markdown to T_eX. 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$.

$\text{exception 25:}$ 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$.

$\text{exception 25:}$ equals $i$.

In this case, we cannot use pdfTeX, because pdfTeX does not define the \directlua T_eX 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 T_eX 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$.

$\text{exception 25:}$ 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 T_eX

The plain T_eX interface provides T_eX 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 T_eX. Instead, its goal is to provide high-level typesetting capabilities.

The plain T_eX interface accepts the same options as the markdown Lua module, in addition to its own options, but now the options are specified as T_eX 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$.

$\text{exception 25:}$ equals $i$.

Invoking pdfTeX should have the same effect:

pdftex --shell-escape document.tex

2.1.3 L^aT_eX

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

The L^aT_eX interface accepts the same options as the plain T_eX 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* L^aT_eX 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$.

$\text{exception 25:}$ equals $i$.

Invoking pdfTeX should have the same effect:

pdflatex --shell-escape document.tex

2.1.4 ConT_eXt

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

The ConT_eXt interface accepts the same options as the plain T_eX 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$.

$\text{exception 25:}$ equals $i$.

2.2 Options

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

2.2.1 Lua

Lua options control the conversion from markdown to T_eX. They are supported by all interfaces of the Markdown package starting with the low-level Lua interfaces and all the way up to the L^aT_eX and ConT_eXt 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 T_eX 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 T_eX 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.

L^aT_eX 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.

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

L^aT_eX 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.

ConT_eXt 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 T_eX document that contains markdown documents without invoking Lua using the frozenCache plain T_eX option. As a result, the plain T_eX 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 T_eX 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.

L^aT_eX 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.

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

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

L^aT_eX 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.

ConT_eXt 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 T_eX 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.

L^aT_eX 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.

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

L^aT_eX Example

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

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

\begin{markdown}
A paragraph.

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

\begin{markdown*}{blankBeforeDivFence}
A paragraph.

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

\end{document}

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

A paragraph.

A fenced div.

A paragraph.

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

2.2.1.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 T_eX 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. ==============

L^aT_eX 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. ==============

ConT_eXt 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 span syntax extension:

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

false

Disable the Pandoc bracketed span syntax extension.

L^aT_eX Example

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

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

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

Here is some colored text.

2.2.1.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 T_eX 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.

L^aT_eX 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.

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

L^aT_eX 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.

L^aT_eX 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 T_eXbook, 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 T_eX 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.”

L^aT_eX 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.”

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

L^aT_eX 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.

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

L^aT_eX 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.

L^aT_eX 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.

ConT_eXt 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 T_eX 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 T_eX document named hello.tex should be produced and contain the following code:

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

Additionally, a T_eX 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}

L^aT_eX 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 T_eX directory structure.

L^aT_eX 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 syntax extension:

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

false

Disable the Pandoc fancy list syntax extension.

L^aT_eX 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

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

L^aT_eX 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>

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

fencedCodeAttributes (default value: false)

true

Enable the Pandoc fenced code attribute syntax extension:

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

false

Disable the Pandoc fenced code attribute syntax extension.

L^aT_eX Example

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

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

Next, invoke LuaTeX from the terminal:

lualatex --shell-escape document.tex

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

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

2.2.1.23 Option fencedDivs

fencedDivs (default value: false)

true

Enable the Pandoc fenced div syntax extension:

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

And another.
:::::

false

Disable the Pandoc fenced div syntax extension.

L^aT_eX 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.24 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 T_eX document that contains markdown documents without invoking Lua using the frozenCache plain T_eX option. As a result, the plain T_eX document becomes more portable, but further changes in the order and the content of markdown documents will not be reflected.

Plain T_eX 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.

L^aT_eX 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.

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

context 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.25 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 T_eX macro \markdownFrozenCache⟨number⟩ that will typeset markdown document number ⟨number⟩.

Lua Module Example

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

\input markdown
\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.26 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.

L^aT_eX 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.27 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.

L^aT_eX 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

ConT_eXt 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.28 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.29 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 T_eX 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.

L^aT_eX 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.

ConT_eXt 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.30 Option hybrid

hybrid (default value: false)

true

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

false

Enable the escaping of special plain T_eX characters outside verbatim environments, so that they are not interpretted by T_eX. 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$.

$\text{exception 25:}$ 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$.

$\text{exception 25:}$ equals $i$.

Plain T_eX 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$.

$\text{exception 25:}$ equals $i$.

L^aT_eX 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$.

$\text{exception 25:}$ equals $i$.

ConT_eXt 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$.

$\text{exception 25:}$ equals $i$.

2.2.1.31 Option inlineCodeAttributes

inlineCodeAttributes (default value: false)

true

Enable the Pandoc inline code span attribute extension:

`<$>`{.haskell}

false

Enable the Pandoc inline code span attribute extension.

L^aT_eX Example

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

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

Next, invoke LuaTeX from the terminal:

lualatex document.tex

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

Here is some colored text.

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

L^aT_eX 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.¹

ConT_eXt 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.1.33 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 T_eX Example