From d559ccaca60acb46c6a12c256ea2a1dcc867d0f8 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 5 Apr 2019 21:09:01 +0000 Subject: markdown (5apr19) git-svn-id: svn://tug.org/texlive/trunk@50784 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/doc/generic/markdown/markdown.css | 25 + .../texmf-dist/doc/generic/markdown/markdown.html | 5670 ++++++++++++++------ Master/texmf-dist/doc/generic/markdown/markdown.md | 3324 +----------- .../texmf-dist/doc/generic/markdown/markdown.pdf | Bin 398905 -> 412653 bytes 4 files changed, 4048 insertions(+), 4971 deletions(-) (limited to 'Master/texmf-dist/doc/generic') diff --git a/Master/texmf-dist/doc/generic/markdown/markdown.css b/Master/texmf-dist/doc/generic/markdown/markdown.css index 2e2f4fb6c44..5abe7013b44 100644 --- a/Master/texmf-dist/doc/generic/markdown/markdown.css +++ b/Master/texmf-dist/doc/generic/markdown/markdown.css @@ -323,3 +323,28 @@ table td { } } +.tex sub, .latex sub, .latex sup { + text-transform: uppercase; +} + +.tex sub, .latex sub { + vertical-align: -0.1ex; + margin-left: -0.1667em; + margin-right: -0.125em; +} + +.tex, .latex, .tex sub, .latex sub { + font-size: 1em; +} + +.latex sup { + font-size: 0.85em; + vertical-align: -0.35em; + margin-left: -0.36em; + margin-right: -0.15em; +} + +abbr { + font-variant: small-caps; +} + diff --git a/Master/texmf-dist/doc/generic/markdown/markdown.html b/Master/texmf-dist/doc/generic/markdown/markdown.html index 523805f0347..203c1be5121 100644 --- a/Master/texmf-dist/doc/generic/markdown/markdown.html +++ b/Master/texmf-dist/doc/generic/markdown/markdown.html @@ -1,150 +1,149 @@ - - + + - - + + Markdown Package User Manual - - + + + - -
+

Vít Novotný

+

v2.7.0 (2019/04/04)

+ +
+

1 Introduction

-

The Markdown package converts markdown markup to TeX commands. The functionality is provided both as a Lua module, and as plain TeX, LaTeX, and ConTeXt macro packages that can be used to directly typeset TeX documents containing markdown markup. Unlike other convertors, the Markdown package makes it easy to redefine how each and every markdown element is rendered. Creative abuse of the markdown syntax is encouraged.

-

This document is a user manual for the Markdown package. It provides beginner tutorials and code examples. For an in-depth description of the package requirements, interfaces, and implementation, please refer to the technical documentation.

+

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

+

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.

+

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

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

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

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

-
cd markdown
-luatex markdown.ins
+
git clone https://github.com/witiko/markdown
+

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

+
cd markdown
+luatex markdown.ins

This should produce the following files:

-

1.2.1 Local installation

-

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

+

1.2.1 Local Installation

+

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

-

where <TEXMF> corresponds to a root of your TeX distribution, such as /usr/share/texmf and ~/texmf on UN*X systems or C:\Users\<YOUR␣USERNAME>\texmf on Windows systems. When in doubt, consult the manual of your TeX distribution.

-

1.2.2 Portable installation

-

Alternatively, you can also store the above files in the same folder as your TeX document and distribute them together. This way your document can be portably typeset on legacy TeX distributions.

-

1.3 First document

-

In this section, we will take the necessary steps to typeset our first markdown document in TeX. This will serve as our first hands-on experience with the package and also as a reassurance that the package has been correctly installed.

+

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

+

1.2.2 Portable Installation

+

Alternatively, you can also store the above files in the same folder as your TeX document and distribute them together. This way your document can be portably typeset on legacy TeX distributions.

+

1.3 First Document

+

In this section, we will take the necessary steps to typeset our first markdown document in TeX. This will serve as our first hands-on experience with the package and also as a reassurance that the package has been correctly installed.

1.3.1 Using Lua

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

-
\input markdown
-\input hello
-\bye
-

1.3.1.1 Using the Lua module

+
\input markdown
+\input hello
+\bye
+

1.3.1.1 Using the Lua Module

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

-
#!/usr/bin/env texlua
-local kpse = require("kpse")
-kpse.set_program_name("luatex")
-local markdown = require("markdown")
-local convert = markdown.new()
-print(convert("Hello *world*!"))
-

Next, invoke LuaTeX from the terminal:

-
texlua hello.lua > hello.tex
-luatex document.tex
+
#!/usr/bin/env texlua
+local kpse = require("kpse")
+kpse.set_program_name("luatex")
+local markdown = require("markdown")
+local convert = markdown.new()
+print(convert("Hello *world*!"))
+

Next, invoke LuaTeX from the terminal:

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

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

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

1.3.1.2 Using the Lua CLI

+
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*!
+
Hello *world*!

Next, invoke LuaTeX from the terminal:

-
texlua <CLI␣PATHNAME> -- hello.md hello.tex
-luatex document.tex
-

where <CLI␣PATHNAME> corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich markdown-cli.lua to locate the Lua CLI script file using Kpathsea.

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

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

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

-
texlua <CLI␣PATHNAME> -- hello.md hello.tex
-pdftex document.tex
-

1.3.2 Using plain TeX

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

1.3.2 Using Plain TeX

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

-
\input markdown
-\markdownBegin
-Hello *world*!
-\markdownEnd
-\bye
+
\input markdown
+\markdownBegin
+Hello *world*!
+\markdownEnd
+\bye

Next, invoke LuaTeX from the terminal:

-
luatex document.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:

-
pdftex --shell-escape document.tex
-

1.3.3 Using LaTeX

-

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

-
\documentclass{article}
-\usepackage{markdown}
-\begin{document}
-\begin{markdown}
-Hello *world*!
-\end{markdown}
-\end{document}
-

Next, invoke LuaTeX from the terminal:

-
lualatex document.tex
+
pdftex --shell-escape document.tex
+

1.3.3 Using LaTeX

+

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

+
\documentclass{article}
+\usepackage{markdown}
+\begin{document}
+\begin{markdown}
+Hello *world*!
+\end{markdown}
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
lualatex document.tex

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

-
pdflatex --shell-escape document.tex
+
pdflatex --shell-escape document.tex

As the next step, try typesetting the example documents distributed along with the Markdown package:

-
git clone https://github.com/witiko/markdown
-cd markdown/examples
-lualatex latex.tex
+
git clone https://github.com/witiko/markdown
+cd markdown/examples
+lualatex latex.tex

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

-
lualatex latex.tex
+
lualatex latex.tex

to see the effect of your changes.

-

1.3.4 Using ConTeXt

+

1.3.4 Using ConTeXt

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

-
\usemodule[t][markdown]
-\starttext
-\startmarkdown
-Hello *world*!
-\stopmarkdown
-\stoptext
+
\usemodule[t][markdown]
+\starttext
+\startmarkdown
+Hello *world*!
+\stopmarkdown
+\stoptext

Next, invoke LuaTeX from the terminal:

-
context document.tex
+
context document.tex

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

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

As the next step, try typesetting the example documents distributed along with the Markdown package:

-
git clone https://github.com/witiko/markdown
-cd markdown/examples
-context context.tex
+
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
+
context context.tex

to see the effect of your changes.

2 Examples

-

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

-

2.1 Lua

-

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

-

2.1.1 Interfaces

-

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

-

2.1.1.1 The Lua module

-

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

-

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

-
\input markdown
-\input lmfonts
-\input example
-\bye
+

In this section, I will describe the individual parts of the Markdown package. Each part will be shown by example, leaving the implementation details to the technical documentation.

+

2.1 Interfaces

+

In this section, I will describe the individual interfaces exposed by the Markdown package starting with the low-level Lua interfaces and all the way up to the LaTeX and ConTeXt interfaces intended for the ordinary user.

+

2.1.1 Lua

+

The Lua programming language is what drives the conversion from markdown to TeX in the Markdown package. Based on the Lunamark Lua library by John MacFarlane, the Lua implementation is largely independent on TeX, and can be used separately from typesetting a document. Lua provides two interfaces: a Lua module and a command-line interface (CLI).

+

2.1.1.1 Lua Module

+

A Lua module is a software library that can be used from in other programs. The markdown Lua module makes it possible to convert markdown to TeX from within LuaTeX documents and Lua scripts.

+

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

+

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

+
\input markdown
+\input lmfonts
+\input example
+\bye

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

-
#!/usr/bin/env texlua
-local kpse = require("kpse")
-kpse.set_program_name("luatex")
-local markdown = require("markdown")
-local convert_safe = markdown.new()
-local convert_unsafe = markdown.new({hybrid = true})
-local input = [[$\sqrt{-1}$ *equals* $i$.]]
-print(convert_safe(input) .. " " .. convert_unsafe(input))
-

Next, invoke LuaTeX from the terminal:

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

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

-
texlua example.lua > example.tex
-pdftex document.tex
+
#!/usr/bin/env texlua
+local kpse = require("kpse")
+kpse.set_program_name("luatex")
+local markdown = require("markdown")
+local input, convert_safe, convert_unsafe, paragraph
+
+input = [[$\sqrt{-1}$ *equals* $i$.]]
+convert_safe = markdown.new()
+convert_unsafe = markdown.new({hybrid = true})
+paragraph = [[\par]]
+
+print(
+  convert_safe(input) .. paragraph ..
+  convert_unsafe(input)
+)
+

Next, invoke LuaTeX from the terminal:

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

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

+
+

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

+

√-̅1̅ equals i.

+
+

Invoking pdfTeX should have the same effect:

+
texlua example.lua > example.tex
+pdftex document.tex

Rather than use the texlua interpreter, we can also access the markdown Lua module directly from our document. Using a text editor, create a text document named document.tex with the following content:

-
\input markdown
-\input lmfonts
-\directlua{
-  local markdown = require("markdown")
-  local convert_safe = markdown.new()
-  local convert_unsafe = markdown.new({hybrid = true})
-  local input = [[$\noexpand\sqrt{-1}$ *equals* $i$.]]
-  tex.sprint(convert_safe(input) .. " " .. convert_unsafe(input)) }
-\bye
-

Next, invoke LuaTeX from the terminal:

-
luatex document.tex
-

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

-

2.1.1.2 The Lua CLI

-

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

-

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

-
\input markdown
-\input lmfonts
-\input safe\ \input unsafe
-\bye
+
\input markdown
+\input lmfonts
+\directlua{
+  local markdown = require("markdown")
+  local input, convert_safe, convert_unsafe, paragraph
+
+  input = [[$\string\sqrt{-1}$ *equals* $i$.]]
+  convert_safe = markdown.new()
+  convert_unsafe = markdown.new({hybrid = true})
+  paragraph = [[\par]]
+
+  tex.sprint(
+    convert_safe(input) .. paragraph ..
+    convert_unsafe(input)
+  )
+}
+\bye
+

Next, invoke LuaTeX from the terminal:

+
luatex document.tex
+

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

+
+

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

+

√-̅1̅ equals i.

+
+

In this case, we cannot use pdfTeX, because pdfTeX does not define the \directlua TeX command.

+

2.1.1.2 Lua Command-Line Interface

+

The Lua command-line interface (CLI) of the Markdown package makes the functionality of the Lua module accessible from the command line. This makes it possible to convert documents from markdown to TeX manually without any knowledge of the Lua programming language.

+

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

+

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

+
\input markdown
+\input lmfonts
+\input safe
+
+\input unsafe
+\bye

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

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

Next, invoke LuaTeX from the terminal:

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

where <CLI␣PATHNAME> corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich markdown-cli.lua to locate the Lua CLI script file using Kpathsea.

-

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

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

2.1.2 Options

-

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

-

2.1.2.1 File and Directory Names

-
2.1.2.1.1 Option cacheDir
+
$\sqrt{-1}$ *equals* $i$.
+

Next, invoke LuaTeX from the terminal:

+
texlua ⟨CLI pathname⟩ -- example.md safe.tex
+texlua ⟨CLI pathname⟩ hybrid=true -- example.md unsafe.tex
+luatex document.tex
+

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

+

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

+
+

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

+

√-̅1̅ equals i.

+
+

Invoking pdfTeX should have the same effect:

+
texlua ⟨CLI pathname⟩ -- example.md safe.tex
+texlua ⟨CLI pathname⟩ hybrid=true -- example.md unsafe.tex
+pdftex document.tex
+

2.1.2 Plain TeX

+

The plain TeX interface provides TeX commands that typeset markdown documents by using the Lua interface behind the scenes. Unlike the Lua interface, the plain TeX interface does not provide low-level tools for converting markdown to TeX. Instead, its goal is to provide high-level typesetting capabilities.

+

The plain TeX interface accepts the same options as the markdown Lua module, in addition to its own options, but now the options are specified as TeX commands.

+

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

+
\input markdown
+\input lmfonts
+
+\markdownBegin
+$\sqrt{-1}$ *equals* $i$.
+\markdownEnd
+
+\def\markdownOptionHybrid{true}
+\markdownBegin
+$\sqrt{-1}$ *equals* $i$.
+\markdownEnd
+
+\bye
+

Next, invoke LuaTeX from the terminal:

+
luatex document.tex
+

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

+
+

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

+

√-̅1̅ equals i.

+
+

Invoking pdfTeX should have the same effect:

+
pdftex --shell-escape document.tex
+

2.1.3 LaTeX

+

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

+

The LaTeX interface accepts the same options as the plain TeX interface, but now the options are specified as ⟨key = value⟩ pairs and they are passed either as package options, in the \markdownSetup command, or as parameters for the markdown* LaTeX environment.

+

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

+
\documentclass{article}
+\usepackage{markdown}
+\begin{document}
+
+\begin{markdown}
+$\sqrt{-1}$ *equals* $i$
+\end{markdown}
+
+\begin{markdown*}{hybrid}
+$\sqrt{-1}$ *equals* $i$
+\end{markdown*}
+
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
lualatex document.tex
+

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

+
+

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

+

√-̅1̅ equals i.

+
+

Invoking pdfTeX should have the same effect:

+
pdflatex --shell-escape document.tex
+

2.1.4 ConTeXt

+

The ConTeXt interface provides the same level of functionality as the plain TeX interface by using the plain TeX interface behind the scenes. Unlike the plain TeX interface, the ConTeXt interface uses familiar ConTeXt idioms, 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:

+
\usemodule[t][markdown]
+\starttext
+
+\startmarkdown
+$\sqrt{-1}$ *equals* $i$.
+\stopmarkdown
+
+\def\markdownOptionHybrid{true}
+\startmarkdown
+$\sqrt{-1}$ *equals* $i$.
+\stopmarkdown
+
+\stoptext
+

Next, invoke LuaTeX from the terminal:

+
context document.tex
+

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

+
+

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

+

√-̅1̅ equals i.

+
+

Invoking pdfTeX should have the same effect:

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

2.2 Options

+

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

+

2.2.1 Lua

+

Lua options control the conversion from markdown to TeX. They are supported by all interfaces of the Markdown package starting with the low-level Lua interfaces and all the way up to the LaTeX and ConTeXt interfaces.

+

2.2.1.1 Option cacheDir

cacheDir (default value: ".")
-

A path to the directory containing auxiliary cache files. If the last segment of the path does not exist, it will be created by the Lua command-line and plain TeX implementations. The Lua implementation expects that the entire path already exists.

+

A path to the directory containing auxiliary cache files. If the last segment of the path does not exist, it will be created by the Lua command-line and plain TeX implementations. The Lua implementation expects that the entire path already exists.

When iteratively writing and typesetting a markdown document, the cache files are going to accumulate over time. You are advised to clean the cache directory every now and then, or to set it to a temporary filesystem (such as /tmp on UN*X systems), which gets periodically emptied.

-
Lua module example
-

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

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

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

-
\input markdown
-\input hello
-\bye
+
\input markdown
+\input hello
+\bye

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

-
Hello *world*!
+
Hello *world*!

Next, invoke LuaTeX from the terminal:

-
texlua <CLI␣PATHNAME> cacheDir=cache -- hello.md hello.tex
-luatex document.tex
-

where <CLI␣PATHNAME> corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich markdown-cli.lua to locate the Lua CLI script file using Kpathsea.

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

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

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

-
Plain TeX example
+
Plain TeX Example

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

-
\input markdown
-\def\markdownOptionCacheDir{cache}
-\markdownBegin
-Hello *world*!
-\markdownEnd
-\bye
+
\input markdown
+\def\markdownOptionCacheDir{cache}
+\markdownBegin
+Hello *world*!
+\markdownEnd
+\bye

Next, invoke LuaTeX from the terminal:

-
luatex document.tex
+
luatex document.tex

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

-
LaTeX example
+
LaTeX Example

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

-
\documentclass{article}
-\usepackage[cacheDir=cache]{markdown}
-\begin{document}
-\begin{markdown}
-Hello *world*!
-\end{markdown}
-\end{document}
+
\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
+
lualatex document.tex

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

-
ConTeXt example
+
ConTeXt Example

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

-
\usemodule[t][markdown]
-\def\markdownOptionCacheDir{cache}
-\starttext
-\startmarkdown
-Hello *world*!
-\stopmarkdown
-\stoptext
+
\usemodule[t][markdown]
+\def\markdownOptionCacheDir{cache}
+\starttext
+\startmarkdown
+Hello *world*!
+\stopmarkdown
+\stoptext

Next, invoke LuaTeX from the terminal:

-
context document.tex
+
context document.tex

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

-

2.1.2.2 Parser Options

-
2.1.2.2.1 Option blankBeforeBlockquote
+

2.2.1.2 Option blankBeforeBlockquote

blankBeforeBlockquote (default value: false)
@@ -381,27 +492,27 @@ Hello *world*!
-
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
+
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
+
luatex document.tex

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

A paragraph.

@@ -410,21 +521,21 @@ Hello *world*!

A paragraph > Not a quote.

-
Lua CLI example
+
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
+
\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?
+
A paragraph.
+> A quote?

Next, invoke LuaTeX from the terminal:

-
texlua <CLI␣PATHNAME> -- content.md optionfalse.tex
-texlua <CLI␣PATHNAME> blankBeforeBlockquote=true -- content.md optiontrue.tex
-luatex document.tex
-

where <CLI␣PATHNAME> corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich markdown-cli.lua to locate the Lua CLI script file using Kpathsea.

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

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

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

A paragraph.

@@ -433,24 +544,24 @@ Hello *world*!

A paragraph. > A quote?

-
Plain TeX example
+
Plain TeX Example

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

-
\input markdown
-
-\markdownBegin
-A paragraph.
-> A quote.
-\markdownEnd
-
-\def\markdownOptionBlankBeforeBlockquote{true}
-\markdownBegin
-A paragraph.
-> Not a quote.
-\markdownEnd
-
-\bye
+
\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
+
luatex document.tex

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

A paragraph.

@@ -459,25 +570,25 @@ A paragraph.

A paragraph > Not a quote.

-
LaTeX example
+
LaTeX Example

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

-
\documentclass{article}
-\usepackage{markdown}
-\begin{document}
-
-\begin{markdown}
-A paragraph.
-> A quote.
-\end{markdown}
-
-\begin{markdown*}{blankBeforeBlockquote}
-A paragraph.
-> Not a quote.
-\end{markdown*}
-
-\end{document}
+
\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
+
lualatex document.tex

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

A paragraph.

@@ -486,25 +597,25 @@ A paragraph.

A paragraph > Not a quote.

-
ConTeXt example
+
ConTeXt Example

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

-
\usemodule[t][markdown]
-\starttext
-
-\startmarkdown
-A paragraph.
-> A quote.
-\stopmarkdown
-
-\def\markdownOptionBlankBeforeBlockquote{true}
-\startmarkdown
-A paragraph.
-> Not a quote.
-\stopmarkdown
-
-\stoptext
+
\usemodule[t][markdown]
+\starttext
+
+\startmarkdown
+A paragraph.
+> A quote.
+\stopmarkdown
+
+\def\markdownOptionBlankBeforeBlockquote{true}
+\startmarkdown
+A paragraph.
+> Not a quote.
+\stopmarkdown
+
+\stoptext

Next, invoke LuaTeX from the terminal:

-
context document.tex
+
context document.tex

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

A paragraph.

@@ -513,7 +624,7 @@ A paragraph.

A paragraph > Not a quote.

-
2.1.2.2.2 Option blankBeforeCodeFence
+

2.2.1.3 Option blankBeforeCodeFence

blankBeforeCodeFence (default value: false)
@@ -526,150 +637,150 @@ A paragraph.
-
Lua module example
-

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

-
\input markdown
-\input lmfonts
-\directlua{
-  local markdown = require("markdown")
-  local newline = [[^^J^^J]]
-  local convert, input
-
-  convert = markdown.new({fencedCode = true})
-  input = "A paragraph."   .. newline ..
-          "```"            .. newline ..
-          "A code fence."  .. newline ..
-          "```"            .. newline
-  tex.sprint(convert(input))
-
-  convert = markdown.new({
-    fencedCode = true, blankBeforeCodeFence = true})
-  input = "A paragraph."       .. newline ..
-          "```"                .. newline ..
-          "Not a code fence."  .. newline ..
-          "```"                .. newline
-  tex.sprint(convert(input)) }
-\bye
+
Lua Module Example
+

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

+
\input markdown
+\input lmfonts
+\directlua{
+  local markdown = require("markdown")
+  local newline = [[^^J^^J]]
+  local convert, input
+
+  convert = markdown.new({fencedCode = true})
+  input = "A paragraph."   .. newline ..
+          "```"            .. newline ..
+          "A code fence."  .. newline ..
+          "```"            .. newline
+  tex.sprint(convert(input))
+
+  convert = markdown.new({
+    fencedCode = true, blankBeforeCodeFence = true})
+  input = "A paragraph."       .. newline ..
+          "```"                .. newline ..
+          "Not a code fence."  .. newline ..
+          "```"                .. newline
+  tex.sprint(convert(input)) }
+\bye

Then, invoke LuaTeX from the terminal:

-
luatex document.tex
+
luatex document.tex

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

A paragraph.

A code fence.

A paragraph. Not a code fence.

-
Lua CLI example
+
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
+
\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?
-```
+
A paragraph.
+```
+A code fence?
+```

Next, invoke LuaTeX from the terminal:

-
texlua <CLI␣PATHNAME> fencedCode=true -- content.md optionfalse.tex
-texlua <CLI␣PATHNAME> fencedCode=true blankBeforeCodeFence=true  -- content.md optiontrue.tex
-luatex document.tex
-

where <CLI␣PATHNAME> corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich markdown-cli.lua to locate the Lua CLI script file using Kpathsea.

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

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

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

A paragraph.

A code fence?

A paragraph. A code fence?

-
Plain TeX example
-

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

-
\input markdown
-\def\markdownOptionFencedCode{true}
-
-\markdownBegin
-A paragraph.
-```
-A code fence.
-```
-\markdownEnd
-
-\def\markdownOptionBlankBeforeCodeFence{true}
-\markdownBegin
-A paragraph.
-```
-Not a code fence.
-```
-\markdownEnd
-
-\bye
-

Next, invoke LuaTeX from the terminal:

-
luatex document.tex
+
Plain TeX Example
+

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

+
\input markdown
+\def\markdownOptionFencedCode{true}
+
+\markdownBegin
+A paragraph.
+```
+A code fence.
+```
+\markdownEnd
+
+\def\markdownOptionBlankBeforeCodeFence{true}
+\markdownBegin
+A paragraph.
+```
+Not a code fence.
+```
+\markdownEnd
+
+\bye
+

Next, invoke LuaTeX from the terminal:

+
luatex document.tex

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

A paragraph.

A code fence.

A paragraph. Not a code fence.

-
LaTeX example
-

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

-
\documentclass{article}
-\usepackage[fencedCode]{markdown}
-\begin{document}
-
-\begin{markdown}
-A paragraph.
-```
-A code fence.
-```
-\end{markdown}
-
-\begin{markdown*}{blankBeforeCodeFence}
-A paragraph.
-```
-Not a code fence.
-```
-\end{markdown*}
-
-\end{document}
-

Next, invoke LuaTeX from the terminal:

-
lualatex document.tex
+
LaTeX Example
+

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

+
\documentclass{article}
+\usepackage[fencedCode]{markdown}
+\begin{document}
+
+\begin{markdown}
+A paragraph.
+```
+A code fence.
+```
+\end{markdown}
+
+\begin{markdown*}{blankBeforeCodeFence}
+A paragraph.
+```
+Not a code fence.
+```
+\end{markdown*}
+
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
lualatex document.tex

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

A paragraph.

A code fence.

A paragraph. Not a code fence.

-
ConTeXt example
-

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

-
\usemodule[t][markdown]
-\def\markdownOptionFencedCode{true}
-\starttext
-
-\startmarkdown
-A paragraph.
-```
-A code fence.
-```
-\stopmarkdown
-
-\def\markdownOptionBlankBeforeCodeFence{true}
-\startmarkdown
-A paragraph.
-```
-Not a code fence.
-```
-\stopmarkdown
-
-\stoptext
-

Next, invoke LuaTeX from the terminal:

-
context document.tex
+
ConTeXt Example
+

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

+
\usemodule[t][markdown]
+\def\markdownOptionFencedCode{true}
+\starttext
+
+\startmarkdown
+A paragraph.
+```
+A code fence.
+```
+\stopmarkdown
+
+\def\markdownOptionBlankBeforeCodeFence{true}
+\startmarkdown
+A paragraph.
+```
+Not a code fence.
+```
+\stopmarkdown
+
+\stoptext
+

Next, invoke LuaTeX from the terminal:

+
context document.tex

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

A paragraph.

A code fence.

A paragraph. Not a code fence.

-
2.1.2.2.3 Option blankBeforeHeading
+

2.2.1.4 Option blankBeforeHeading

blankBeforeHeading (default value: false)
@@ -682,139 +793,139 @@ Not a code fence.
-
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
+
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
+
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
+
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
+
\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?
-==========
+
A paragraph.
+A heading?
+==========

Next, invoke LuaTeX from the terminal:

-
texlua <CLI␣PATHNAME> -- content.md optionfalse.tex
-texlua <CLI␣PATHNAME> blankBeforeHeading=true  -- content.md optiontrue.tex
-luatex document.tex
-

where <CLI␣PATHNAME> corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich markdown-cli.lua to locate the Lua CLI script file using Kpathsea.

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

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

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

A paragraph.

A heading?

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

-
Plain TeX example
+
Plain TeX Example

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

-
\input markdown
-
-\markdownBegin
-A paragraph.
-A heading.
-==========
-\markdownEnd
-
-\def\markdownOptionBlankBeforeHeading{true}
-\markdownBegin
-A paragraph.
-Not a heading.
-==============
-\markdownEnd
-
-\bye
+
\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
+
luatex document.tex

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

A paragraph.

A heading.

A paragraph. Not a heading. ==============

-
LaTeX example
-

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

-
\documentclass{article}
-\usepackage{markdown}
-\begin{document}
-
-\begin{markdown}
-A paragraph.
-A heading.
-==========
-\end{markdown}
-
-\begin{markdown*}{blankBeforeHeading}
-A paragraph.
-Not a heading.
-==============
-\end{markdown*}
-
-\end{document}
-

Next, invoke LuaTeX from the terminal:

-
lualatex document.tex
+
LaTeX Example
+

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

+
\documentclass{article}
+\usepackage{markdown}
+\begin{document}
+
+\begin{markdown}
+A paragraph.
+A heading.
+==========
+\end{markdown}
+
+\begin{markdown*}{blankBeforeHeading}
+A paragraph.
+Not a heading.
+==============
+\end{markdown*}
+
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
lualatex document.tex

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

A paragraph.

A heading.

A paragraph. Not a heading. ==============

-
ConTeXt example
-

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

-
\usemodule[t][markdown]
-\starttext
-
-\startmarkdown
-A paragraph.
-A heading.
-==========
-\stopmarkdown
-
-\def\markdownOptionBlankBeforeHeading{true}
-\startmarkdown
-A paragraph.
-Not a heading.
-==============
-\stopmarkdown
-
-\stoptext
-

Next, invoke LuaTeX from the terminal:

-
context document.tex
+
ConTeXt Example
+

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

+
\usemodule[t][markdown]
+\starttext
+
+\startmarkdown
+A paragraph.
+A heading.
+==========
+\stopmarkdown
+
+\def\markdownOptionBlankBeforeHeading{true}
+\startmarkdown
+A paragraph.
+Not a heading.
+==============
+\stopmarkdown
+
+\stoptext
+

Next, invoke LuaTeX from the terminal:

+
context document.tex

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

A paragraph.

A heading.

A paragraph. Not a heading. ==============

-
2.1.2.2.4 Option breakableBlockquotes
+

2.2.1.5 Option breakableBlockquotes

breakableBlockquotes (default value: false)
@@ -827,28 +938,28 @@ Not a heading.
-
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
+
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
+
luatex document.tex

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

@@ -861,22 +972,22 @@ Not a heading.

Another block quote.

-
Lua CLI example
+
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
+
\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?
+
> A single block quote
+
+> or two block quotes?

Next, invoke LuaTeX from the terminal:

-
texlua <CLI␣PATHNAME> -- content.md optionfalse.tex
-texlua <CLI␣PATHNAME> breakableBlockquotes=true  -- content.md optiontrue.tex
-luatex document.tex
-

where <CLI␣PATHNAME> corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich markdown-cli.lua to locate the Lua CLI script file using Kpathsea.

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

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

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

@@ -889,26 +1000,26 @@ Not a heading.

or two block quotes?

-
Plain TeX example
+
Plain TeX Example

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

-
\input markdown
-
-\markdownBegin
-> A single
-
-> block quote.
-\markdownEnd
-
-\def\markdownOptionBreakableBlockquotes{true}
-\markdownBegin
-> A block quote.
-
-> Another block quote.
-\markdownEnd
-
-\bye
+
\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
+
luatex document.tex

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

@@ -921,27 +1032,27 @@ Not a heading.

Another block quote.

-
LaTeX example
+
LaTeX Example

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

-
\documentclass{article}
-\usepackage{markdown}
-\begin{document}
-
-\begin{markdown}
-> A single
-
-> block quote.
-\end{markdown}
-
-\begin{markdown*}{breakableBlockquotes}
-> A block quote.
-
-> Another block quote.
-\end{markdown*}
-
-\end{document}
+
\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
+
lualatex document.tex

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

@@ -954,27 +1065,27 @@ Not a heading.

Another block quote.

-
ConTeXt example
+
ConTeXt Example

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

-
\usemodule[t][markdown]
-\starttext
-
-\startmarkdown
-> A single
-
-> block quote.
-\stopmarkdown
-
-\def\markdownOptionBreakableBlockquotes{true}
-\startmarkdown
-> A block quote.
-
-> Another block quote.
-\stopmarkdown
-
-\stoptext
+
\usemodule[t][markdown]
+\starttext
+
+\startmarkdown
+> A single
+
+> block quote.
+\stopmarkdown
+
+\def\markdownOptionBreakableBlockquotes{true}
+\startmarkdown
+> A block quote.
+
+> Another block quote.
+\stopmarkdown
+
+\stoptext

Next, invoke LuaTeX from the terminal:

-
context document.tex
+
context document.tex

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

@@ -987,7 +1098,7 @@ Not a heading.

Another block quote.

-
2.1.2.2.5 Option citationNbsps
+

2.2.1.6 Option citationNbsps

citationNbsps (default value: true)
@@ -1000,60 +1111,61 @@ Not a heading.
-
LaTeX example
+
LaTeX Example

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

-
@book{knuth:tex,
-  author    = "Knuth, Donald Ervin",
-  title     = "The \TeX book, volume A of Computers and typesetting",
-  publisher = "Addison-Wesley",
-  year      = "1984" }
-

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

-
\documentclass{article}
-\usepackage[citations]{markdown}
-\begin{document}
-
-\begin{markdown}
-The TeXbook [@knuth:tex, p. 123 and 130] is good.
-\end{markdown}
-
-\begin{markdown*}{citationNbsps = false}
-The TeXbook [@knuth:tex, p. 123 and 130] is good.
-\end{markdown*}
-
-\bibliographystyle{plain}
-\bibliography{document.bib}
-\end{document}
+
@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
+
lualatex document.tex
+bibtex document.aux
+lualatex document.tex
+lualatex document.tex

A PDF document named document.pdf should be produced and contain the following text, where the middot (·) denotes a non-breakable space:

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

-

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

+

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

References

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

-
2.1.2.2.6 Option citations
+

2.2.1.7 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.
+
@@ -1064,45 +1176,46 @@ suppressed -@doe99.
-
LaTeX example
+
LaTeX Example

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

-
@book{knuth:tex,
-  author    = "Knuth, Donald Ervin",
-  title     = "The \TeX book, volume A of Computers and typesetting",
-  publisher = "Addison-Wesley",
-  year      = "1984" }
-

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

-
\documentclass{article}
-\usepackage[backend=biber]{biblatex}
-\addbibresource{document.bib}
-\usepackage[citations]{markdown}
-\begin{document}
-
-\begin{markdown}
-The TeXbook [@knuth:tex, p. 123 and 130] was written by @knuth:tex.
-\end{markdown}
-
-\printbibliography
-\end{document}
+
@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
+
lualatex document.tex
+biber document.bcf
+lualatex document.tex
+lualatex document.tex

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

The TeXbook [1, p.·123 and 130] was written by Knuth [1].

References

-

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

+

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

-
2.1.2.2.7 Option codeSpans
+

2.2.1.8 Option codeSpans

codeSpans (default value: true)
true

Enable the code span syntax:

-
Use the `printf()` function.
-``There is a literal backtick (`) here.``
+
@@ -1114,136 +1227,136 @@ The TeXbook [@knuth:tex, p. 123 and 130] was written by @knuth:tex.
-
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
+
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
+
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 code span.''This is no longer a code span.’’

“This is a quote.” “This is another quote.”

-
Lua CLI example
+
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
+
\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?''
+
``Is this a code span?'' ``Or a quote?''

Next, invoke LuaTeX from the terminal:

-
texlua <CLI␣PATHNAME> codeSpans=false -- content.md optionfalse.tex
-texlua <CLI␣PATHNAME> -- content.md optiontrue.tex
-luatex document.tex
-

where <CLI␣PATHNAME> corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich markdown-cli.lua to locate the Lua CLI script file using Kpathsea.

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

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

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

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

-

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

+

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

-
Plain TeX example
+
Plain TeX Example

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

-
\input markdown
-
-\markdownBegin
-``This is a code span.''
-``This is no longer a code span.''
-\markdownEnd
-
-\def\markdownOptionCodeSpans{false}
-\markdownBegin
-``This is a quote.''
-``This is another quote.''
-\markdownEnd
-
-\bye
+
\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
+
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 code span.''This is no longer a code span.’’

“This is a quote.” “This is another quote.”

-
LaTeX example
+
LaTeX Example

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

-
\documentclass{article}
-\usepackage{markdown}
-\begin{document}
-
-\begin{markdown}
-``This is a code span.''
-``This is no longer a code span.''
-\end{markdown}
-
-\begin{markdown*}{codeSpans=false}
-``This is a quote.''
-``This is another quote.''
-\end{markdown*}
-
-\end{document}
+
\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
+
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 code span.''This is no longer a code span.’’

“This is a quote.” “This is another quote.”

-
ConTeXt example
+
ConTeXt Example

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

-
\usemodule[t][markdown]
-\starttext
-
-\startmarkdown
-``This is a code span.''
-``This is no longer a code span.''
-\stopmarkdown
-
-\def\markdownOptionCodeSpans{false}
-\startmarkdown
-``This is a quote.''
-``This is another quote.''
-\stopmarkdown
-
-\stoptext
+
\usemodule[t][markdown]
+\starttext
+
+\startmarkdown
+``This is a code span.''
+``This is no longer a code span.''
+\stopmarkdown
+
+\def\markdownOptionCodeSpans{false}
+\startmarkdown
+``This is a quote.''
+``This is another quote.''
+\stopmarkdown
+
+\stoptext

Next, invoke LuaTeX from the terminal:

-
context document.tex
+
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 code span.''This is no longer a code span.’’

“This is a quote.” “This is another quote.”

-
2.1.2.2.8 Option contentBlocks
+

2.2.1.9 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
+
@@ -1254,33 +1367,33 @@ The TeXbook [@knuth:tex, p. 123 and 130] was written by @knuth:tex.
-
LaTeX example
+
LaTeX Example

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

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

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

-
{
-  "tex": "LaTeX"
-}
+
{
+  "tex": "LaTeX"
+}

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

-
This is an example code listing in \LaTeX.
+
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*.
+
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}
+
\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
+
lualatex --shell-escape document.tex

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

@@ -1310,37 +1423,37 @@ Thomas,Edison,1847

Table 1: An example table

-
This is an example code listing in \LaTeX.
+

This is a transcluded markdown document.

-
ConTeXt example
+
ConTeXt Example

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

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

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

-
{
-  "tex": "ConTeXt"
-}
+
{
+  "tex": "ConTeXt"
+}

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

-
This is an example code listing in \ConTeXt.
+
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*.
+
This is a *transcluded markdown document*.

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

-
\usemodule[t][markdown]
-\def\markdownOptionContentBlocks{true}
-\definetyping [ConTeXt]
-\setuptyping  [ConTeXt] [option=TEX]
-\starttext
-\startmarkdown
-/table.csv  (An example table)
-/code.tex   (An example code listing)
-/part.md    (A file transclusion example)
-\stopmarkdown
-\stoptext
+
\usemodule[t][markdown]
+\def\markdownOptionContentBlocks{true}
+\definetyping [ConTeXt]
+\setuptyping  [ConTeXt] [option=TEX]
+\starttext
+\startmarkdown
+/table.csv  (An example table)
+/code.tex   (An example code listing)
+/part.md    (A file transclusion example)
+\stopmarkdown
+\stoptext

Next, invoke LuaTeX from the terminal:

-
context document.tex
+
context document.tex

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

@@ -1370,45 +1483,45 @@ Thomas,Edison,1847

Table 1: An example table

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

This is a transcluded markdown document.

-
2.1.2.2.9 Option contentBlocksLanguageMap
+

2.2.1.10 Option contentBlocksLanguageMap

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

The filename of the JSON file that maps filename extensions to programming language names in the iA Writer content blocks.

-
LaTeX example
+
LaTeX Example

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

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

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

-
{
-  "tex": "LaTeX"
-}
+
{
+  "tex": "LaTeX"
+}

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

-
This is an example code listing in \LaTeX.
+
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*.
+
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}
+
\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
+
lualatex --shell-escape document.tex

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

@@ -1438,38 +1551,38 @@ Thomas,Edison,1847

Table 1: An example table

-
This is an example code listing in \LaTeX.
+

This is a transcluded markdown document.

-
ConTeXt example
+
ConTeXt Example

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

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

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

-
{
-  "tex": "ConTeXt"
-}
+
{
+  "tex": "ConTeXt"
+}

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

-
This is an example code listing in \ConTeXt.
+
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*.
+
This is a *transcluded markdown document*.

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

-
\usemodule[t][markdown]
-\def\markdownOptionContentBlocks{true}
-\def\markdownOptionContentBlocksLanguageMap{language-map.json}
-\definetyping [ConTeXt]
-\setuptyping  [ConTeXt] [option=TEX]
-\starttext
-\startmarkdown
-/table.csv  (An example table)
-/code.tex   (An example code listing)
-/part.md    (A file transclusion example)
-\stopmarkdown
-\stoptext
-

Next, invoke LuaTeX from the terminal:

-
context document.tex
+
\usemodule[t][markdown]
+\def\markdownOptionContentBlocks{true}
+\def\markdownOptionContentBlocksLanguageMap{language-map.json}
+\definetyping [ConTeXt]
+\setuptyping  [ConTeXt] [option=TEX]
+\starttext
+\startmarkdown
+/table.csv  (An example table)
+/code.tex   (An example code listing)
+/part.md    (A file transclusion example)
+\stopmarkdown
+\stoptext
+

Next, invoke LuaTeX from the terminal:

+
context document.tex

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

@@ -1499,26 +1612,26 @@ Thomas,Edison,1847

Table 1: An example table

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

This is a transcluded markdown document.

-
2.1.2.2.10 Option definitionLists
+

2.2.1.11 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.
+
@@ -1529,27 +1642,27 @@ Term 2 with *inline markup*
-
LaTeX example
-

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

-
\documentclass{article}
-\usepackage[definitionLists]{markdown}
-\begin{document}
-\begin{markdown}
-Term 1
-
-:   Definition 1
-
-Term 2 with *inline markup*
-
-:   Definition 2
-
-        { some code, part of Definition 2 }
-
-    Third paragraph of definition 2.
-\end{markdown}
-\end{document}
-

Next, invoke LuaTeX from the terminal:

-
lualatex document.tex
+
LaTeX Example
+

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

+
\documentclass{article}
+\usepackage[definitionLists]{markdown}
+\begin{document}
+\begin{markdown}
+Term 1
+
+:   Definition 1
+
+Term 2 with *inline markup*
+
+:   Definition 2
+
+        { some code, part of Definition 2 }
+
+    Third paragraph of definition 2.
+\end{markdown}
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
lualatex document.tex

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

@@ -1563,27 +1676,27 @@ Term 2 with *inline markup*
-
ConTeXt example
-

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

-
\usemodule[t][markdown]
-\def\markdownOptionDefinitionLists{true}
-\starttext
-\startmarkdown
-Term 1
-
-:   Definition 1
-
-Term 2 with *inline markup*
-
-:   Definition 2
-
-        { some code, part of Definition 2 }
-
-    Third paragraph of definition 2.
-\stopmarkdown
-\stoptext
-

Next, invoke LuaTeX from the terminal:

-
context document.tex
+
ConTeXt Example
+

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

+
\usemodule[t][markdown]
+\def\markdownOptionDefinitionLists{true}
+\starttext
+\startmarkdown
+Term 1
+
+:   Definition 1
+
+Term 2 with *inline markup*
+
+:   Definition 2
+
+        { some code, part of Definition 2 }
+
+    Third paragraph of definition 2.
+\stopmarkdown
+\stoptext
+

Next, invoke LuaTeX from the terminal:

+
context document.tex

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

@@ -1597,28 +1710,28 @@ Term 2 with *inline markup*
-
2.1.2.2.11 Option fencedCode
+

2.2.1.12 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>
-  ```
+
@@ -1629,113 +1742,113 @@ if (a > 3) {
-
LaTeX example
-

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

-
\documentclass{article}
-\usepackage{minted}
-\usepackage[fencedCode]{markdown}
-\begin{document}
-\begin{markdown}
-~~~ js
-if (a > 3) {
-    moveShip(5 * gravity, DOWN);
-}
-~~~~~~
-
-  ``` html
-  <pre>
-    <code>
-      // Some comments
-      line 1 of code
-      line 2 of code
-      line 3 of code
-    </code>
-  </pre>
-  ```
-\end{markdown}
-\end{document}
-

Next, invoke LuaTeX from the terminal:

-
lualatex --shell-escape document.tex
-

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

-
-
if (a > 3) {
-    moveShip(5 * gravity, DOWN);
-}
-
<pre>
-  <code>
-    // Some comments
-    line 1 of code
-    line 2 of code
-    line 3 of code
-  </code>
-</pre>
-
-
ConTeXt example
-

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

-
\usemodule[t][markdown]
-\def\markdownOptionFencedCode{true}
-\definetyping [js]
-\definetyping [html]
-\setuptyping  [html] [option=XML]
-\starttext
-\startmarkdown
-~~~ js
-if (a > 3) {
-    moveShip(5 * gravity, DOWN);
-}
-~~~~~~
-
-  ``` html
-  <pre>
-    <code>
-      // Some comments
-      line 1 of code
-      line 2 of code
-      line 3 of code
-    </code>
-  </pre>
-  ```
-\stopmarkdown
-\stoptext
-

Next, invoke LuaTeX from the terminal:

-
context document.tex
-

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

-
-
if (a > 3) {
-    moveShip(5 * gravity, DOWN);
-}
-
<pre>
-  <code>
-    // Some comments
-    line 1 of code
-    line 2 of code
-    line 3 of code
-  </code>
-</pre>
-
-
2.1.2.2.12 Option footnotes
+
LaTeX Example
+

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

+
\documentclass{article}
+\usepackage{minted}
+\usepackage[fencedCode]{markdown}
+\begin{document}
+\begin{markdown}
+~~~ js
+if (a > 3) {
+    moveShip(5 * gravity, DOWN);
+}
+~~~~~~
+
+  ``` html
+  <pre>
+    <code>
+      // Some comments
+      line 1 of code
+      line 2 of code
+      line 3 of code
+    </code>
+  </pre>
+  ```
+\end{markdown}
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
lualatex --shell-escape document.tex
+

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

+
+ + +
+
ConTeXt Example
+

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

+
\usemodule[t][markdown]
+\def\markdownOptionFencedCode{true}
+\definetyping [js]
+\definetyping [html]
+\setuptyping  [html] [option=XML]
+\starttext
+\startmarkdown
+~~~ js
+if (a > 3) {
+    moveShip(5 * gravity, DOWN);
+}
+~~~~~~
+
+  ``` html
+  <pre>
+    <code>
+      // Some comments
+      line 1 of code
+      line 2 of code
+      line 3 of code
+    </code>
+  </pre>
+  ```
+\stopmarkdown
+\stoptext
+

Next, invoke LuaTeX from the terminal:

+
context document.tex
+

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

+
+ + +
+

2.2.1.13 Option footnotes

footnotes (default value: false)
true

Enable the pandoc footnote syntax extension:

-
Here is a footnote reference,[^1] and another.[^longnote]
-
-[^1]: Here is the footnote.
-
-[^longnote]: Here's one with multiple blocks.
-
-    Subsequent paragraphs are indented to show that they
-belong to the previous footnote.
-
-        { some.code }
-
-    The whole paragraph can be indented, or just the
-    first line.  In this way, multi-paragraph footnotes
-    work like multi-paragraph list items.
-
-This paragraph won't be part of the note, because it
-isn't indented.
+
@@ -1746,79 +1859,79 @@ isn't indented.
-
LaTeX example
-

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

-
\documentclass{article}
-\usepackage[footnotes]{markdown}
-\begin{document}
-\begin{markdown}
-Here is a footnote reference,[^1] and another.[^longnote]
-
-[^1]: Here is the footnote.
-
-[^longnote]: Here's one with multiple blocks.
-
-    Subsequent paragraphs are indented to show that they
-belong to the previous footnote.
-
-        { some.code }
-
-    The whole paragraph can be indented, or just the
-    first line.  In this way, multi-paragraph footnotes
-    work like multi-paragraph list items.
-
-This paragraph won't be part of the note, because it
-isn't indented.
-\end{markdown}
-\end{document}
-

Next, invoke LuaTeX from the terminal:

-
lualatex document.tex
-

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

-
-

Here is a footnote reference,1 and another.2

-

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

-
-
ConTeXt example
-

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

-
\usemodule[t][markdown]
-\def\markdownOptionFootnotes{true}
-\starttext
-\startmarkdown
-Here is a footnote reference,[^1] and another.[^longnote]
-
-[^1]: Here is the footnote.
-
-[^longnote]: Here's one with multiple blocks.
-
-    Subsequent paragraphs are indented to show that they
-belong to the previous footnote.
-
-        { some.code }
-
-    The whole paragraph can be indented, or just the
-    first line.  In this way, multi-paragraph footnotes
-    work like multi-paragraph list items.
-
-This paragraph won't be part of the note, because it
-isn't indented.
-\stopmarkdown
-\stoptext
-

Next, invoke LuaTeX from the terminal:

-
context document.tex
-

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

-
-

Here is a footnote reference,3 and another.4

-

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

-
-
2.1.2.2.13 Option hashEnumerators
+
LaTeX Example
+

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

+
\documentclass{article}
+\usepackage[footnotes]{markdown}
+\begin{document}
+\begin{markdown}
+Here is a footnote reference,[^1] and another.[^longnote]
+
+[^1]: Here is the footnote.
+
+[^longnote]: Here's one with multiple blocks.
+
+    Subsequent paragraphs are indented to show that they
+belong to the previous footnote.
+
+        { some.code }
+
+    The whole paragraph can be indented, or just the
+    first line.  In this way, multi-paragraph footnotes
+    work like multi-paragraph list items.
+
+This paragraph won't be part of the note, because it
+isn't indented.
+\end{markdown}
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
lualatex document.tex
+

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

+
+

Here is a footnote reference,1 and another.2

+

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

+
+
ConTeXt Example
+

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

+
\usemodule[t][markdown]
+\def\markdownOptionFootnotes{true}
+\starttext
+\startmarkdown
+Here is a footnote reference,[^1] and another.[^longnote]
+
+[^1]: Here is the footnote.
+
+[^longnote]: Here's one with multiple blocks.
+
+    Subsequent paragraphs are indented to show that they
+belong to the previous footnote.
+
+        { some.code }
+
+    The whole paragraph can be indented, or just the
+    first line.  In this way, multi-paragraph footnotes
+    work like multi-paragraph list items.
+
+This paragraph won't be part of the note, because it
+isn't indented.
+\stopmarkdown
+\stoptext
+

Next, invoke LuaTeX from the terminal:

+
context document.tex
+

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

+
+

Here is a footnote reference,3 and another.4

+

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

+
+

2.2.1.14 Option hashEnumerators

hashEnumerators (default value: false)
true

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

-
#. Bird
-#. McHale
-#. Parish
+
@@ -1829,27 +1942,27 @@ isn't indented.
-
LaTeX example
-

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

-
\documentclass{article}
-\usepackage{markdown}
-\begin{document}
-
-\begin{markdown}
-#. Bird
-#. McHale
-#. Parish
-\end{markdown}
-
-\begin{markdown*}{hashEnumerators}
-#. Bird
-#. McHale
-#. Parish
-\end{markdown*}
-
-\end{document}
-

Next, invoke LuaTeX from the terminal:

-
lualatex document.tex
+
LaTeX Example
+

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

+
\documentclass{article}
+\usepackage{markdown}
+\begin{document}
+
+\begin{markdown}
+. Bird
+. McHale
+. Parish
+\end{markdown}
+
+\begin{markdown*}{hashEnumerators}
+. Bird
+. McHale
+. Parish
+\end{markdown*}
+
+\end{document}
+

Next, invoke LuaTeX from the terminal:

+
lualatex document.tex

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

. Bird

@@ -1861,27 +1974,27 @@ isn't indented.
  • Parish
  • -
    ConTeXt example
    -

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

    -
    \usemodule[t][markdown]
    -\starttext
    -
    -\startmarkdown
    -#. Bird
    -#. McHale
    -#. Parish
    -\stopmarkdown
    -
    -\def\markdownOptionHashEnumerators{true}
    -\startmarkdown
    -#. Bird
    -#. McHale
    -#. Parish
    -\stopmarkdown
    -
    -\stoptext
    -

    Next, invoke LuaTeX from the terminal:

    -
    context document.tex
    +
    ConTeXt Example
    +

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

    +
    \usemodule[t][markdown]
    +\starttext
    +
    +\startmarkdown
    +. Bird
    +. McHale
    +. Parish
    +\stopmarkdown
    +
    +\def\markdownOptionHashEnumerators{true}
    +\startmarkdown
    +. Bird
    +. McHale
    +. Parish
    +\stopmarkdown
    +
    +\stoptext
    +

    Next, invoke LuaTeX from the terminal:

    +
    context document.tex

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

    . Bird

    @@ -1893,7 +2006,30 @@ isn't indented.
  • Parish
  • -
    2.1.2.2.14 Option html
    +

    2.2.1.15 Option headerAttributes

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

    Enable the assignment of HTML attributes to headings:

    + +

    These HTML attributes have currently no effect other than enabling content slicing.

    +
    +
    +
    +
    +
    false
    +

    Disable the assignment of HTML attributes to headings.

    +
    +
    +
    +
    +

    2.2.1.16 Option html

    html (default value: false)
    @@ -1910,273 +2046,296 @@ isn't indented.

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

    -
    Lua module example
    -

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

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

    +

    <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
    +
    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
    +
    \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?_
    +
    <div>
    +*Is there block tag support?*
    +</div>
    +*Is there <inline tag="tag"></inline> support?*
    +_Is there <!-- comment --> support?_
    +_Is there <? HTML instruction ?> support?_

    Next, invoke LuaTeX from the terminal:

    -
    texlua <CLI␣PATHNAME> -- content.md optionfalse.tex
    -texlua <CLI␣PATHNAME> html=true -- content.md optiontrue.tex
    -luatex document.tex
    -

    where <CLI␣PATHNAME> corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich markdown-cli.lua to locate the Lua CLI script file using Kpathsea.

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

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

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

    -

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

    +

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

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

    -
    Plain TeX example
    -

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

    -
    \input markdown
    -\input lmfonts
    -
    -\markdownBegin
    -<div>
    -*There is no block tag support.*
    -</div>
    -*There is no <inline tag="tag"></inline> support.*
    -_There is no <!-- comment --> support._
    -_There is no <? HTML instruction ?> support._
    -\markdownEnd
    -
    -\def\markdownOptionHtml{true}
    -\markdownBegin
    -<div>
    -*There is block tag support.*
    -</div>
    -*There is <inline tag="tag"></inline> support.*
    -_There is <!-- comment --> support._
    -_There is <? HTML instruction ?> support._
    -\markdownEnd
    -
    -\bye
    -

    Next, invoke LuaTeX from the terminal:

    -
    luatex document.tex
    -

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

    -
    -

    <div>There is no block tag support.</div> There is no <inline tag=”tag”></inline> support. There is no <!-- comment --> support. There is no <? HTML instruction ?> support.

    +
    Plain TeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    <div>There is no block tag support.</div> There is no <inline tag=”tag”></inline> support. There is no <!– comment –> support. There is no <? HTML instruction ?> support.

    There is support. There is support. There is support.

    -
    LaTeX example
    -

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

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

    Next, invoke LuaTeX from the terminal:

    -
    lualatex document.tex
    -

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

    -
    -

    <div>There is no block tag support.</div> There is no <inline tag=”tag”></inline> support. There is no <!-- comment --> support. There is no <? HTML instruction ?> support.

    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    <div>There is no block tag support.</div> There is no <inline tag=”tag”></inline> support. There is no <!– comment –> support. There is no <? HTML instruction ?> support.

    There is support. There is support. There is support.

    -
    ConTeXt example
    -

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

    -
    \usemodule[t][markdown]
    -\starttext
    -
    -\startmarkdown
    -<div>
    -*There is no block tag support.*
    -</div>
    -*There is no <inline tag="tag"></inline> support.*
    -_There is no <!-- comment --> support._
    -_There is no <? HTML instruction ?> support._
    -\stopmarkdown
    -
    -\def\markdownOptionHtml{true}
    -\startmarkdown
    -<div>
    -*There is block tag support.*
    -</div>
    -*There is <inline tag="tag"></inline> support.*
    -_There is <!-- comment --> support._
    -_There is <? HTML instruction ?> support._
    -\stopmarkdown
    -
    -\stoptext
    -

    Next, invoke LuaTeX from the terminal:

    -
    context document.tex
    -

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

    -
    -

    <div>There is no block tag support.</div> There is no <inline tag=”tag”></inline> support. There is no <!-- comment --> support. There is no <? HTML instruction ?> support.

    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    <div>There is no block tag support.</div> There is no <inline tag=”tag”></inline> support. There is no <!– comment –> support. There is no <? HTML instruction ?> support.

    There is support. There is support. There is support.

    -
    2.1.2.2.15 Option hybrid
    +

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

    +

    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.

    +

    Enable the escaping of special plain TeX characters outside verbatim environments, so that they are not interpretted by TeX. This is encouraged when typesetting automatically generated content or markdown documents that were not prepared with this package in mind.

    -
    Lua module example
    -

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

    -
    \input markdown
    -\input lmfonts
    -\directlua{
    -  local markdown = require("markdown")
    -  local convert_safe = markdown.new()
    -  local convert_unsafe = markdown.new({hybrid = true})
    -  local input = [[$\noexpand\sqrt{-1}$ *equals* $i$.]]
    -  tex.sprint(convert_safe(input) .. " " .. convert_unsafe(input)) }
    -\bye
    +
    Lua Module Example
    +

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

    +

    Then, invoke LuaTeX from the terminal:

    -
    luatex document.tex
    +

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

    -

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

    +

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

    +

    √-̅1̅ equals i.

    -
    Lua CLI example
    +
    Lua CLI Example

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

    -
    \input markdown
    -\input lmfonts
    -\input optionfalse
    -\input optiontrue
    -\bye
    +

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

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

    Next, invoke LuaTeX from the terminal:

    -
    texlua <CLI␣PATHNAME> -- content.md optionfalse.tex
    -texlua <CLI␣PATHNAME> hybrid=true -- content.md optiontrue.tex
    -luatex document.tex
    -

    where <CLI␣PATHNAME> corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich markdown-cli.lua to locate the Lua CLI script file using Kpathsea.

    + +

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

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

    -

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

    +

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

    +

    √-̅1̅ equals i.

    -
    Plain TeX example
    +
    Plain TeX Example

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

    -
    \input markdown
    -\input lmfonts
    -\markdownBegin
    -$\sqrt{-1}$ *equals* $i$.
    -\markdownEnd
    -\def\markdownOptionHybrid{true}
    -\markdownBegin
    -$\sqrt{-1}$ *equals* $i$.
    -\markdownEnd
    -\bye
    +

    Next, invoke LuaTeX from the terminal:

    -
    luatex document.tex
    +

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

    -

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

    +

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

    +

    √-̅1̅ equals i.

    -
    LaTeX example
    +
    LaTeX Example

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

    -
    \documentclass{article}
    -\usepackage{markdown}
    -\begin{document}
    -\begin{markdown}
    -$\sqrt{-1}$ *equals* $i$.
    -\end{markdown}
    -\begin{markdown*}{hybrid}
    -$\sqrt{-1}$ *equals* $i$.
    -\end{markdown*}
    -\end{document}
    +

    Next, invoke LuaTeX from the terminal:

    -
    lualatex document.tex
    +

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

    -

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

    +

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

    +

    √-̅1̅ equals i.

    -
    ConTeXt example
    +
    ConTeXt Example

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

    -
    \usemodule[t][markdown]
    -\starttext
    -\startmarkdown
    -$\sqrt{-1}$ *equals* $i$.
    -\stopmarkdown
    -\def\markdownOptionHybrid{true}
    -\startmarkdown
    -$\sqrt{-1}$ *equals* $i$.
    -\stopmarkdown
    -\stoptext
    +

    Next, invoke LuaTeX from the terminal:

    -
    context document.tex
    +

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

    -

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

    +

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

    +

    √-̅1̅ equals i.

    -
    2.1.2.2.16 Option inlineFootnotes
    +

    2.2.1.18 Option inlineFootnotes

    inlineFootnotes (default value: false)
    true

    Enable the pandoc inline footnote syntax extension:

    -
    Here is an inline note.^[Inlines notes are easier to
    -write, since you don't have to pick an identifier and
    -move down to type the note.]
    +
    @@ -2187,42 +2346,42 @@ move down to type the note.]
    -
    LaTeX example
    +
    LaTeX Example

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

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

    Next, invoke LuaTeX from the terminal:

    -
    lualatex document.tex
    +

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

    -

    Here is an inline note.5

    +

    Here is an inline note.5

    -
    ConTeXt example
    +
    ConTeXt Example

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

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

    Next, invoke LuaTeX from the terminal:

    -
    context document.tex
    +

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

    -

    Here is an inline note.6

    +

    Here is an inline note.6

    -
    2.1.2.2.17 Option preserveTabs
    +

    2.2.1.19 Option preserveTabs

    preserveTabs (default value: false)
    @@ -2239,12 +2398,149 @@ move down to type the note.]

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

    -
    2.1.2.2.18 Option smartEllipses
    +

    2.2.1.20 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⟩.

    +
    +
    +
    Plain TeX Example
    +

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

    + +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    The Tragedy of Hamlet

    +

    Shakespeare’s longest play.

    +

    Act I

    +

    Hamlet talks to ghost.

    +

    Act III

    +

    Hamlet kills Polonius.

    +

    Act V

    +

    Hamlet dies.

    +
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    The Tragedy of Hamlet

    +

    Shakespeare’s longest play.

    +

    Act I

    +

    Hamlet talks to ghost.

    +

    Act III

    +

    Hamlet kills Polonius.

    +

    Act V

    +

    Hamlet dies.

    +
    +
    ConTeXt Example
    +

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

    + +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    The Tragedy of Hamlet

    +

    Shakespeare’s longest play.

    +

    Act I

    +

    Hamlet talks to ghost.

    +

    Act III

    +

    Hamlet kills Polonius.

    +

    Act V

    +

    Hamlet dies.

    +
    +

    2.2.1.21 Option smartEllipses

    smartEllipses (default value: false)
    true
    -

    Convert any ellipses in the input to the \markdownRendererEllipsis TeX macro.

    +

    Convert any ellipses in the input to the \markdownRendererEllipsis TeX macro.

    @@ -2255,223 +2551,223 @@ move down to type the note.]
    -
    Lua module example
    -

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

    -
    \input markdown
    -\def\markdownRendererEllipsis{. . .}
    -\input lmfonts
    -\directlua{
    -  local markdown = require("markdown")
    -  local convert = markdown.new()
    -  input = "These are just three regular dots ..."
    -  tex.sprint(convert(input)) }
    -\par
    -\directlua{
    -  local markdown = require("markdown")
    -  local convert = markdown.new({smartEllipses = true})
    -  input = "... and this is a victorian ellipsis."
    -  tex.sprint(convert(input)) }
    -\bye
    +
    Lua Module Example
    +

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

    +

    Then, invoke LuaTeX from the terminal:

    -
    luatex document.tex
    +

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

    -

    These are just three regular dots ...

    +

    These are just three regular dots …

    . . . and this is a victorian ellipsis.

    -
    Lua CLI example
    +
    Lua CLI Example

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

    -
    \input markdown
    -\def\markdownRendererEllipsis{. . .}
    -\input lmfonts
    -\input optionfalse
    -\par
    -\input optiontrue
    -\bye
    +

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

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

    Next, invoke LuaTeX from the terminal:

    -
    texlua <CLI␣PATHNAME> -- content.md optionfalse.tex
    -texlua <CLI␣PATHNAME> smartEllipses=true -- content.md optiontrue.tex
    -luatex document.tex
    -

    where <CLI␣PATHNAME> corresponds to the location of the Lua CLI script file, such as ~/texmf/scripts/markdown/markdown-cli.lua on UN*X systems or C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua on Windows systems. Use the command kpsewhich markdown-cli.lua to locate the Lua CLI script file using Kpathsea.

    + +

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

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

    -

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

    +

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

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

    -
    Plain TeX example
    +
    Plain TeX Example

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

    -
    \input markdown
    -\def\markdownRendererEllipsis{. . .}
    -
    -\markdownBegin
    -These are just three regular dots ...
    -\markdownEnd
    -
    -\def\markdownOptionSmartEllipses{true}
    -\markdownBegin
    -... and this is a victorian ellipsis.
    -\markdownEnd
    -
    -\bye
    +

    Next, invoke LuaTeX from the terminal:

    -
    luatex document.tex
    +

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

    -

    These are just three regular dots ...

    +

    These are just three regular dots …

    . . . and this is a victorian ellipsis.

    -
    LaTeX example
    -

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

    -
    \documentclass{article}
    -\usepackage{markdown}
    -\markdownSetup{
    -  renderers = {
    -    ellipsis = {. . .} }}
    -\begin{document}
    -
    -\begin{markdown}
    -These are just three regular dots ...
    -\end{markdown}
    -
    -\begin{markdown*}{smartEllipses}
    -... and this is a victorian ellipsis.
    -\end{markdown*}
    -
    -\end{document}
    -

    Next, invoke LuaTeX from the terminal:

    -
    lualatex document.tex
    -

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

    -
    -

    These are just three regular dots ...

    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    These are just three regular dots …

    . . . and this is a victorian ellipsis.

    -
    ConTeXt example
    +
    ConTeXt Example

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

    -
    \usemodule[t][markdown]
    -\def\markdownRendererEllipsis{. . .}
    -\starttext
    -
    -\startmarkdown
    -These are just three regular dots ...
    -\stopmarkdown
    -
    -\def\markdownOptionSmartEllipses{true}
    -\startmarkdown
    -... and this is a victorian ellipsis.
    -\stopmarkdown
    -
    -\stoptext
    +

    Next, invoke LuaTeX from the terminal:

    -
    context document.tex
    +

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

    -

    These are just three regular dots ...

    +

    These are just three regular dots …

    . . . and this is a victorian ellipsis.

    -
    2.1.2.2.19 Option startNumber
    +

    2.2.1.22 Option startNumber

    startNumber (default value: true)
    true
    -

    Make the number in the first item of an ordered lists significant. The item numbers will be passed to the \markdownRendererOlItemWithNumber TeX macro.

    +

    Make the number in the first item of an ordered lists significant. The item numbers will be passed to the \markdownRendererOlItemWithNumber TeX macro.

    false
    -

    Ignore the numbers in the ordered list items. Each item will only produce a \markdownRendererOlItem TeX macro.

    +

    Ignore the numbers in the ordered list items. Each item will only produce a \markdownRendererOlItem TeX macro.

    -
    LaTeX example
    -

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

    -
    \documentclass{article}
    -\usepackage{markdown}
    -\begin{document}
    -
    -\begin{markdown}
    -The following list respects the numbers specified in the markup:
    -
    -3. third item
    -4. fourth item
    -5. fifth item
    -\end{markdown}
    -
    -\begin{markdown*}{startNumber=false}
    -The following list does not respect the numbers specified in the
    -markup:
    -
    -3. third item
    -4. fourth item
    -5. fifth item
    -\end{markdown*}
    -
    -\end{document}
    -

    Next, invoke LuaTeX from the terminal:

    -
    lualatex document.tex
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    +

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

    The following list respects the numbers specified in the markup:

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

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

      -
        +
        1. third item
        2. fourth item
        3. fifth item
    -
    ConTeXt example
    -

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

    -
    \usemodule[t][markdown]
    -\starttext
    -
    -\startmarkdown
    -The following list respects the numbers specified in the markup:
    -
    -3. third item
    -4. fourth item
    -5. fifth item
    -\stopmarkdown
    -
    -\def\markdownOptionStartNumber{false}
    -\startmarkdown
    -The following list respects the numbers specified in the markup:
    -
    -3. third item
    -4. fourth item
    -5. fifth item
    -\stopmarkdown
    -\stoptext
    -

    Next, invoke LuaTeX from the terminal:

    -
    context document.tex
    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    +

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

    The following list respects the numbers specified in the markup:

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

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

      -
        +
        1. third item
        2. fourth item
        3. fifth item
    -
    2.1.2.2.20 Option tightLists
    +

    2.2.1.23 Option tightLists

    tightLists (default value: true)
    true
    -

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

    +

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

    @@ -2482,39 +2778,39 @@ The following list respects the numbers specified in the markup:
    -
    LaTeX example
    -

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

    -
    \documentclass{article}
    -\usepackage{markdown}
    -\begin{document}
    -
    -\begin{markdown}
    -The following list is tight:
    -
    -  - first item
    -  - second item
    -  - third item
    -
    -The following list is loose:
    -
    -  - first item
    -  - second item that spans
    -
    -    multiple paragraphs
    -  - third item
    -\end{markdown}
    -
    -\begin{markdown*}{tightLists=false}
    -The following list is now also loose:
    -
    -  - first item
    -  - second item
    -  - third item
    -\end{markdown*}
    -
    -\end{document}
    -

    Next, invoke LuaTeX from the terminal:

    -
    lualatex document.tex
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    +

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

    The following list is tight:

    @@ -2537,134 +2833,2114 @@ multiple paragraphs
  • third item

  • -
    2.1.2.2.21 Option underscores
    +

    2.2.1.24 Option underscores

    underscores (default value: true)
    true

    Both underscores and asterisks can be used to denote emphasis and strong emphasis:

    -
    *single asterisks*
    -_single underscores_
    -**double asterisks**
    -__double underscores__
    +
    false
    -

    Only asterisks can be used to denote emphasis and strong emphasis. This makes it easy to write math with the option without the need to constantly escape subscripts.

    +

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

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

    -
    \input markdown
    -\def\markdownOptionHybrid{true}
    -
    -\markdownBegin
    -This is _emphasized text_ and this is a math subscript: $m\_n$.
    -\markdownEnd
    -
    -\def\markdownOptionUnderscores{false}
    -\markdownBegin
    -This is *emphasized text* and this is a math subscript: $m_n$.
    -\markdownEnd
    -
    -\bye
    +

    Next, invoke LuaTeX from the terminal:

    -
    luatex document.tex
    +

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

    This is emphasized text and this is a math subscript: mₙ.

    This is emphasized text and this is a math subscript: mₙ.

    -
    LaTeX example
    +
    LaTeX Example

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

    -
    \documentclass{article}
    -\usepackage[hybrid]{markdown}
    -\begin{document}
    -
    -\begin{markdown}
    -This is _emphasized text_ and this is a math subscript: $m\_n$.
    -\end{markdown}
    -
    -\begin{markdown*}{underscores=false}
    -This is *emphasized text* and this is a math subscript: $m_n$.
    -\end{markdown*}
    -
    -\end{document}
    +

    Next, invoke LuaTeX from the terminal:

    -
    lualatex document.tex
    +

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

    This is emphasized text and this is a math subscript: mₙ.

    This is emphasized text and this is a math subscript: mₙ.

    -
    ConTeXt example
    +
    ConTeXt Example

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

    -
    \usemodule[t][markdown]
    -\def\markdownOptionHybrid{true}
    -\starttext
    -
    -\startmarkdown
    -This is _emphasized text_ and this is a math subscript: $m\_n$.
    -\stopmarkdown
    -
    -\def\markdownOptionUnderscores{false}
    -\startmarkdown
    -This is *emphasized text* and this is a math subscript: $m_n$.
    -\stopmarkdown
    -
    -\stoptext
    +

    Next, invoke LuaTeX from the terminal:

    -
    context document.tex
    +

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

    This is emphasized text and this is a math subscript: mₙ.

    This is emphasized text and this is a math subscript: mₙ.

    -

    2.2 Plain TeX

    -

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

    -

    2.2.1 Interfaces

    - -

    2.2.2 Options

    - -

    2.2.3 Token renderers

    - -

    2.3 LaTeX

    -

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

    - -

    2.3.1 Interfaces

    - -

    2.3.2 Options

    - -

    2.3.3 Token renderers

    - -

    2.4 ConTeXt

    -

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

    -

    2.4.1 Interfaces

    - -

    2.4.2 Options

    - -

    2.4.3 Token renderers

    - -
    +

    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 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, and
    • +
    • \markdownOptionCacheDir.
    • +
    +

    Using a text editor, create a folder named output-directory and a text document named document.tex with the following content:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +

    2.3 Markdown Tokens

    +

    A key feature of the Markdown package is the support for manipulating markdown tokens, such as headings, emphasized text, links, and lists, in TeX. Instead of reducing TeX to a PDF document producer, the Markdown package allows the user to specify how every markdown token should be processed and rendered.

    +

    2.3.1 Token Renderers

    +

    Token renderers are user-defined TeX macros, which render markdown tokens. In this section, I will describe the individual token renderers.

    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    Hello world!

    +

    (The end of a block)

    +

    Foo bar!

    +
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    Hello world!

    +

    (The end of a block)

    +

    Foo bar!

    +
    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    Hello world!

    +

    (The end of a block)

    +

    Foo bar!

    +
    +

    2.3.1.2 Line Break Renderer

    +

    The \markdownRendererLineBreak macro represents a forced line break. The macro receives no arguments.

    +
    Plain TeX Example
    +

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

    + +

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

    +
    Hello world!  
    _Foo_ bar!
    +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    Hello world!

    +

    (A forced linebreak)

    +

    Foo bar!

    +
    +
    LaTeX Example
    +

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

    + +

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

    +
    Hello world!  
    _Foo_ bar!
    +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    Hello world!

    +

    (A forced linebreak)

    +

    Foo bar!

    +
    +
    ConTeXt Example
    +

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

    + +

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

    +
    Hello world!  
    _Foo_ bar!
    +

    Next, invoke LuaTeX from the terminal:

    + +

    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 true. The macro receives no arguments.

    +
    Plain TeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    The secret word is SHAZAM!

    +
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    The secret word is SHAZAM!

    +
    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    Hello world!

    +

    (The end of a block)

    +

    Foo bar!

    +
    +

    2.3.1.4 Non-Breaking Space Renderer

    +

    The \markdownRendererNbsp macro represents a non-breaking space.

    +
    LaTeX Example
    +

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

    + +

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

    + +

    Next, invoke LuaTeX and BibTeX from the terminal:

    + +

    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.

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    A PDF document named document.pdf should be produced and contain the following text, where the middot (·) denotes a non-breakable 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.

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    A PDF document named document.pdf should be produced and contain the following text, where the middot (·) denotes a non-breakable 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.

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    A PDF document named document.pdf should be produced and contain the following text, where the middot (·) denotes a non-breakable 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:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

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

    +

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

    +

    √-̅1̅ equals i.

    +
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

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

    +

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

    +

    √-̅1̅ equals i.

    +
    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

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

    +

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

    +

    √-̅1̅ equals i.

    +
    + +

    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:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

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

    +
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

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

    +
    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    + +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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:

    + +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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.

    • +
    +
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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.

    • +
    +
    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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 true. The macro receives no arguments.

    +

    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:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

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

    +

    This is a loose list:

    +
      +
    1. This is the first item.

    2. +
    3. This is the second item.

    4. +
    5. This is the third item.

    6. +
    +
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

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

    +

    This is a loose list:

    +
      +
    1. This is the first item.

    2. +
    3. This is the second item.

    4. +
    5. This is the third item.

    6. +
    +
    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

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

    +

    This is a loose list:

    +
      +
    1. This is the first item.

    2. +
    3. This is the second item.

    4. +
    5. This is the third item.

    6. +
    +
    +

    2.3.1.12 Definition List Renderers

    +

    The following macros are only produced, when the definitionLists option is true.

    +

    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:

    +
    \input markdown
    +\def\markdownOptionDefinitionLists{true}
    +\def\markdownOptionTightLists{true}
    +
    +\def\markdownRendererInterblockSeparator{%
    +  :%
    +  \def\markdownRendererInterblockSeparator{\par}%
    +}
    +\def\markdownRendererDlBeginTight{%
    +  \begingroup
    +  \parindent=0pt
    +}
    +\def\markdownRendererDlItem#1{%
    +  \par{\bf#1}%
    +  \def\markdownRendererDlDefinitionEnd{%
    +    ,
    +    \def\markdownRendererDlDefinitionEnd{%
    +      , and
    +      \def\markdownRendererDlDefinitionEnd{.}%
    +    }%
    +  }%
    +}
    +\def\markdownRendererDlItemEnd{}
    +\def\markdownRendererDlDefinitionBegin{\par--\kern 0.5em}
    +\def\markdownRendererDlEndTight{\endgroup}
    +
    +\markdownBegin
    +This is a tight definition list
    +
    +Coffee
    +:   black hot drink
    +:   prepared from roasted coffee beans
    +:   one of the most traded agricultural commodities in the world
    +
    +Milk
    +:   white cold drink
    +:   nutrient-rich
    +:   produced on an industrial scale
    +\markdownEnd
    +
    +\def\markdownRendererInterblockSeparator{%
    +  \def\markdownRendererInterblockSeparator{\par}%
    +}
    +\def\markdownRendererDlBegin{}
    +\def\markdownRendererDlItem#1{%
    +  . #1 is a
    +  \def\markdownRendererDlDefinitionBegin{%
    +    \def\markdownRendererDlDefinitionBegin{%
    +      ,
    +      \def\markdownRendererDlDefinitionBegin{, and }%
    +    }%
    +  }%
    +}
    +\def\markdownRendererDlItemEnd{}
    +\def\markdownRendererDlDefinitionEnd{}
    +\def\markdownRendererDlEnd{.}
    +
    +\markdownBegin
    +This is a loose definition list
    +
    +Coffee
    +
    +:   black hot drink
    +
    +:   prepared from roasted coffee beans
    +
    +:   one of the most traded agricultural commodities in the world
    +
    +Milk
    +
    +:   white cold drink
    +
    +:   nutrient-rich
    +
    +:   produced on an industrial scale
    +\markdownEnd
    +
    +\bye
    +

    Next, invoke LuaTeX from the terminal:

    + +

    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:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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:

    +
    \usemodule[t][markdown]
    +\def\markdownOptionDefinitionLists{true}
    +\def\markdownOptionTightLists{true}
    +\starttext
    +
    +\def\markdownRendererInterblockSeparator{%
    +  :%
    +  \def\markdownRendererInterblockSeparator{\par}%
    +}
    +\def\markdownRendererDlBeginTight{}
    +\def\markdownRendererDlItem#1{%
    +  \par{\bf#1}%
    +  \startitemize
    +  \def\markdownRendererDlDefinitionEnd{%
    +    ,
    +    \def\markdownRendererDlDefinitionEnd{%
    +      , and
    +      \def\markdownRendererDlDefinitionEnd{.}%
    +    }%
    +  }%
    +}
    +\def\markdownRendererDlItemEnd{\stopitemize}
    +\def\markdownRendererDlDefinitionBegin{\item}
    +\def\markdownRendererDlEndTight{}
    +
    +\startmarkdown
    +This is a tight definition list
    +
    +Coffee
    +:   black hot drink
    +:   prepared from roasted coffee beans
    +:   one of the most traded agricultural commodities in the world
    +
    +Milk
    +:   white cold drink
    +:   nutrient-rich
    +:   produced on an industrial scale
    +\stopmarkdown
    +
    +\def\markdownRendererInterblockSeparator{%
    +  \def\markdownRendererInterblockSeparator{\par}%
    +}
    +\def\markdownRendererDlBegin{}
    +\def\markdownRendererDlItem#1{%
    +  . #1 is a
    +  \def\markdownRendererDlDefinitionBegin{%
    +    \def\markdownRendererDlDefinitionBegin{%
    +      ,
    +      \def\markdownRendererDlDefinitionBegin{, and }%
    +    }%
    +  }%
    +}
    +\def\markdownRendererDlItemEnd{}
    +\def\markdownRendererDlDefinitionEnd{}
    +\def\markdownRendererDlEnd{.}
    +
    +\startmarkdown
    +This is a loose definition list
    +
    +Coffee
    +
    +:   black hot drink
    +
    +:   prepared from roasted coffee beans
    +
    +:   one of the most traded agricultural commodities in the world
    +
    +Milk
    +
    +:   white cold drink
    +
    +:   nutrient-rich
    +
    +:   produced on an industrial scale
    +\stopmarkdown
    +
    +\stoptext
    +

    Next, invoke LuaTeX from the terminal:

    + +

    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:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    This is emphasis.

    +

    This is strong emphasis.

    +
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    This is emphasis.

    +

    This is strong emphasis.

    +
    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    A PDF document named document.pdf should be produced and contain the following text except for the filename, which may differ:

    +
    +

    The following code is contained in file ./_markdown_document/882453149edcf288976647f6fe147ada.verbatim:

    + +

    The following code in Python contained in file ./_markdown_document/cf2a96e2120cef5b1fae5fea36fcc27b.verbatim:

    + +
    +

    2.3.1.16 Heading Renderers

    +

    The \markdownRendererHeadingOne macro represents a first level heading. The macro receives a single argument that corresponds to the heading text.

    +

    The \markdownRendererHeadingTwo macro represents a second level heading. The macro receives a single argument that corresponds to the heading text.

    +

    The \markdownRendererHeadingThree macro represents a third level heading. The macro receives a single argument that corresponds to the heading text.

    +

    The \markdownRendererHeadingFour macro represents a fourth level heading. The macro receives a single argument that corresponds to the heading text.

    +

    The \markdownRendererHeadingFive macro represents a fifth level heading. The macro receives a single argument that corresponds to the heading text.

    +

    The \markdownRendererHeadingSix macro represents a sixth level heading. The macro receives a single argument that corresponds to the heading text.

    +
    Plain TeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    65536

    +
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    65536

    +
    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    65536

    +
    +

    2.3.1.17 Horizontal Rule Renderer

    +

    The \markdownRendererHorizontalRule macro represents a horizontal rule. The macro receives no arguments.

    +
    Plain TeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    This is the first page.

    +
    +

    This is the second page.

    +
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    This is the first page.

    +
    +

    This is the second page.

    +
    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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 true. The macro receives the parameter {number of citations} followed by {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:

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

    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.2 Token Renderer Prototypes

    +

    By default, token renderers point to package-defined TeX macros, further referred to as prototypes, which provide useful default definitions.

    +
    Plain TeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    Packages can specify token renderer prototypes.

    +

    User-defined token renderers take precedence.

    +
    +
    LaTeX Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    Packages can specify token renderer prototypes.

    +

    User-defined token renderers take precedence.

    +
    +
    ConTeXt Example
    +

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

    + +

    Next, invoke LuaTeX from the terminal:

    + +

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

    +
    +

    Packages can specify token renderer prototypes.

    +

    User-defined token renderers take precedence.

    +
    +

      -
    1. Here is the footnote.

    2. -
    3. Here's one with multiple blocks.

      +
    4. Here is the footnote.

    5. +
    6. Here’s one with multiple blocks.

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

      { some.code }
      -

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

    7. -
    8. Here is the footnote.

    9. -
    10. Here's one with multiple blocks.

      +

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

    11. +
    12. Here is the footnote.

    13. +
    14. Here’s one with multiple blocks.

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

      { some.code }
      -

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

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

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

    19. +

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

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

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

    -
    + diff --git a/Master/texmf-dist/doc/generic/markdown/markdown.md b/Master/texmf-dist/doc/generic/markdown/markdown.md index 7bbfc7fa4f1..ddd8c67dcdb 100644 --- a/Master/texmf-dist/doc/generic/markdown/markdown.md +++ b/Master/texmf-dist/doc/generic/markdown/markdown.md @@ -2,6 +2,7 @@ --- title: Markdown Package User Manual author: Vít Novotný +date: v\markdownVersion{} (\markdownLastModified{}) --- @@ -9,12 +10,12 @@ author: Vít Novotný Introduction ============ -The [Markdown package][pkg] converts [markdown][] markup to TeX commands. The -functionality is provided both as a Lua module, and as plain TeX, LaTeX, and -ConTeXt macro packages that can be used to directly typeset TeX documents +The [Markdown package][pkg] converts [markdown][] markup to \TeX{} commands. The +functionality is provided both as a Lua module and as plain \TeX{}, \LaTeX{}, and +\Hologo{ConTeXt} macro packages that can be used to directly typeset \TeX documents containing markdown markup. Unlike other convertors, the Markdown package makes it easy to redefine how each and every markdown element is rendered. -Creative abuse of the markdown syntax is encouraged. +Creative abuse of the markdown syntax is encouraged. ;-) [markdown]: https://daringfireball.net/projects/markdown/basics/ (Daring Fireball: Markdown Basics) @@ -23,9 +24,9 @@ Creative abuse of the markdown syntax is encouraged. This document is a user manual for the [Markdown package][pkg]. It provides -beginner tutorials and code examples. For an in-depth description of the -package requirements, interfaces, and implementation, please refer to the -[technical documentation][techdoc]. +tutorials and code examples. For an in-depth description of the package +requirements, interfaces, and implementation, please refer to the [technical +documentation][techdoc]. [techdoc]: http://mirrors.ctan.org/macros/generic/markdown/markdown.pdf (A Markdown Interpreter for TeX) @@ -34,19 +35,19 @@ package requirements, interfaces, and implementation, please refer to the 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 +The package requires a working \TeX{} distribution. [\TeX{} Live][tl] ≥ 2013 is +known to work and so are recent installation of [Mik\TeX{}][mik]. If you are +using a minimal installation of a \TeX{} distribution, please consult the [technical documentation][techdoc] for a detailed list of required packages. - [TeX Live]: https://www.tug.org/texlive/ (TeX Live - TeX Users Group) - [MikTeX]: https://miktex.org/ (Home - MiKTeXorg) + [tl]: https://www.tug.org/texlive/ (TeX Live - TeX Users Group) + [mik]: https://miktex.org/ (Home - MiKTeXorg) Installation ------------ -The package comes pre-installed with [TeX Live][] ≥ 2016 and with recent -installations of [MikTeX][]. Unless you explicitly wish to use the latest +The package comes pre-installed with [\TeX{} Live][tl] ≥ 2016 and with recent +installations of [MikTeX][mik]. 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 @@ -55,7 +56,7 @@ using Git: git clone https://github.com/witiko/markdown `````` Next, enter the directory named `markdown` and interpret the file named -`markdown.ins` file using a Unicode-aware TeX engine, such as XeTeX or +`markdown.ins` file using a Unicode-aware \TeX{} engine, such as XeTeX or LuaTeX: ``` sh cd markdown @@ -63,16 +64,17 @@ luatex markdown.ins `````` This should produce the following files: - * `markdown.lua` – the Lua module, - * `markdown-cli.lua` – the Lua command-line interface, - * `markdown.tex` – the plain TeX macro package, - * `markdown.sty` – the LaTeX package, and - * `t-markdown.tex` – the ConTeXt module. + * `markdown.lua`, the Lua module, + * `markdown-cli.lua`, the Lua command-line interface, + * `markdown.tex`, the plain \TeX{} macro package, + * `markdown.sty`, the \LaTeX{} package, and + * `t-markdown.tex`, the \Hologo{ConTeXt} module. -### Local installation +### 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: +To perform a local installation, place the above files into your \TeX{} +directory structure. This is generally where the individual files should be +placed: * `/tex/luatex/markdown/markdown.lua` * `/scripts/markdown/markdown-cli.lua` @@ -80,23 +82,23 @@ structure. This is generally where the individual files should be placed: * `/tex/latex/markdown/markdown.sty` * `/tex/context/third/markdown/t-markdown.tex` -where `` corresponds to a root of your TeX distribution, such as +where `` corresponds to a root of your \TeX{} distribution, such as `/usr/share/texmf` and `~/texmf` on UN\*X systems or -`C:\Users\\texmf` on Windows systems. When in doubt, -consult the manual of your TeX distribution. +`C:\Users\`\meta{Your username}`\texmf` on Windows systems. When in doubt, +consult the manual of your \TeX{} distribution. -### Portable installation ### +### 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. +\TeX{} document and distribute them together. This way your document can be +portably typeset on legacy \TeX{} distributions. -First document +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 +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. ### Using Lua @@ -109,7 +111,7 @@ following content: \bye ``````` -#### Using the Lua module +#### Using the Lua Module Using a text editor, create a text document named `hello.lua` with the following content: @@ -133,7 +135,7 @@ texlua hello.lua > hello.tex pdftex document.tex `````` -#### Using the Lua CLI +#### Using the Lua Command-Line Interface Using a text editor, create a text document named `hello.md` with the following content: @@ -142,12 +144,12 @@ Hello *world*! `````` Next, invoke LuaTeX from the terminal: ``` sh -texlua -- hello.md hello.tex +texlua ⟨CLI pathname⟩ -- hello.md hello.tex luatex document.tex `````` -where `` corresponds to the location of the Lua CLI script file, +where \meta{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\\texmf\scripts\markdown\markdown-cli.lua` on Windows +`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI script file using [Kpathsea][]. @@ -156,11 +158,11 @@ 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: ``` sh -texlua -- hello.md hello.tex +texlua ⟨CLI pathname⟩ -- hello.md hello.tex pdftex document.tex `````` -### Using plain TeX +### Using Plain \TeX{} Using a text editor, create a text document named `document.tex` with the following content: @@ -181,7 +183,7 @@ A PDF document named `document.pdf` should be produced and contain the text pdftex --shell-escape document.tex ``````` -### Using LaTeX +### Using \LaTeX{} Using a text editor, create a text document named `document.tex` with the following content: @@ -221,7 +223,7 @@ lualatex latex.tex `````` to see the effect of your changes. -### Using ConTeXt +### Using \Hologo{ConTeXt} Using a text editor, create a text document named `document.tex` with the following content: @@ -263,3240 +265,14 @@ to see the effect of your changes. Examples ======== -This section will show how to use the package by example. - - -Lua ---- - -The Lua part of the package makes it possible to convert a markdown document -into TeX commands and typeset it later when convenient. Although the typical -user will not find this terribly useful and will instead use the plain TeX, -LaTeX, and ConTeXt macro packages to convert and typeset the markdown documents -in a single step, they will still benefit from learning the options that -control the behavior of the Lua parser. - - -### Interfaces - -The Lua part of the package exposes two interfaces – the `markdown` Lua module, -and the Lua command-line interface (CLI). - -#### The Lua module - -The `markdown` Lua module exposes the `new(options)` method, which creates a -converter function from markdown to TeX. The properties of the converter -function are specified by the Lua table `options`. The parameter is optional; -when unspecified, the behaviour will be the same as if `options` were an empty -table. - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input lmfonts -\input example -\bye -``````` -Using a text editor, create a text document named `example.lua` with the -following content: -``` lua -#!/usr/bin/env texlua -local kpse = require("kpse") -kpse.set_program_name("luatex") -local markdown = require("markdown") -local convert_safe = markdown.new() -local convert_unsafe = markdown.new({hybrid = true}) -local input = [[$\sqrt{-1}$ *equals* $i$.]] -print(convert_safe(input) .. " " .. convert_unsafe(input)) -``````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua example.lua > example.tex -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the text -“\$\\sqrt{-1}\$ *equals* \$i\$. √-̅1̅ *equals* $i$.” Invoking pdfTeX should have -the same effect: -``` sh -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: -``` tex -\input markdown -\input lmfonts -\directlua{ - local markdown = require("markdown") - local convert_safe = markdown.new() - local convert_unsafe = markdown.new({hybrid = true}) - local input = [[$\noexpand\sqrt{-1}$ *equals* $i$.]] - tex.sprint(convert_safe(input) .. " " .. convert_unsafe(input)) } -\bye -``````` -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -``````` -A PDF document named `document.pdf` should be produced and contain the text -“\$\\sqrt {-1}\$ *equals* \$i\$. √-̅1̅ *equals* $i$.” In this case, we cannot -use pdfTeX, because pdfTeX does not define the `\directlua` TeX command. - -#### The Lua CLI - -The Lua command-line interface (CLI) accepts the same options as the `markdown` -Lua module, but now the options are specified as command-line parameters. - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input lmfonts -\input safe\ \input unsafe -\bye -``````` -Using a text editor, create a text document named `example.md` with the -following content: -``` md -$\sqrt{-1}$ *equals* $i$. -`````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua -- example.md safe.tex -texlua hybrid=true -- example.md unsafe.tex -luatex document.tex -`````` -where `` 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\\texmf\scripts\markdown\markdown-cli.lua` on Windows -systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI -script file using [Kpathsea][]. - -A PDF document named `document.pdf` should be produced and contain the text -“\$\\sqrt{-1}\$ *equals* \$i\$. √-̅1̅ *equals* $i$.” Invoking pdfTeX should have -the same effect: -``` sh -texlua -- example.md safe.tex -texlua hybrid=true -- example.md unsafe.tex -pdftex document.tex -`````` - - -### Options - -This section will cover the options recognized by the Lua interface. The -interfaces of the plain TeX, LaTeX, and ConTeXt macro packages recognize these -options as well, in addition to their own options. - - -#### File and Directory Names - - -##### 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 {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -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 {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input hello -\bye -``````` -Using a text editor, create a text document named `hello.md` with the -following content: -``` md -Hello *world*! -`````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua cacheDir=cache -- hello.md hello.tex -luatex document.tex -``````` -where `` 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\\texmf\scripts\markdown\markdown-cli.lua` on Windows -systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI -script file using [Kpathsea][]. - -A PDF document named `document.pdf` should be produced and contain the text -“Hello *world*!” A directory named `cache` containing several cache files of -the Markdown package will also be produced as we requested using the `cacheDir` -option. - -###### Plain TeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\def\markdownOptionCacheDir{cache} -\markdownBegin -Hello *world*! -\markdownEnd -\bye -``````` -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the text “Hello -*world*!” A directory named `cache` containing several cache files of the -Markdown package will also be produced as we requested using the `cacheDir` -option. - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage[cacheDir=cache]{markdown} -\begin{document} -\begin{markdown} -Hello *world*! -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the text “Hello -*world*!” A directory named `cache` containing several cache files of the -Markdown package will also be produced as we requested using the `cacheDir` -option. - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\def\markdownOptionCacheDir{cache} -\starttext -\startmarkdown -Hello *world*! -\stopmarkdown -\stoptext -``````` -Next, invoke LuaTeX from the terminal: -``` sh -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. - - -#### Parser Options - - -##### 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 {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -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 {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input lmfonts -\input optionfalse -\input optiontrue -\bye -``````` -Using a text editor, create a text document named `content.md` with the -following content: -``` md -A paragraph. -> A quote? -`````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua -- content.md optionfalse.tex -texlua blankBeforeBlockquote=true -- content.md optiontrue.tex -luatex document.tex -``````` -where `` 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\\texmf\scripts\markdown\markdown-cli.lua` on Windows -systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI -script file using [Kpathsea][]. - -A PDF document named `document.pdf` should be produced and contain the -following text: - -> A paragraph. -> -> > A quote? -> -> A paragraph. > A quote? - -###### Plain TeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> A paragraph. -> -> > A quote. -> -> A paragraph > Not a quote. - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> A paragraph. -> -> > A quote. -> -> A paragraph > Not a quote. - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\starttext +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][techdoc]. -\startmarkdown -A paragraph. -> A quote. -\stopmarkdown - -\def\markdownOptionBlankBeforeBlockquote{true} -\startmarkdown -A paragraph. -> Not a quote. -\stopmarkdown - -\stoptext -``````` -Next, invoke LuaTeX from the terminal: -``` sh -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. - - -##### 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 {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input lmfonts -\directlua{ - local markdown = require("markdown") - local newline = [[^^J^^J]] - local convert, input - - convert = markdown.new({fencedCode = true}) - input = "A paragraph." .. newline .. - "```" .. newline .. - "A code fence." .. newline .. - "```" .. newline - tex.sprint(convert(input)) - - convert = markdown.new({ - fencedCode = true, blankBeforeCodeFence = true}) - input = "A paragraph." .. newline .. - "```" .. newline .. - "Not a code fence." .. newline .. - "```" .. newline - tex.sprint(convert(input)) } -\bye -``````` -Then, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -``````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> A paragraph. -> -> ``` -> A code fence. -> ``` -> -> A paragraph. ``` Not a code fence. ``` - -###### Lua CLI example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input lmfonts -\input optionfalse -\input optiontrue -\bye -``````` -Using a text editor, create a text document named `content.md` with the -following content: -```` md -A paragraph. -``` -A code fence? -``` -``````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua fencedCode=true -- content.md optionfalse.tex -texlua fencedCode=true blankBeforeCodeFence=true -- content.md optiontrue.tex -luatex document.tex -``````` -where `` 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\\texmf\scripts\markdown\markdown-cli.lua` on Windows -systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI -script file using [Kpathsea][]. - -A PDF document named `document.pdf` should be produced and contain the -following text: - -> A paragraph. -> -> ``` -> A code fence? -> ``` -> -> A paragraph. ``` A code fence? ``` - -###### Plain TeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -```` tex -\input markdown -\def\markdownOptionFencedCode{true} - -\markdownBegin -A paragraph. -``` -A code fence. -``` -\markdownEnd - -\def\markdownOptionBlankBeforeCodeFence{true} -\markdownBegin -A paragraph. -``` -Not a code fence. -``` -\markdownEnd - -\bye -```````` -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> A paragraph. -> -> ``` -> A code fence. -> ``` -> -> A paragraph. ``` Not a code fence. ``` - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -```` tex -\documentclass{article} -\usepackage[fencedCode]{markdown} -\begin{document} - -\begin{markdown} -A paragraph. -``` -A code fence. -``` -\end{markdown} - -\begin{markdown*}{blankBeforeCodeFence} -A paragraph. -``` -Not a code fence. -``` -\end{markdown*} - -\end{document} -```````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> A paragraph. -> -> ``` -> A code fence. -> ``` -> -> A paragraph. ``` Not a code fence. ``` - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -```` tex -\usemodule[t][markdown] -\def\markdownOptionFencedCode{true} -\starttext - -\startmarkdown -A paragraph. -``` -A code fence. -``` -\stopmarkdown - -\def\markdownOptionBlankBeforeCodeFence{true} -\startmarkdown -A paragraph. -``` -Not a code fence. -``` -\stopmarkdown - -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> A paragraph. -> -> ``` -> A code fence. -> ``` -> -> A paragraph. ``` Not a code fence. ``` - - -##### 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 {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -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 {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input lmfonts -\input optionfalse -\input optiontrue -\bye -``````` -Using a text editor, create a text document named `content.md` with the -following content: -``` md -A paragraph. -A heading? -========== -`````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua -- content.md optionfalse.tex -texlua blankBeforeHeading=true -- content.md optiontrue.tex -luatex document.tex -``````` -where `` 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\\texmf\scripts\markdown\markdown-cli.lua` on Windows -systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI -script file using [Kpathsea][]. - -A PDF document named `document.pdf` should be produced and contain the -following text: - -> A paragraph. -> -> A heading? -> ========== -> -> A paragraph. A heading? ========== - -###### Plain TeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> A paragraph. -> -> A heading. -> ========== -> -> A paragraph. Not a heading. ============== - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> A paragraph. -> -> A heading. -> ========== -> -> A paragraph. Not a heading. ============== - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\starttext - -\startmarkdown -A paragraph. -A heading. -========== -\stopmarkdown - -\def\markdownOptionBlankBeforeHeading{true} -\startmarkdown -A paragraph. -Not a heading. -============== -\stopmarkdown - -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -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. ============== - - -##### 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 {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -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 {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input lmfonts -\input optionfalse -\input optiontrue -\bye -``````` -Using a text editor, create a text document named `content.md` with the -following content: -``` md -> A single block quote - -> or two block quotes? -`````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua -- content.md optionfalse.tex -texlua breakableBlockquotes=true -- content.md optiontrue.tex -luatex document.tex -``````` -where `` 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\\texmf\scripts\markdown\markdown-cli.lua` on Windows -systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI -script file using [Kpathsea][]. - -A PDF document named `document.pdf` should be produced and contain the -following text: - -> > A single block quote or two block quotes? -> -> > A single block quote -> -> > or two block quotes? - -###### Plain TeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> > A single block quote. -> -> > A block quote. -> -> > Another block quote. - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> > A single block quote. -> -> > A block quote. -> -> > Another block quote. - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\starttext - -\startmarkdown -> A single - -> block quote. -\stopmarkdown - -\def\markdownOptionBreakableBlockquotes{true} -\startmarkdown -> A block quote. - -> Another block quote. -\stopmarkdown - -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -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. - - -##### Option `citationNbsps` - -`citationNbsps` (default value: `true`) - -: true - - : Replace regular spaces with non-breakable spaces inside the prenotes - and postnotes of citations produced via the pandoc citation syntax - extension. - - false - - : Do not replace regular spaces with non-breakable spaces inside the - prenotes and postnotes of citations produced via the pandoc citation - syntax extension. - - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.bib` with the -following content: -``` bib -@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: -``` tex -\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: -``` sh -lualatex document.tex -bibtex document.aux -lualatex document.tex -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text, where the middot (`·`) denotes a non-breakable space: - -> The TeXbook [1, p.·123·and·130] is good. -> -> The TeXbook [1, p. 123 and 130] is good. -> -> ### References -> [1] Donald·Ervin Knuth. _The TeXbook, volume A of Computers and typesetting._ -> Addison-Wesley, 1984. - - -##### Option `citations` - -`citations` (default value: `false`) - -: true - - : Enable the pandoc citation syntax extension: - - ``` md - Here is a simple parenthetical citation [@doe99] and here - is a string of several [see @doe99, pp. 33-35; also - @smith04, chap. 1]. - - A parenthetical citation can have a [prenote @doe99] and - a [@smith04 postnote]. The name of the author can be - suppressed by inserting a dash before the name of an - author as follows [-@smith04]. - - Here is a simple text citation @doe99 and here is - a string of several @doe99 [pp. 33-35; also @smith04, - chap. 1]. Here is one with the name of the author - suppressed -@doe99. - `````` - -: false - - : Disable the pandoc citation syntax extension. - - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.bib` with the -following content: -``` bib -@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: -``` tex -\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: -``` sh -lualatex document.tex -biber document.bcf -lualatex document.tex -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> The TeXbook [1, p.·123 and 130] was written by Knuth [1]. -> -> ### References -> [1] Donald Ervin Knuth. _The TeXbook, volume A of Computers and typesetting._ -> Addison-Wesley, 1984. - - -##### Option `codeSpans` - -`codeSpans` (default value: `true`) - -: true - - : Enable the code span syntax: - - ~~~ md - 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 {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -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 {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` md -``Is this a code span?'' ``Or a quote?'' -`````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua codeSpans=false -- content.md optionfalse.tex -texlua -- content.md optiontrue.tex -luatex document.tex -``````` -where `` 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\\texmf\scripts\markdown\markdown-cli.lua` on Windows -systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI -script file using [Kpathsea][]. - -A PDF document named `document.pdf` should be produced and contain the -following text: - -> “Is this a code span?” “Or a quote?” -> -> ``Is this a code span?'' ``Or a quote?'' - -###### Plain TeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> ``This is a code span.'' ``This is no longer a code span.'' -> -> “This is a quote.” “This is another quote.” - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> ``This is a code span.'' ``This is no longer a code span.'' -> -> “This is a quote.” “This is another quote.” - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\starttext - -\startmarkdown -``This is a code span.'' -``This is no longer a code span.'' -\stopmarkdown - -\def\markdownOptionCodeSpans{false} -\startmarkdown -``This is a quote.'' -``This is another quote.'' -\stopmarkdown - -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -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.” - - -##### Option `contentBlocks` - -`contentBlocks` (default value: `false`) - -: true - - : Enable the - iA Writer content blocks syntax extension: - - ``` md - http://example.com/minard.jpg (Napoleon's - disastrous Russian campaign of 1812) - /Flowchart.png "Engineering Flowchart" - /Savings Account.csv 'Recent Transactions' - /Example.swift - /Lorem Ipsum.txt - `````` - -: false - - : Disable the - iA Writer content blocks syntax extension. - - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `table.csv` with the -following content: -``` csv -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: -``` js -{ - "tex": "LaTeX" -} -`````` -Create also a text document named `code.tex` with the following content: -``` tex -This is an example code listing in \LaTeX. -``````` -Create also a text document named `part.md` with the following content: -``` md -This is a *transcluded markdown document*. -`````` -Create also a text document named `document.tex` with the following content: -``` tex -\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: -``` sh -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 -> -> ``` tex -> This is an example code listing in \LaTeX. -> ``````` -> -> This is a *transcluded markdown document*. - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `table.csv` with the -following content: -``` csv -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: -``` js -{ - "tex": "ConTeXt" -} -`````` -Create also a text document named `code.tex` with the following content: -``` tex -This is an example code listing in \ConTeXt. -``````` -Create also a text document named `part.md` with the following content: -``` md -This is a *transcluded markdown document*. -`````` -Create also a text document named `document.tex` with the following content: -``` tex -\usemodule[t][markdown] -\def\markdownOptionContentBlocks{true} -\definetyping [ConTeXt] -\setuptyping [ConTeXt] [option=TEX] -\starttext -\startmarkdown -/table.csv (An example table) -/code.tex (An example code listing) -/part.md (A file transclusion example) -\stopmarkdown -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -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 -> -> ``` tex -> This is an example code listing in \ConTeXt. -> ``````` -> -> This is a *transcluded markdown document*. - - -##### Option `contentBlocksLanguageMap` - -`contentBlocksLanguageMap` (default value: `"markdown-languages.json"`) - -: The filename of the JSON file that maps filename extensions to - programming language names in the iA Writer content blocks. - - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `table.csv` with the -following content: -``` csv -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: -``` js -{ - "tex": "LaTeX" -} -`````` -Create also a text document named `code.tex` with the following content: -``` tex -This is an example code listing in \LaTeX. -``````` -Create also a text document named `part.md` with the following content: -``` md -This is a *transcluded markdown document*. -`````` -Create also a text document named `document.tex` with the following content: -``` tex -\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: -``` sh -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 -> -> ``` tex -> This is an example code listing in \LaTeX. -> ``````` -> -> This is a *transcluded markdown document*. - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `table.csv` with the -following content: -``` csv -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: -``` js -{ - "tex": "ConTeXt" -} -`````` -Create also a text document named `code.tex` with the following content: -``` tex -This is an example code listing in \ConTeXt. -``````` -Create also a text document named `part.md` with the following content: -``` md -This is a *transcluded markdown document*. -`````` -Create also a text document named `document.tex` with the following content: -``` tex -\usemodule[t][markdown] -\def\markdownOptionContentBlocks{true} -\def\markdownOptionContentBlocksLanguageMap{language-map.json} -\definetyping [ConTeXt] -\setuptyping [ConTeXt] [option=TEX] -\starttext -\startmarkdown -/table.csv (An example table) -/code.tex (An example code listing) -/part.md (A file transclusion example) -\stopmarkdown -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -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 -> -> ``` tex -> This is an example code listing in \ConTeXt. -> ``````` -> -> This is a *transcluded markdown document*. - - -##### Option `definitionLists` - -`definitionLists` (default value: `false`) - -: true - - : Enable the pandoc definition list syntax extension: - - ``` md - Term 1 - - : Definition 1 - - Term 2 with *inline markup* - - : Definition 2 - - { some code, part of Definition 2 } - - Third paragraph of definition 2. - ````` - -: false - - : Disable the pandoc definition list syntax extension. - - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Term 1 -> -> : Definition 1 -> -> Term 2 with *inline markup* -> -> : Definition 2 -> -> { some code, part of Definition 2 } -> -> Third paragraph of definition 2. - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\def\markdownOptionDefinitionLists{true} -\starttext -\startmarkdown -Term 1 - -: Definition 1 - -Term 2 with *inline markup* - -: Definition 2 - - { some code, part of Definition 2 } - - Third paragraph of definition 2. -\stopmarkdown -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -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. - - -##### Option `fencedCode` - -`fencedCode` (default value: `false`) - -: true - - : Enable the commonmark fenced code block extension: - - ~~~~~~~~ md - ~~~ js - if (a > 3) { - moveShip(5 * gravity, DOWN); - } - ~~~~~~ - - ``` html -
    -            
    -              // Some comments
    -              line 1 of code
    -              line 2 of code
    -              line 3 of code
    -            
    -          
    - ``` - ~~~~~~~~~~~ - -: false - - : Disable the commonmark fenced code block extension. - - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage{minted} -\usepackage[fencedCode]{markdown} -\begin{document} -\begin{markdown} -~~~ js -if (a > 3) { - moveShip(5 * gravity, DOWN); -} -~~~~~~ - - ``` html -
    -    
    -      // Some comments
    -      line 1 of code
    -      line 2 of code
    -      line 3 of code
    -    
    -  
    - ``` -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex --shell-escape document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> ~~~ js -> if (a > 3) { -> moveShip(5 * gravity, DOWN); -> } -> ~~~~~~ -> -> ``` html ->
    ->   
    ->     // Some comments
    ->     line 1 of code
    ->     line 2 of code
    ->     line 3 of code
    ->   
    -> 
    -> ``` - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\def\markdownOptionFencedCode{true} -\definetyping [js] -\definetyping [html] -\setuptyping [html] [option=XML] -\starttext -\startmarkdown -~~~ js -if (a > 3) { - moveShip(5 * gravity, DOWN); -} -~~~~~~ - - ``` html -
    -    
    -      // Some comments
    -      line 1 of code
    -      line 2 of code
    -      line 3 of code
    -    
    -  
    - ``` -\stopmarkdown -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> ~~~ js -> if (a > 3) { -> moveShip(5 * gravity, DOWN); -> } -> ~~~~~~ -> -> ``` html ->
    ->   
    ->     // Some comments
    ->     line 1 of code
    ->     line 2 of code
    ->     line 3 of code
    ->   
    -> 
    -> ``` - - -##### Option `footnotes` - -`footnotes` (default value: `false`) - -: true - - : Enable the pandoc footnote syntax extension: - - ``` md - Here is a footnote reference,[^1] and another.[^longnote] - - [^1]: Here is the footnote. - - [^longnote]: Here's one with multiple blocks. - - Subsequent paragraphs are indented to show that they - belong to the previous footnote. - - { some.code } - - The whole paragraph can be indented, or just the - first line. In this way, multi-paragraph footnotes - work like multi-paragraph list items. - - This paragraph won't be part of the note, because it - isn't indented. - `````` - -: false - - : Disable the pandoc footnote syntax extension. - - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage[footnotes]{markdown} -\begin{document} -\begin{markdown} -Here is a footnote reference,[^1] and another.[^longnote] - -[^1]: Here is the footnote. - -[^longnote]: Here's one with multiple blocks. - - Subsequent paragraphs are indented to show that they -belong to the previous footnote. - - { some.code } - - The whole paragraph can be indented, or just the - first line. In this way, multi-paragraph footnotes - work like multi-paragraph list items. - -This paragraph won't be part of the note, because it -isn't indented. -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Here is a footnote reference,[^1] and another.[^longnote] -> -> [^1]: Here is the footnote. -> -> [^longnote]: Here's one with multiple blocks. -> -> Subsequent paragraphs are indented to show that they -> belong to the previous footnote. -> -> { some.code } -> -> The whole paragraph can be indented, or just the -> first line. In this way, multi-paragraph footnotes -> work like multi-paragraph list items. -> -> This paragraph won't be part of the note, because it -> isn't indented. - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\def\markdownOptionFootnotes{true} -\starttext -\startmarkdown -Here is a footnote reference,[^1] and another.[^longnote] - -[^1]: Here is the footnote. - -[^longnote]: Here's one with multiple blocks. - - Subsequent paragraphs are indented to show that they -belong to the previous footnote. - - { some.code } - - The whole paragraph can be indented, or just the - first line. In this way, multi-paragraph footnotes - work like multi-paragraph list items. - -This paragraph won't be part of the note, because it -isn't indented. -\stopmarkdown -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Here is a footnote reference,[^1] and another.[^longnote] -> -> [^1]: Here is the footnote. -> -> [^longnote]: Here's one with multiple blocks. -> -> Subsequent paragraphs are indented to show that they -> belong to the previous footnote. -> -> { some.code } -> -> The whole paragraph can be indented, or just the -> first line. In this way, multi-paragraph footnotes -> work like multi-paragraph list items. -> -> This paragraph won't be part of the note, because it -> isn't indented. - - -##### Option `hashEnumerators` - -`hashEnumerators` (default value: `false`) - -: true - - : Enable the use of hash symbols (`#`) as ordered item list - markers: - - ``` md - #. Bird - #. McHale - #. Parish - `````` - -: false - - : Disable the use of hash symbols (`#`) as ordered item list - markers. - - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> . Bird -> ======== -> . McHale -> ======== -> . Parish -> ======== -> -> #. Bird -> #. McHale -> #. Parish - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\starttext - -\startmarkdown -#. Bird -#. McHale -#. Parish -\stopmarkdown - -\def\markdownOptionHashEnumerators{true} -\startmarkdown -#. Bird -#. McHale -#. Parish -\stopmarkdown - -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> . Bird -> ======== -> . McHale -> ======== -> . Parish -> ======== -> -> #. Bird -> #. McHale -> #. Parish - - -##### Option `html` - -`html` (default value: `false`) - -: true - - : Enable the recognition of HTML tags, block elements, comments, HTML - instructions, and entities in the input. Tags, block elements (along - with contents), HTML instructions, and comments will be ignored and - HTML entities will be replaced with the corresponding Unicode - codepoints. - -: false - - : Disable the recognition of HTML markup. Any HTML markup in the input - will be rendered as plain text. - - -When the option is enabled, HTML entities are currently incorrectly parsed. -See [the corresponding issue][issue-38] in the package repository. - - [issue-36]: https://github.com/Witiko/markdown/issues/36 - (HTML entities with the `html` Lua option enabled produce a Lua - parser error) - -###### Lua module example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input lmfonts -\directlua{ - local markdown = require("markdown") - local convert = markdown.new() - local newline = [[^^J^^J]] - local input = - "
    *There is no block tag support.*
    " .. newline .. - "*There is no support.*" .. newline .. - "_There is no support._" .. newline .. - "_There is no support._" - tex.sprint(convert(input)) } -\par -\directlua{ - local markdown = require("markdown") - local convert = markdown.new({html = true}) - local input = - "
    *There is block tag support.*
    " .. newline .. - "*There is support.*" .. newline .. - "_There is support._" .. newline .. - "_There is support._" - tex.sprint(convert(input)) } -\bye -``````` -Then, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -``````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> \
    There is no block tag support.\
    -> There is no \\ support. -> There is no \ support. -> There is no support. -> -> There is support. There is support. There is support. - -###### Lua CLI example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` html -
    -*Is there block tag support?* -
    -*Is there support?* -_Is there support?_ -_Is there support?_ -```````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua -- content.md optionfalse.tex -texlua html=true -- content.md optiontrue.tex -luatex document.tex -``````` -where `` 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\\texmf\scripts\markdown\markdown-cli.lua` on Windows -systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI -script file using [Kpathsea][]. - -A PDF document named `document.pdf` should be produced and contain the -following text: - -> \
    Is there block tag support?\
    -> Is there \\ support? -> Is there \ support? -> Is there support? -> -> Is there support? Is there support? Is there support? - -###### Plain TeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input lmfonts - -\markdownBegin -
    -*There is no block tag support.* -
    -*There is no support.* -_There is no support._ -_There is no support._ -\markdownEnd - -\def\markdownOptionHtml{true} -\markdownBegin -
    -*There is block tag support.* -
    -*There is support.* -_There is support._ -_There is support._ -\markdownEnd - -\bye -``````` -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> \
    There is no block tag support.\
    -> There is no \\ support. -> There is no \ support. -> There is no support. -> -> There is support. There is support. There is support. - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage{markdown} -\begin{document} - -\begin{markdown} -
    -*There is no block tag support.* -
    -*There is no support.* -_There is no support._ -_There is no support._ -\end{markdown} - -\begin{markdown*}{html} -
    -*There is block tag support.* -
    -*There is support.* -_There is support._ -_There is support._ -\end{markdown*} - -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> \
    There is no block tag support.\
    -> There is no \\ support. -> There is no \ support. -> There is no support. -> -> There is support. There is support. There is support. - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\starttext - -\startmarkdown -
    -*There is no block tag support.* -
    -*There is no support.* -_There is no support._ -_There is no support._ -\stopmarkdown - -\def\markdownOptionHtml{true} -\startmarkdown -
    -*There is block tag support.* -
    -*There is support.* -_There is support._ -_There is support._ -\stopmarkdown - -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> \
    There is no block tag support.\
    -> There is no \\ support. -> There is no \ support. -> There is no support. -> -> There is support. There is support. There is support. - - -##### 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 {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input lmfonts -\directlua{ - local markdown = require("markdown") - local convert_safe = markdown.new() - local convert_unsafe = markdown.new({hybrid = true}) - local input = [[$\noexpand\sqrt{-1}$ *equals* $i$.]] - tex.sprint(convert_safe(input) .. " " .. convert_unsafe(input)) } -\bye -``````` -Then, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -``````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> \$\\sqrt {-1}\$ *equals* \$i\$. -> √-̅1̅ *equals* $i$. - -###### Lua CLI example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input lmfonts -\input optionfalse -\input optiontrue -\bye -``````` -Using a text editor, create a text document named `content.md` with the -following content: -``` md -$\sqrt{-1}$ *equals* $i$. -`````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua -- content.md optionfalse.tex -texlua hybrid=true -- content.md optiontrue.tex -luatex document.tex -``````` -where `` 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\\texmf\scripts\markdown\markdown-cli.lua` on Windows -systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI -script file using [Kpathsea][]. - -A PDF document named `document.pdf` should be produced and contain the -following text: - -> \$\\sqrt {-1}\$ *equals* \$i\$. -> √-̅1̅ *equals* $i$. - -###### Plain TeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> \$\\sqrt {-1}\$ *equals* \$i\$. -> √-̅1̅ *equals* $i$. - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\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: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> \$\\sqrt {-1}\$ *equals* \$i\$. -> √-̅1̅ *equals* $i$. - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\starttext -\startmarkdown -$\sqrt{-1}$ *equals* $i$. -\stopmarkdown -\def\markdownOptionHybrid{true} -\startmarkdown -$\sqrt{-1}$ *equals* $i$. -\stopmarkdown -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> \$\\sqrt {-1}\$ *equals* \$i\$. -> √-̅1̅ *equals* $i$. - - -##### Option `inlineFootnotes` - -`inlineFootnotes` (default value: `false`) - -: true - - : Enable the pandoc inline footnote syntax extension: - - ``` md - Here is an inline note.^[Inlines notes are easier to - write, since you don't have to pick an identifier and - move down to type the note.] - `````` - -: false - - : Disable the pandoc inline footnote syntax extension. - - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage[footnotes, inlineFootnotes]{markdown} -\begin{document} -\begin{markdown} -Here is an inline note.^[Inlines notes are easier to -write, since you don't have to pick an identifier and -move down to type the note.] -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> 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.] - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\def\markdownOptionFootnotes{true} -\def\markdownOptionInlineFootnotes{true} -\starttext -\startmarkdown -Here is an inline note.^[Inlines notes are easier to -write, since you don't have to pick an identifier and -move down to type the note.] -\stopmarkdown -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> 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.] - - -##### Option `preserveTabs` - -`preserveTabs` (default value: `false`) - -: true - - : Preserve all tabs in the input. - -: false - - : Convert any tabs in the input to spaces. - - -This option is currently non-functional. See [the corresponding -issue][issue-38] in the package repository. - - [issue-38]: https://github.com/Witiko/markdown/issues/38 - (Tabs are stripped even with the `preserveTabs=true` - Lua option enabled) - - -##### Option `smartEllipses` - -`smartEllipses` (default value: `false`) - -: true - - : Convert any ellipses in the input to the - `\markdownRendererEllipsis` TeX macro. - -: false - - : Preserve all ellipses in the input. - - -###### Lua module example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\def\markdownRendererEllipsis{. . .} -\input lmfonts -\directlua{ - local markdown = require("markdown") - local convert = markdown.new() - input = "These are just three regular dots ..." - tex.sprint(convert(input)) } -\par -\directlua{ - local markdown = require("markdown") - local convert = markdown.new({smartEllipses = true}) - input = "... and this is a victorian ellipsis." - tex.sprint(convert(input)) } -\bye -``````` -Then, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -``````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> These are just three regular dots ... -> -> . . . and this is a victorian ellipsis. - -###### Lua CLI example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\def\markdownRendererEllipsis{. . .} -\input lmfonts -\input optionfalse -\par -\input optiontrue -\bye -``````` -Using a text editor, create a text document named `content.md` with the -following content: -``` md -Are these just three regular dots, a victorian ellipsis, or ... ? -`````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua -- content.md optionfalse.tex -texlua smartEllipses=true -- content.md optiontrue.tex -luatex document.tex -``````` -where `` 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\\texmf\scripts\markdown\markdown-cli.lua` on Windows -systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI -script file using [Kpathsea][]. - -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Are these just three regular dots, a victorian ellipsis, or ... ? -> -> Are these just three regular dots, a victorian ellipsis, or . . . ? - -###### Plain TeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\def\markdownRendererEllipsis{. . .} - -\markdownBegin -These are just three regular dots ... -\markdownEnd - -\def\markdownOptionSmartEllipses{true} -\markdownBegin -... and this is a victorian ellipsis. -\markdownEnd - -\bye -``````` -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> These are just three regular dots ... -> -> . . . and this is a victorian ellipsis. - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage{markdown} -\markdownSetup{ - renderers = { - ellipsis = {. . .} }} -\begin{document} - -\begin{markdown} -These are just three regular dots ... -\end{markdown} - -\begin{markdown*}{smartEllipses} -... and this is a victorian ellipsis. -\end{markdown*} - -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> These are just three regular dots ... -> -> . . . and this is a victorian ellipsis. - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\def\markdownRendererEllipsis{. . .} -\starttext - -\startmarkdown -These are just three regular dots ... -\stopmarkdown - -\def\markdownOptionSmartEllipses{true} -\startmarkdown -... and this is a victorian ellipsis. -\stopmarkdown - -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> These are just three regular dots ... -> -> . . . and this is a victorian ellipsis. - - -##### Option `startNumber` - -`startNumber` (default value: `true`) - -: true - - : Make the number in the first item of an ordered lists significant. The - item numbers will be passed to the - `\markdownRendererOlItemWithNumber` TeX macro. - -: false - - : Ignore the numbers in the ordered list items. Each item will only - produce a - `\markdownRendererOlItem` TeX macro. - - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage{markdown} -\begin{document} - -\begin{markdown} -The following list respects the numbers specified in the markup: - -3. third item -4. fourth item -5. fifth item -\end{markdown} - -\begin{markdown*}{startNumber=false} -The following list does not respect the numbers specified in the -markup: - -3. third item -4. fourth item -5. fifth item -\end{markdown*} - -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> The following list respects the numbers specified in the markup: -> -> 3. third item -> 4. fourth item -> 5. fifth item -> -> The following list does not respect the numbers specified in the markup: -> -> 1. third item -> 2. fourth item -> 3. fifth item - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\starttext - -\startmarkdown -The following list respects the numbers specified in the markup: - -3. third item -4. fourth item -5. fifth item -\stopmarkdown - -\def\markdownOptionStartNumber{false} -\startmarkdown -The following list respects the numbers specified in the markup: - -3. third item -4. fourth item -5. fifth item -\stopmarkdown -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> The following list respects the numbers specified in the markup: -> -> 3. third item -> 4. fourth item -> 5. fifth item -> -> The following list does not respect the numbers specified in the markup: -> -> 1. third item -> 2. fourth item -> 3. fifth item - - -##### Option `tightLists` - -`tightLists` (default value: `true`) - -: true - - : Lists whose bullets do not consist of multiple paragraphs will be - passed to the - `\markdownRendererOlBeginTight`, `\markdownRendererOlEndTight`, - `\markdownRendererUlBeginTight`, `\markdownRendererUlEndTight`, - `\markdownRendererDlBeginTight`, and - `\markdownRendererDlEndTight` TeX macros. - -: false - - : Lists whose bullets do not consist of multiple paragraphs will be - treated the same way as lists that do consist of multiple paragraphs. - - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage{markdown} -\begin{document} - -\begin{markdown} -The following list is tight: - - - first item - - second item - - third item - -The following list is loose: - - - first item - - second item that spans - - multiple paragraphs - - third item -\end{markdown} - -\begin{markdown*}{tightLists=false} -The following list is now also loose: - - - first item - - second item - - third item -\end{markdown*} - -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> The following list is tight: -> -> - first item -> - second item -> - third item -> -> The following list is loose: -> -> - first item -> - second item that spans -> -> multiple paragraphs -> - third item -> -> The following list is now also loose: -> -> - first item -> -> - second item -> -> - third item - - -##### Option `underscores` - -`underscores` (default value: `true`) - -: true - - : Both underscores and asterisks can be used to denote emphasis and - strong emphasis: - - ``` md - *single asterisks* - _single underscores_ - **double asterisks** - __double underscores__ - `````` - -: false - - : Only asterisks can be used to denote emphasis and strong emphasis. - This makes it easy to write math with the \Opt{hybrid} option - without the need to constantly escape subscripts. - - -###### Plain TeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\def\markdownOptionHybrid{true} - -\markdownBegin -This is _emphasized text_ and this is a math subscript: $m\_n$. -\markdownEnd - -\def\markdownOptionUnderscores{false} -\markdownBegin -This is *emphasized text* and this is a math subscript: $m_n$. -\markdownEnd - -\bye -``````` -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> This is _emphasized text_ and this is a math subscript: *mₙ*. -> -> This is _emphasized text_ and this is a math subscript: *mₙ*. - -###### LaTeX example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage[hybrid]{markdown} -\begin{document} - -\begin{markdown} -This is _emphasized text_ and this is a math subscript: $m\_n$. -\end{markdown} - -\begin{markdown*}{underscores=false} -This is *emphasized text* and this is a math subscript: $m_n$. -\end{markdown*} - -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> This is _emphasized text_ and this is a math subscript: *mₙ*. -> -> This is _emphasized text_ and this is a math subscript: *mₙ*. - -###### ConTeXt example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\def\markdownOptionHybrid{true} -\starttext - -\startmarkdown -This is _emphasized text_ and this is a math subscript: $m\_n$. -\stopmarkdown - -\def\markdownOptionUnderscores{false} -\startmarkdown -This is *emphasized text* and this is a math subscript: $m_n$. -\stopmarkdown - -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> This is _emphasized text_ and this is a math subscript: *mₙ*. -> -> This is _emphasized text_ and this is a math subscript: *mₙ*. - - -Plain TeX ---------- - -The plain TeX macro package provides TeX commands for typesetting markdown -documents that invoke the Lua parser in the background. Beside TeX commands -that correspond to the Lua options, the macro package also provides commands -corresponding to additional plain TeX-specific options, and so-called *token -renderer* commands that define how the individual markdown elements will be -typeset. - -### Interfaces - - - - -### Options - - - - -### Token renderers - - - - -LaTeX ------ - -The LaTeX macro package provides additional syntactic sugar on top of the plain -TeX macro package and provides sane default definitions of the token renderers. - - - -### Interfaces - - - - -### Options - - - - -### Token renderers - - - - -ConTeXt -------- - -The ConTeXt macro package provides additional syntactic sugar on top of the -plain TeX macro package and provides sane default definitions of the token -renderers. - -### Interfaces - - - -### Options - - - -### Token renderers + [techdoc]: http://mirrors.ctan.org/macros/generic/markdown/markdown.pdf + (A Markdown Interpreter for \TeX{}) - +/markdown-interfaces.md +/markdown-options.md +/markdown-tokens.md diff --git a/Master/texmf-dist/doc/generic/markdown/markdown.pdf b/Master/texmf-dist/doc/generic/markdown/markdown.pdf index 567f99aed14..b445d4cc577 100644 Binary files a/Master/texmf-dist/doc/generic/markdown/markdown.pdf and b/Master/texmf-dist/doc/generic/markdown/markdown.pdf differ -- cgit v1.2.3