Luatex Extensions: Adding Markdown-Style Formatting Without Compromising Latex Structure
LaTeX is a powerful document preparation system that enables high-quality typesetting, but writing in its markup language can have a steep learning curve. Markdown offers a simpler and more intuitive syntax for formatting text documents. LuaTeX, the scriptable successor to pdfTeX, allows the straightforward integration of Markdown into LaTeX through Lua modules that translate the Markdown syntax. With these LuaTeX extensions, authors can write documents using easy Markdown formatting, while still producing output consistent with LaTeX structure and style conventions.
Why Use Markdown in LaTeX?
Mixing Markdown and LaTeX combines the readability of Markdown with the typographical capabilities of LaTeX:
- Markdown offers an easy-to-write and easy-to-read syntax that facilitates writing at the speed of thought.
- LaTeX provides professional-quality typography with consistent, beautiful formatting configurable through document classes and packages.
- Using Markdown syntax removes the need to interrupt writing to mark up text, improving author productivity.
- LaTeX handles auto-numbering of sections, figures, tables, equations, and citations, reducing clerical work for the author.
- Markdown in LaTeX provides the best of both worlds—simple text writing with powerful formatting.
Loading LuaTeX Extensions
LuaTeX extends TeX with an embedded scripting language called Lua, enabling new possibilities through scriptable extensions. Several Lua packages translate Markdown syntax into LaTeX markup on the fly:
- Pandoc Lua filters—Pandoc converts Markdown documents into LaTeX, HTML, Docx and many other formats. Its Lua filters parse Markdown and emit LaTeX from within LuaTeX.
- Markdown—A Lua package by V. Verfaille that provides core Markdown functionality for emphasis, lists, links and images in LuaLaTeX.
- Marked—Another Markdown parser in Lua with extensions for footnotes, tables and math by D. Muhl. Compatible with both LuaLaTeX and LuaTeX.
To enable Markdown with Pandoc filters in a LuaLaTeX document:
\documentclass{article}
\usepackage{pandocfilters}
\EnableLuaFilters
For the Markdown Lua package, use:
\documentclass{article}
\usepackage{markdown}
Then Markdown can be written inside the LuaLaTeX or LuaTeX file alongside traditional LaTeX markup.
Basic Markdown Syntax
Markdown uses simple, intuitive text-based formats for common document elements:
Headings
Headings use the number sign #
:
# Heading 1
## Heading 2
### Heading 3
In LaTeX output, Heading 1 and 2 are translated into LaTeX sectioning commands:
\section{Heading 1}
\subsection{Heading 2}
Emphasis
Text can be italicized using asterisks *
or underscores _
:
_italicized_ or *italicized*
Bold using double asterisks or underscores:
__bold__ or **bold**
And strikethrough uses tildes ~~
:
~~strikethrough~~
Lists
Numbered lists use numbers followed by periods. Nested items use indentation:
1. Item 1
1. Nested item 1
2. Nested item 2
2. Item 2
Bulleted lists use asterisks, pluses or hyphens as bullet characters, also with indentation:
* Bullet 1
- Nested bullet 1
- Nested bullet 2
+ Bullet 2
Links
Hyperlinks use square brackets for text, parentheses for URLs:
[Text of link](https://example.com)
Optionally, add a title in quotes after the URL:
[Text](https://example.com "Optional title")
Images
Same syntax as links, but preceding with an exclamation point !
:
![Alt text of image](path/to/image.jpg "Optional title")
Markdown Environments
Special Markdown environments enable writing Markdown content while in LaTeX modes:
- markdown—Renders Markdown text as a LaTeX paragraph.
- markdownsection—Renders a Markdown heading and following paragraph as a LaTeX section.
- markdownsubsection—Like above, but renders as a LaTeX subsection.
For example:
\begin{markdownsection}
# Heading
Paragraph text.
\end{markdownsection}
This provides finer control over Markdown content than just enabling it globally.
Markdown Inside LaTeX Environments
LaTeX environments like figure
, table
, itemize
and others can contain Markdown text without additional markup. For example:
\begin{figure}
![Caption with **bold** text](fig1.png)
\end{figure}
The caption text will be parsed as Markdown but remain inside the LaTeX float environment.
Customizing Markdown
Custom Markdown extensions can be added through Lua filters to extend the base syntax:
- Embed raw LaTeX commands or environments.
- Add Citations—parse citation keys like
@smith2022
. - Include source code listings with highlighting.
- Translate Markdown tables into LaTeX tabular environments.
- Add Tikz and PGF graphics integration.
For example, define custom fenced code blocks with a Lua filter:
~~~ {#mycode .python .numberLines startFrom="10"}
import numpy as np
x = np.random.randn(10)
print (x)
~~~
Then write a filter to substitute into a LaTeX lstlisting
environment.
Example Document Structure
A sample LaTeX document using Markdown might have this structure:
\documentclass{article}
\title{Sample Markdown Article}
\author{Author Name}
\usepackage{markdown}
\EnableLuaFilters
\begin{document}
\maketitle
\begin{abstract}
Abstract summary in Markdown or LaTeX.
\end{abstract}
\section{Introduction}
Introductory section content written in Markdown!
Easily include **formatting**, _emphasis_, lists, [links](https://example.com), and images:
![alt text](fig1.png)
\section{Methods}
Methods section content in \LaTeX{} or _Markdown_.
\begin{table}
| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Cell 1 | Cell 2 | Cell 3 |
\end{table}
\section{Results}
## Section Heading
Markdown text discussing the wonderful results.
\begin{figure}
![Caption bold text](fig2.png)
\end{figure}
\section{Discussion}
Discussion of amazing discovery all in Markdown!
\section{Conclusion}
Markdown is great for stream-of-consciousness writing combined with \LaTeX!
\end{document}
Additional Extensions
Beyond core Markdown functionality, some added extensions are useful:
- Multimarkdown extensions like footnotes, tables and metadata support.
- R Markdown for embedding R code chunks and outputs.
- Bookdown and Blogdown output Markdown into LaTeX/PDF books and websites.
- Manubot integrates Markdown, Pandoc, Git and continuous publication workflows.
These further extend authoring Markdown content while harnessing LaTeX documents.