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 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 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:
markdownthemewitiko_dot.sty, the witiko/dotLaTeX theme,
markdownthemewitiko_graphicx_http.sty, the witiko/graphicx/httpLaTeX theme,
markdownthemewitiko_tilde.sty, the witiko/tildeLaTeX theme, and
t-markdown.tex, the ConTeXt module.
1.2.1 Local Installation
To perform a local installation, place the above files into your TeX directory structure. This is generally where the individual files should be placed:
where <TEXMF> corresponds to a root of your TeX distribution, such as /usr/share/texmf and ~/texmf on UN*X systems or C:\Users\⟨Your username⟩\texmf on Windows systems. When in doubt, consult the manual of your TeX distribution.
1.2.2 Portable Installation
Alternatively, you can also store the above files in the same folder as your TeX document and distribute them together. This way your document can be portably typeset on legacy TeX distributions.
Since Markdown version 2.10.0, the file markdown.tex must be placed in a directory named markdown due to issue #74.
1.3 First Document
In this section, we will take the necessary steps to typeset our first markdown document in TeX. This will serve as our first hands-on experience with the package and also as a reassurance that the package has been correctly installed.
1.3.1 Using Lua
Using a text editor, create a text document named document.tex with the following content:
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:
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:
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:
In this section, I will describe the individual parts of the Markdown package. Each part will be shown by example, leaving the implementation details to the technical documentation.
2.1 Interfaces
In this section, I will describe the individual interfaces exposed by the Markdown package starting with the low-level Lua interfaces and all the way up to the LaTeX and ConTeXt interfaces intended for the ordinary user.
2.1.1 Lua
The Lua programming language is what drives the conversion from markdown to TeX in the Markdown package. Based on the Lunamark Lua library by John MacFarlane, the Lua implementation is largely independent on TeX, and can be used separately from typesetting a document. Lua provides two interfaces: a Lua module and a command-line interface (CLI).
2.1.1.1 Lua Module
A Lua module is a software library that can be used from in other programs. The markdown Lua module makes it possible to convert markdown to TeX from within LuaTeX documents and Lua scripts.
The markdown Lua module exposes the new(⟨options⟩) method, which creates a converter function from markdown to TeX. The properties of the converter function are specified by the Lua table options. The parameter is optional; when unspecified, the behaviour will be the same as if ⟨options⟩ were an empty table.
Using a text editor, create a text document named document.tex with the following content:
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:
A PDF document named document.pdf should be produced and contain the following text:
$\sqrt{-1}$ equals $i$.
√-̅1̅ equalsi.
In this case, we cannot use pdfTeX, because pdfTeX does not define the \directluaTeX command.
2.1.1.2 Lua Command-Line Interface
The Lua command-line interface (CLI) of the Markdown package makes the functionality of the Lua module accessible from the command line. This makes it possible to convert documents from markdown to TeX manually without any knowledge of the Lua programming language.
The Lua command-line interface accepts the same options as the markdown Lua module, but now the options are specified as command-line parameters.
Using a text editor, create a text document named document.tex with the following content:
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:
The plain TeX interface provides TeX commands that typeset markdown documents by using the Lua interface behind the scenes. Unlike the Lua interface, the plain TeX interface does not provide low-level tools for converting markdown to TeX. Instead, its goal is to provide high-level typesetting capabilities.
The plain TeX interface accepts the same options as the markdown Lua module, in addition to its own options, but now the options are specified as TeX commands.
Using a text editor, create a text document named document.tex with the following content:
The LaTeX interface provides the same level of functionality as the plain TeX interface by using the plain TeX interface behind the scenes. Unlike the plain TeX interface, the LaTeX interface uses familiar LaTeX idioms, such as package options and environments.
The LaTeX interface accepts the same options as the plain TeX interface, but now the options are specified as ⟨key⟩ = ⟨value⟩ pairs and they are passed either as package options, in the \markdownSetup command, or as parameters for the markdown*LaTeX environment.
Using a text editor, create a text document named document.tex with the following content:
The ConTeXt interface provides the same level of functionality as the plain TeX interface by using the plain TeX interface behind the scenes. Unlike the plain TeX interface, the ConTeXt interface uses familiar ConTeXt idioms, such as environments.
The ConTeXt interface accepts the same options as the plain TeX interface.
Using a text editor, create a text document named document.tex with the following content:
In this section, I will describe all the options recognized by the Markdown package.
2.2.1 Lua
Lua options control the conversion from markdown to TeX. They are supported by all interfaces of the Markdown package starting with the low-level Lua interfaces and all the way up to the LaTeX and ConTeXt interfaces.
2.2.1.1 Option cacheDir
cacheDir (default value: ".")
A path to the directory containing auxiliary cache files. If the last segment of the path does not exist, it will be created by the Lua command-line and plain TeX implementations. The Lua implementation expects that the entire path already exists.
When iteratively writing and typesetting a markdown document, the cache files are going to accumulate over time. You are advised to clean the cache directory every now and then, or to set it to a temporary filesystem (such as /tmp on UN*X systems), which gets periodically emptied.
Lua Module Example
Using a text editor, create a text document named document.tex with the following content:
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:
where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\⟨Your username⟩\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -a markdown-cli.lua to locate the Lua CLI script file using Kpathsea.
A PDF document named document.pdf should be produced and contain the text “Hello world!” A directory named cache containing several cache files of the Markdown package will also be produced as we requested using the cacheDir option.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
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:
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:
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.
A path to an output file (frozen cache) that will be created when the finalizeCache option is enabled and will contain a mapping between an enumeration of markdown documents and their auxiliary cache files.
The frozen cache makes it possible to later typeset a plain TeX document that contains markdown documents without invoking Lua using the \markdownOptionFrozenCache plain TeX option. As a result, the plain TeX document becomes more portable, but further changes in the order and the content of markdown documents will not be reflected.
Lua Module Example
Using a text editor, create a text document named document.tex with the following content:
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:
where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\⟨Your username⟩\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -a markdown-cli.lua to locate the Lua CLI script file using Kpathsea.
A PDF document named document.pdf should be produced and contain the text “Hello world!” A frozen cache will also be produced in the cache.tex output file as we requested using the finalizeCache and frozenCacheFileName options.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
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:
A PDF document named frozen-document.pdf should be produced and contain the text “Hello world!” Since we used the contents of the frozen cache using the \markdownOptionFrozenCache option, we were able to typeset the document without accessing the shell or invoking Lua, but the change in the content of the markdown document from “Hello world!” to “Hi world!” was not reflected.
LaTeX Example
Using a text editor, create a text document named document.tex with the following content:
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:
A PDF document named frozen-document.pdf should be produced and contain the text “Hello world!” Since we used the contents of the frozen cache using the frozencache option, we were able to typeset the document without accessing the shell or invoking Lua, but the change in the content of the markdown document from “Hello world!” to “Hi world!” was not reflected.
ConTeXt Example
Using a text editor, create a text document named document.tex with the following content:
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:
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.3 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:
where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\⟨Your username⟩\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -a markdown-cli.lua to locate the Lua CLI script file using Kpathsea.
A PDF document named document.pdf should be produced and contain the following text:
A paragraph.
A quote?
A paragraph. > A quote?
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\⟨Your username⟩\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -a markdown-cli.lua to locate the Lua CLI script file using Kpathsea.
A PDF document named document.pdf should be produced and contain the following text:
A paragraph.
A code fence?
A paragraph. A code fence?
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\⟨Your username⟩\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -a markdown-cli.lua to locate the Lua CLI script file using Kpathsea.
A PDF document named document.pdf should be produced and contain the following text:
A paragraph.
A heading?
A paragraph. A heading? ==========
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\⟨Your username⟩\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -a markdown-cli.lua to locate the Lua CLI script file using Kpathsea.
A PDF document named document.pdf should be produced and contain the following text:
A single block quote or two block quotes?
A single block quote
or two block quotes?
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
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.7 Option citationNbsps
citationNbsps (default value: true)
true
Replace regular spaces with non-breaking spaces inside the prenotes and postnotes of citations produced via the pandoc citation syntax extension.
false
Do not replace regular spaces with non-breaking spaces inside the prenotes and postnotes of citations produced via the pandoc citation syntax extension.
LaTeX Example
Using a text editor, create a text document named document.bib with the following content:
where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\⟨Your username⟩\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -a markdown-cli.lua to locate the Lua CLI script file using Kpathsea.
A PDF document named document.pdf should be produced and contain the following text:
“Is this a code span?” “Or a quote?”
Is this a code span?''Or a quote?’’
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
Whether an output file specified with the frozenCacheFileName option (frozen cache) that contains a mapping between an enumeration of markdown documents and their auxiliary cache files will be created.
The frozen cache makes it possible to later typeset a plain TeX document that contains markdown documents without invoking Lua using the \markdownOptionFrozenCache plain TeX option. As a result, the plain TeX document becomes more portable, but further changes in the order and the content of markdown documents will not be reflected.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
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:
A new PDF document named document.pdf should be produced and contain the same text “Hello world!” Since we used the contents of the frozen cache using the \markdownOptionFrozenCache option, we were able to typeset the document without accessing the shell or invoking Lua, but the change in the content of the markdown document from “Hello world!” to “Hi world!” was not reflected.
LaTeX Example
Using a text editor, create a text document named document.tex with the following content:
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:
A new PDF document named document.pdf should be produced and contain the same text “Hello world!” Since we used the contents of the frozen cache using the \markdownOptionFrozenCache option, we were able to typeset the document without accessing the shell or invoking Lua, but the change in the content of the markdown document from “Hello world!” to “Hi world!” was not reflected.
ConTeXt Example
Using a text editor, create a text document named document.tex with the following content:
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:
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.
This paragraph won’t be part of the note, because it isn’t indented.
2.2.1.16 Option frozenCacheCounter
frozenCacheCounter (default value: 0)
The number of the current markdown document that will be stored in an output file (frozen cache) when the finalizeCache is enabled. When the document number is 0, then a new frozen cache will be created. Otherwise, the frozen cache will be appended.
Each frozen cache entry will define a TeX macro \markdownFrozenCache⟨number⟩ that will typeset markdown document number ⟨number⟩.
Lua Module Example
Using a text editor, create a text document named document.tex with the following content:
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.17 Option hashEnumerators
hashEnumerators (default value: false)
true
Enable the use of hash symbols (#) as ordered item list markers:
These HTML attributes have currently no effect other than enabling content slicing.
false
Disable the assignment of HTML attributes to headings.
2.2.1.19 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.
Lua Module Example
Using a text editor, create a text document named document.tex with the following content:
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:
where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\⟨Your username⟩\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -a markdown-cli.lua to locate the Lua CLI script file using Kpathsea.
A PDF document named document.pdf should be produced and contain the following text:
<div>Is there block tag support?</div> Is there <inline tag=”tag”></inline> support? Is there <!– comment –> support? Is there <? HTML instruction ?> support?
Is there support? Is there support? Is there support?
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
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:
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:
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.20 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:
where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\⟨Your username⟩\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -a markdown-cli.lua to locate the Lua CLI script file using Kpathsea.
A PDF document named document.pdf should be produced and contain the following text:
$\sqrt {-1}$ equals $i$.
√-̅1̅ equalsi.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
Right
Left
Default
Center
12
12
12
12
123
123
123
123
1
1
1
1
2.2.1.23 Option preserveTabs
preserveTabs (default value: false)
true
Preserve tabs in code block and fenced code blocks.
false
Convert any tabs in the input to spaces.
2.2.1.24 Option shiftHeadings
shiftHeadings (default value: 0)
All headings will be shifted by ⟨shift amount⟩, which can be both positive and negative. Headings will not be shifted beyond level 6 or below level 1. Instead, those headings will be shifted to level 6, when ⟨shift amount⟩ is positive, and to level 1, when ⟨shift amount⟩ is negative.
Plain TeX Example
Using a text editor, create a text document named example.md with the following content:
A PDF document named document.pdf should be produced and contain the following text:
A section
A section
A section
2.2.1.25 Option slice
slice (default value: ^ $)
Two space-separated selectors that specify the slice of a document that will be processed, whereas the remainder of the document will be ignored. The following selectors are recognized:
The circumflex (^) selects the beginning of a document.
The dollar sign ($) selects the end of a document.
^⟨identifier⟩ selects the beginning of a section with the HTML attribute#⟨identifier⟩.
$⟨identifier⟩ selects the end of a section with the HTML attribute #⟨identifier⟩.
⟨identifier⟩ corresponds to ^⟨identifier⟩ for the first selector and to $⟨identifier⟩ for the second selector.
Specifying only a single selector, ⟨identifier⟩, is equivalent to specifying the two selectors ⟨identifier⟩ ⟨identifier⟩, which is equivalent to ^⟨identifier⟩ $⟨identifier⟩, i.e. the entire section with the HTML attribute #⟨identifier⟩ will be selected.
Plain TeX Example
Using a text editor, create a text document named hamlet.md with the following content:
where ⟨CLI pathname⟩ corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\⟨Your username⟩\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich -a markdown-cli.lua to locate the Lua CLI script file using Kpathsea.
A PDF document named document.pdf should be produced and contain the following text:
Are these just three regular dots, a victorian ellipsis, or … ?
Are these just three regular dots, a victorian ellipsis, or . . . ?
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the text “Hello world!”
2.2.1.31 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 \markdownRendererDlEndTightTeX 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:
Only asterisks can be used to denote emphasis and strong emphasis. This makes it easy to write math with the hybrid option without the need to constantly escape subscripts.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is emphasized text and this is a math subscript: mₙ.
This is emphasized text and this is a math subscript: mₙ.
2.2.2 Plain TeX
Plain TeX options control the communication between the TeX interface and the markdown Lua module. They are supported by all higher-level interfaces of the Markdown package, i.e. the plain TeX, LaTeX and ConTeXt interfaces.
2.2.2.1 Finalizing and Freezing the Cache
The \markdownOptionFrozenCache option uses the mapping previously created by the Lua interface finalizeCache option, and uses it to typeset the plain TeX document without invoking Lua. As a result, the plain TeX document becomes more portable, but further changes in the order and the content of markdown documents will not be reflected. It defaults to false.
The standard usage of the finalizeCache and \markdownOptionFrozenCache options is as follows:
Remove the cacheDir cache directory with stale auxiliary cache files.
Enable the finalizeCache option.
Typeset the plain TeX document to populate and finalize the cache.
Enable the \markdownOptionFrozenCache option.
Publish the source code of the plain TeX document and the cacheDir directory.
For more information, see the examples for the finalizeCache option.
2.2.2.2 File and Directory Names
The plain TeX interface provides the following commands that you can use to specify the location of temporary files produced during the conversion from Markdown to TeX:
\markdownOptionHelperScriptFileName,
\markdownOptionInputTempFileName,
\markdownOptionOutputTempFileName,
\markdownOptionErrorTempFileName,
\markdownOptionOutputDir,
\markdownOptionCacheDir, and
\markdownOptionFrozenCacheFileName.
Using a text editor, create a folder named output-directory and a text document named document.tex with the following content:
A text document named temporary-input.md should be produced in the folder named output-directory and contain the following text:
Hello *world*!
A folder named output-directory/cache-directory should also be produced and contain fragments of the converted markdown document. LuaTeX does not need other temporary files to perform the conversion from markdown to TeX. To produce the remaining temporary files, invoke pdfTeX from the terminal:
Text documents named helper-script.lua, and temporary-output.md should be produced in the folder named output-directory. The document named helper-script.lua will contain Lua code that was executed to convert markdown to plain TeX. The document named temporary-output.tex will contain the input markdown document converted to TeX.
No document named error-output.txt should be produced in the folder named output-directory. This document would only be produced if an error had occured while executing the Lua code. If this happens, please file a bug.
2.2.2.3 Package Documentation
The \markdownOptionStripPercentSigns macro controls whether a percent sign (%) at the beginning of a line will be discarded when reading Markdown input from a TeX document. This enables the use of markdown when writing TeX package documentation using the Doc LaTeX package by Frank Mittelbach. The recognized values of the macro are true (discard) and false (retain). It defaults to false.
Using a text editor, create a text document named document.dtx with the following content:
A PDF document named document.pdf should be produced and contain the text “Hello world!”
2.2.3LaTeX
LaTeX options allow us to disable the redefinition of the default renderer prototypes from plain TeX, load user-contributed themes, and invoke user-defined setup snippets.
2.2.3.1 No default token renderer prototypes
Default token renderer prototypes require LaTeX packages that may clash with other packages used in a document. Additionally, if we redefine token renderers and renderer prototypes ourselves, the default definitions will bring no benefit to us. Using the plain package option, we can keep the default definitions from the plain TeX implementation (see Section ) and prevent the soft LaTeX prerequisites in Section from being loaded:
User-contributed LaTeX themes for the Markdown package provide a domain-specific interpretation of some Markdown tokens. Similarly to LaTeX packages, themes allow the authors to achieve a specific look and other high-level goals without low-level programming.
For example, to load themes named witiko/beamer/MU and witiko/dot, you would use the following code in the preamble of your document:
Due to limitations of LaTeX, themes may not be loaded after the beginning of a LaTeX document.
Example themes provided with the Markdown package include:
witiko/dot
A theme that typesets fenced code blocks with the dot … infostring as images of directed graphs rendered by the Graphviz tools. The right tail of the infostring is used as the image title. The theme requires a Unix-like operating system with GNU Diffutils and Graphviz installed. The theme also requires shell access unless the \markdownOptionFrozenCache plain TeX option is enabled.
LaTeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain a drawing of a directed graph similar to Figure 1 from the following conference article:
NOVOTNÝ, Vít, Petr SOJKA, Michal ŠTEFÁNIK and Dávid LUPTÁK. Three is Better than One: Ensembling Math Information Retrieval Systems. CEUR Workshop Proceedings. Thessaloniki, Greece: M. Jeusfeld c/o Redaktion Sun SITE, Informatik V, RWTH Aachen., 2020, vol. 2020, No 2696, p. 1-30. ISSN 1613-0073. http://ceur-ws.org/Vol-2696/paper_235.pdf
witiko/graphicx/http
A theme that adds support for downloading images whose URL has the http or https protocol. The theme requires the catchfileLaTeX package and a Unix-like operating system with GNU Coreutils md5sum and either GNU Wget or cURL installed. The theme also requires shell access unless the \markdownOptionFrozenCache plain TeX option is enabled.
LaTeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text, where the middot (·) denotes a non-breaking space:
Bartel·Leendert van·der·Waerden
2.2.3.3LaTeX setup snippets
User-contributed LaTeX themes provide global control over high-level goals. However, it is often desirable to change only some local aspects of a document. LaTeX setup snippets provide syntactic sugar for defining and invoking various options locally.
Here is how we can use setup snippets to store options and invoke them later:
A key feature of the Markdown package is the support for manipulating markdown tokens, such as headings, emphasized text, links, and lists, in TeX. Instead of reducing TeX to a PDF document producer, the Markdown package allows the user to specify how every markdown token should be processed and rendered.
2.3.1 Token Renderers
Token renderers are user-defined TeX macros, which render markdown tokens. In this section, I will describe the individual token renderers.
2.3.1.1 Interblock Separator Renderer
The \markdownRendererInterblockSeparator macro represents a separator between two markdown block elements. The macro receives no arguments.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
Using a text editor, create a text document named example.md with the following content. Note the two spaces at the end of the first line, which specify a hard linebreak. Due to the limitations of the TeX input processor, hard linebreaks would be ignored if we typed them directly into the document.tex document.
Using a text editor, create a text document named example.md with the following content. Note the two spaces at the end of the first line, which specify a hard linebreak. Due to the limitations of the TeX input processor, hard linebreaks would be ignored if we typed them directly into the document.tex document.
Using a text editor, create a text document named example.md with the following content. Note the two spaces at the end of the first line, which specify a hard linebreak. Due to the limitations of the TeX input processor, hard linebreaks would be ignored if we typed them directly into the document.tex document.
A PDF document named document.pdf should be produced and contain the following text:
Hello world!
(A forced linebreak)
Foo bar!
2.3.1.3 Ellipsis Renderer
The \markdownRendererEllipsis macro replaces any occurance of ASCII ellipses in the input text. This macro will only be produced, when the smartEllipses option is enabled. The macro receives no arguments.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
The TeXbook [1, p.·123·and·130] is good.
References
[1] Donald Ervin Knuth. The TeXbook, volume A of Computers and typesetting. Addison-Wesley, 1984.
2.3.1.5 Special Character Renderers
The following macros replace any special plain TeX characters, including the active pipe character (|) of ConTeXt, in the input text:
\markdownRendererAmpersand replaces the ampersand (&).
\markdownRendererBackslash replaces the backslash (\).
\markdownRendererCircumflex replaces the circumflex (^).
\markdownRendererDollarSign replaces the dollar sign ($).
\markdownRendererHash replaces the hash sign (#).
\markdownRendererLeftBrace replaces the left brace ({).
\markdownRendererPercentSign replaces the percent sign (%).
\markdownRendererPipe replaces the pipe character (|).
\markdownRendererRightBrace replaces the right brace (}).
\markdownRendererTilde replaces the tilde (~).
\markdownRendererUnderscore replaces the underscore (_).
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content. We will make the tilde behave as if it were written in TeX, where it represents a non-breaking space.
A PDF document named document.pdf should be produced and contain the following text, where the middot (·) denotes a non-breaking space:
Bartel·Leendert van·der·Waerden
LaTeX Example
Using a text editor, create a text document named document.tex with the following content. We will make the tilde behave as if it were written in TeX, where it represents a non-breaking space.
A PDF document named document.pdf should be produced and contain the following text, where the middot (·) denotes a non-breaking space:
Bartel·Leendert van·der·Waerden
ConTeXt Example
Using a text editor, create a text document named document.tex with the following content. We will make the tilde behave as if it were written in TeX, where it represents a non-breaking space.
A PDF document named document.pdf should be produced and contain the following text, where the middot (·) denotes a non-breaking space:
Bartel·Leendert van·der·Waerden
2.3.1.6 Code Span Renderer
The \markdownRendererCodeSpan macro represents inlined code span in the input text. It receives a single argument that corresponds to the inlined code span.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
$\sqrt{-1}$ *equals* $i$.
$\sqrt{-1}$ equals $i$.
√-̅1̅ equalsi.
2.3.1.7 Link Renderer
The \markdownRendererLink macro represents a hyperlink. It receives four arguments: the label, the fully escaped uri that can be directly typeset, the raw uri that can be used outside typesetting, and the title of the link.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
Please visit the link https://ctan.org/ titled the Comprehensive TeX Archive Network.
2.3.1.8 Image Renderer
The \markdownRendererImage macro represents an image. It receives four arguments: the label, the fully escaped uri that can be directly typeset, the raw uri that can be used outside typesetting, and the title of the link.
LaTeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following content. This assumes that you use a Unix-like operating system with Bourne or Bourne again shell as the default shell of the current user. It also assumes that the md5sum, wget, and convert binaries are installed and that the TeX engine has shell access.
2.3.1.9 Content Block Renderers
The \markdownRendererContentBlock macro represents an iA Writer content block. It receives four arguments: the local file or online image filename extension cast to the lower case, the fully escaped uri that can be directly typeset, the raw uri that can be used outside typesetting, and the title of the content block.
The \markdownRendererContentBlockOnlineImage macro represents an iA Writer online image content block. The macro receives the same arguments as \markdownRendererContentBlock.
The \markdownRendererContentBlockCode macro represents an iA Writer content block that was recognized as a file in a known programming language by its filename extension s. If any markdown-languages.json file found by kpathsea contains a record (k, v), then a non-online-image content block with the filename extension s, s:lower() = k is considered to be in a known programming language v. The macro receives five arguments: the local file name extension s cast to the lower case, the language v, the fully escaped uri that can be directly typeset, the raw uri that can be used outside typesetting, and the title of the content block.
Note that you will need to place place a markdown-languages.json file inside your working directory or inside your local TeX directory structure. In this file, you will define a mapping between filename extensions and the language names recognized by your favorite syntax highlighter; there may exist other creative uses beside syntax highlighting. The Languages.json file provided by Anton Sotkov is a good starting point.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is document.tex, the document that we are currently typesetting.
This is the JavaScript Object Notation (JSON) document markdown-languages.json, the mapping between filename extensions and programming language names.
This is the image https://tug.org/tugboat/noword.jpg, the logotype of TUGboat.
LaTeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is document.tex, the document that we are currently typesetting.
This is the JavaScript Object Notation (JSON) document markdown-languages.json, the mapping between filename extensions and programming language names.
This is the image https://tug.org/tugboat/noword.jpg, the logotype of TUGboat.
ConTeXt Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is document.tex, the document that we are currently typesetting.
This is the JavaScript Object Notation (JSON) document markdown-languages.json, the mapping between filename extensions and programming language names.
This is the image https://tug.org/tugboat/noword.jpg, the logotype of TUGboat.
2.3.1.10 Bullet List Renderers
The \markdownRendererUlBegin macro represents the beginning of a bulleted list that contains an item with several paragraphs of text (the list is not tight). The macro receives no arguments.
The \markdownRendererUlBeginTight macro represents the beginning of a bulleted list that contains no item with several paragraphs of text (the list is tight). This macro will only be produced, when the tightLists option is false. The macro receives no arguments.
The \markdownRendererUlItem macro represents an item in a bulleted list. The macro receives no arguments.
The \markdownRendererUlItemEnd macro represents the end of an item in a bulleted list. The macro receives no arguments.
The \markdownRendererUlEnd macro represents the end of a bulleted list that contains an item with several paragraphs of text (the list is not tight). The macro receives no arguments.
The \markdownRendererUlEndTight macro represents the end of a bulleted list that contains no item with several paragraphs of text (the list is tight). This macro will only be produced, when the tightLists option is false. The macro receives no arguments.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is a tight list (the first item, the second item, and the third item).
This is a loose list:
This is the first item.
This is the second item.
This is the third item.
2.3.1.11 Ordered List Renderers
The \markdownRendererOlBegin macro represents the beginning of an ordered list that contains an item with several paragraphs of text (the list is not tight). The macro receives no arguments.
The \markdownRendererOlBeginTight macro represents the beginning of an ordered list that contains no item with several paragraphs of text (the list is tight). This macro will only be produced, when the tightLists option is false. The macro receives no arguments.
The \markdownRendererOlItem macro represents an item in an ordered list. This macro will only be produced, when the startNumber option is false. The macro receives no arguments.
The \markdownRendererOlItemEnd macro represents the end of an item in an ordered list. The macro receives no arguments.
The \markdownRendererOlItemWithNumber macro represents an item in an ordered list. This macro will only be produced, when the startNumber option is enabled. The macro receives a single numeric argument that corresponds to the item number.
The \markdownRendererOlEnd macro represents the end of an ordered list that contains an item with several paragraphs of text (the list is not tight). The macro receives no arguments.
The \markdownRendererOlEndTight macro represents the end of an ordered list that contains no item with several paragraphs of text (the list is tight). This macro will only be produced, when the tightLists option is false. The macro receives no arguments.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is a tight list (the first item, the second item, and the third item).
This is a loose list:
This is the first item.
This is the second item.
This is the third item.
2.3.1.12 Definition List Renderers
The following macros are only produced, when the definitionLists option is enabled.
The \markdownRendererDlBegin macro represents the beginning of a definition list that contains an item with several paragraphs of text (the list is not tight). The macro receives no arguments.
The \markdownRendererDlBeginTight macro represents the beginning of a definition list that contains an item with several paragraphs of text (the list is not tight). This macro will only be produced, when the tightLists option is false. The macro receives no arguments.
The \markdownRendererDlItem macro represents a term in a definition list. The macro receives a single argument that corresponds to the term being defined.
The \markdownRendererDlItemEnd macro represents the end of a list of definitions for a single term.
The \markdownRendererDlDefinitionBegin macro represents the beginning of a definition in a definition list. There can be several definitions for a single term.
The \markdownRendererDlDefinitionEnd macro represents the end of a definition in a definition list. There can be several definitions for a single term.
The \markdownRendererDlEnd macro represents the end of a definition list that contains an item with several paragraphs of text (the list is not tight). The macro receives no arguments.
The \markdownRendererDlEndTight macro represents the end of a definition list that contains no item with several paragraphs of text (the list is tight). This macro will only be produced, when the tightLists option is false. The macro receives no arguments.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is a tight definition list:
Coffee
black hot drink,
prepared from roasted coffee beans, and
one of the most traded agricultural commodities in the world.
Milk
white cold drink,
nutrient-rich, and
produced on an industrial scale.
This is a loose definition list. Coffee is a black hot drink, prepared from roasted coffee beans, and one of the most traded agricultural commodities in the world. Milk is a white cold drink, nutrient-rich, and produced on an industrial scale.
LaTeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is a tight definition list:
Coffee
black hot drink,
prepared from roasted coffee beans, and
one of the most traded agricultural commodities in the world.
Milk
white cold drink,
nutrient-rich, and
produced on an industrial scale.
This is a loose definition list. Coffee is a black hot drink, prepared from roasted coffee beans, and one of the most traded agricultural commodities in the world. Milk is a white cold drink, nutrient-rich, and produced on an industrial scale.
ConTeXt Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is a tight definition list:
Coffee
black hot drink,
prepared from roasted coffee beans, and
one of the most traded agricultural commodities in the world.
Milk
white cold drink,
nutrient-rich, and
produced on an industrial scale.
This is a loose definition list. Coffee is a black hot drink, prepared from roasted coffee beans, and one of the most traded agricultural commodities in the world. Milk is a white cold drink, nutrient-rich, and produced on an industrial scale.
2.3.1.13 Emphasis Renderers
The \markdownRendererEmphasis macro represents an emphasized span of text. The macro receives a single argument that corresponds to the emphasized span of text.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is emphasis.
This is strong emphasis.
The \markdownRendererStrongEmphasis macro represents a strongly emphasized span of text. The macro receives a single argument that corresponds to the emphasized span of text.
2.3.1.14 Block Quote Renderers
The \markdownRendererBlockQuoteBegin macro represents the beginning of a block quote. The macro receives no arguments.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
A quote from William Shakespeare’s King Lear:
This is the excellent foppery of the world that when we are sick in fortune—often the surfeit of our own behavior—we make guilty of our disasters the sun, the moon, and the stars […]
LaTeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
A quote from William Shakespeare’s King Lear:
This is the excellent foppery of the world that when we are sick in fortune—often the surfeit of our own behavior—we make guilty of our disasters the sun, the moon, and the stars […]
ConTeXt Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
A quote from William Shakespeare’s King Lear:
This is the excellent foppery of the world that when we are sick in fortune—often the surfeit of our own behavior—we make guilty of our disasters the sun, the moon, and the stars […]
The \markdownRendererBlockQuoteEnd macro represents the end of a block quote. The macro receives no arguments.
2.3.1.15 Code Block Renderers
The \markdownRendererInputVerbatim macro represents a code block. The macro receives a single argument that corresponds to the filename of a file contaning the code block contents.
The \markdownRendererInputFencedCode macro represents a fenced code block. This macro will only be produced, when the fencedCode option is enabled. The macro receives two arguments that correspond to the filename of a file contaning the code block contents and to the code fence infostring.
LaTeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is the first page.
This is the second page.
2.3.1.18 Footnote Renderer
The \markdownRendererFootnote macro represents a footnote. This macro will only be produced, when the footnotes option is enabled. The macro receives a single argument that corresponds to the footnote text.
Plain TeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is some text (and this is a footnote) and this is some other text (and this is some other footnote).
2.3.1.19 Parenthesized Citations Renderer
The \markdownRendererCite macro represents a string of one or more parenthetical citations. This macro will only be produced, when the citations option is enabled. The macro receives the parameter {⟨number of citations⟩} followed by ⟨suppress author⟩ {⟨prenote⟩}{⟨postnote⟩}{⟨name⟩} repeated ⟨number of citations⟩ times. The ⟨suppress author⟩ parameter is either the token -, when the author’s name is to be suppressed, or + otherwise.
LaTeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is a parenthesized citation abrahams90 with a prefix see and a postfix pp. 12, and a citation eijkhout91 with a postfix pp. 34.
2.3.1.20 Text Citations Renderer
The \markdownRendererTextCite macro represents a string of one or more text citations. This macro will only be produced, when the citations option is enabled. The macro receives parameters in the same format as the \markdownRendererCite macro.
LaTeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is a text citation abrahams90 with a postfix pp. 12, and a citation eijkhout91 with a prefix also.
2.3.1.21 Table Renderer
The \markdownRendererTable macro represents a table. This macro will only be produced, when the pipeTables option is enabled. The macro receives the parameters {⟨caption⟩}{⟨number of rows⟩}{⟨number of columns⟩} followed by {⟨alignments⟩} and then by {⟨row⟩} repeated ⟨number of rows⟩ times, where ⟨row⟩ is {⟨column⟩} repeated ⟨number of columns⟩ times, ⟨alignments⟩ is ⟨alignment⟩ repeated ⟨number of columns⟩ times, and ⟨alignment⟩ is one of the following:
d – The corresponding column has an unspecified (default) alignment.
l – The corresponding column is left-aligned.
c – The corresponding column is centered.
r – The corresponding column is right-aligned.
LaTeX Example
Using a text editor, create a text document named document.tex with the following content:
A PDF document named document.pdf should be produced and contain the following text:
This is a table with caption Demonstration of pipe table syntax that is 4 colums wide and 4 rows long. As for the alignment, column number 1 is right-aligned, column number 2 is left-aligned, column number 3 has default alignment, and column number 4 is centered. In row 1, column number 1 says Right, column number 2 says Left, column number 3 says Default, and column number 4 says Center. In row 2, column number 1 says 12, column number 2 says 12, column number 3 says 12, and column number 4 says 12. In row 3, column number 1 says 123, column number 2 says 123, column number 3 says 123, and column number 4 says 123. In row 4, column number 1 says 1, column number 2 says 1, column number 3 says 1, and column number 4 says 1.
2.3.1.22 Inline HTML Comment Renderer
The \markdownRendererInlineHtmlComment macro represents the contents of an inline HTML comment. This macro will only be produced, when the html option is enabled. The macro receives a single argument that corresponds to the contents of the HTML comment.
LaTeX Example
Using a text editor, create a text document named document.tex with the following content: