Verzeichnis macros/generic/markdown
Markdown
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 does not require any external programs, and makes it easy to redefine how each and every markdown element is rendered. Creative abuse of the markdown syntax is encouraged. 😉
Your first Markdown document
Using a text editor, create an empty directory named workdir/
. In it, create a text document named workdir/document.tex
with the following content:
\documentclass{book} \usepackage{markdown} \markdownSetup{pipeTables,tableCaptions} \begin{document} \begin{markdown} Introduction ============ ## Section ### Subsection Hello *Markdown*! | Right | Left | Default | Center | |------:|:-----|---------|:------:| | 12 | 12 | 12 | 12 | | 123 | 123 | 123 | 123 | | 1 | 1 | 1 | 1 | : Table \end{markdown} \end{document}
Next, run the LaTeXMK tool from our official Docker image on document.tex
:
docker run --rm -v "$PWD"/workdir:/workdir -w /workdir witiko/markdown \ latexmk -lualatex -silent document.tex
Alternatively, you can install TeX Live (can take up to several hours) and use its LaTeXMK tool:
latexmk -cd -lualatex -silent workdir/document.tex
A PDF document named workdir/document.pdf
should be produced and contain the following output:
Congratulations, you have just typeset your first Markdown document! 🥳
Use Markdown for continuous integration
Can't live without the latest features of the Markdown package in your continuous integration pipelines? It's ok, you can use our official Docker image as a drop-in replacement for the texlive/texlive:latest
Docker image! The following example shows a GitHub Actions pipeline, which will automatically typeset and prerelease a PDF document:
name: Typeset and prerelease the book on: push: jobs: typeset: runs-on: ubuntu-latest container: image: witiko/markdown:latest steps: - uses: actions/checkout@v2 - run: latexmk -lualatex document.tex - uses: marvinpinto/action-automatic-releases@latest with: title: The latest typeset book automatic_release_tag: latest prerelease: true repo_token: ${{ secrets.GITHUB_TOKEN }} files: document.pdf
In fact, this is how we automatically produce the latest documentation for the Markdown package.
Peek under the hood
Remember how we said that the Markdown package converts markdown markup to TeX commands? Let's see what that means and what we can do with this knowledge.
Using a text editor, create an empty text document named document.md
with the following markdown content:
Hello *Markdown*! $a_x + b_x = c_x$
Next, run the Lua command-line interface (CLI) from our official Docker image on document.md
:
docker run --rm -i witiko/markdown markdown-cli hybrid=true < document.md
We will receive the following output, where the markdown markup has been replaced by TeX commands:
\markdownDocumentBegin Hello \markdownRendererEmphasis{Markdown}! $a\markdownRendererEmphasis{x + b}x = c_x$ \markdownDocumentEnd
We can see right away that the Markdown package has incorrectly interpreted _x + b_
as an emphasized text. We can fix this by passing in the underscores=false
option:
docker run --rm -i witiko/markdown markdown-cli hybrid=true underscores=false < document.md
\markdownDocumentBegin Hello \markdownRendererEmphasis{Markdown}! $a_x + b_x = c_x$ \markdownDocumentEnd
Much better! If the Markdown package ever surprises you, use the Lua CLI to peek under the hood and inspect the results of the conversion.
Further information
For further information, consult one of the following:
- The user manual for either the released version or the latest development version, which can be produced by interpreting the
markdown.ins
file using a Unicode-aware TeX engine, such as LuaTeX (luatex markdown.ins
). The manual will reside in the filemarkdown.md
and the CSS stylesheetmarkdown.css
. - The technical documentation for either the released version or the latest development version, which can be typeset by running the LaTeXMK tool on the
markdown.dtx
file (latexmk
markdown.dtx) after [installing the Markdown package][install].
LaTeXMK should be included in your TeX distribution. The typeset documentation will reside in the filemarkdown.pdf
. - Tutorials and example documents by Lian Tze Lim at Overleaf:
- My journal articles published by TUGboat:
- Using Markdown inside TeX documents,
- Markdown 2.7.0: Towards lightweight markup in TeX,
- Making Markdown into a Microwave Meal,
- Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX,
- Markdown 2.15.0: What's New?,
- Markdown 2.17.1: What's New, What's Next?, and
- Attributes in Markdown.
- Journal articles of me and my students published by CSTUG Bulletin (in Czech and Slovak):
- Talks by me and my students:
- Theses by my students:
Acknowledgements
Logo | Acknowledgement |
---|---|
I gratefully acknowledge the funding from the Faculty of Informatics at the Masaryk University in Brno, Czech Republic, for the development of the Markdown package in projects MUNI/33/12/2015, MUNI/33/1784/2020, MUNI/33/0776/2021, MUNI/33/1654/2022, and MUNI/33/1658/2022. | |
Extensive user documentation for the Markdown package was kindly written by Lian Tze Lim and published by Overleaf. | |
Support for content slicing (Lua options shiftHeadings and slice ) and pipe tables (Lua options pipeTables and tableCaptions ) was graciously sponsored by David Vins and Omedym. |
Contributing to the Development of Markdown
Apart from the example markdown documents, tests, and continuous integration, which are placed in the examples/
, tests/
, and .github/
directories, the complete source code and documentation of the package are placed in the markdown.dtx
document following the literate programming paradigm. Some useful commands, such as building the release archives and typesetting the documentation, are placed in the Makefile
file for ease of maintenance.
When the file markdown.ins
is interpreted using a Unicode-aware TeX engine, such LuaTeX (luatex markdown.ins
), several files are produced from the markdown.dtx
document. The make base
command is provided by Makefile
for convenience. In markdown.dtx
, the boundaries between the produced files are marked up using an XML-like syntax provided by the l3docstrip plain TeX package.
Running the LaTeXMK tool on the markdown.dtx
file (latexmk markdown.dtx
) after the Markdown package has been installed typesets the documentation. The make markdown.pdf
command is provided by Makefile
for convenience. In markdown.dtx
, the documentation is placed inside TeX comments and marked up using the ltxdockit LaTeX document class. Support for typesetting the documentation is provided by the doc LaTeX package.
To facilitate continuous integration and sharing of the Markdown package, there exists an official Docker image, which can be reproduced by running the docker build
command on Dockerfile
(docker build
-t witiko/markdown .). The
make docker-image command is provided by
Makefile
for convenience.
Contributed Software
Links to contributed third-party software for the Markdown package are available in the contributions/
directory. The intention is to show interesting tools for the Markdown package and to give them wider exposure without taking responsibility for their development or maintenance.
Citing Markdown
When citing Markdown in academic papers and theses, please use the following BibTeX entry:
@article{novotny2017markdown, author = {V\'{i}t Novotn\'{y}}, year = {2017}, title = {Using {M}arkdown Inside {\TeX} Documents}, journal = {TUGboat}, volume = {38}, number = {2}, pages = {214--217}, issn = {0896-3207}, url = {https://tug.org/TUGboat/tb38-2/tb119novotny.pdf}, urldate = {2020-07-31}, }
Alternatively, you can use the Novotny:2017:UMI
key from the tugboat.bib
BibTeX file that is included in your TeX distribution like this:
\cite{Novotny:2017:UMI} \bibliography{tugboat}
Herunterladen des vollständigen Inhalts dieses Pakets in einem Zip-Archiv (1.3M).
markdown – Converting and rendering markdown documents inside TeX
The package provides facilities for the conversion of markdown markup to plain TeX. These are provided both in form of a Lua module and in form of plain TeX, LaTeX, and ConTeXt macro packages that enable the direct inclusion of markdown documents inside TeX documents.
Architecturally, the package consists of the Lunamark Lua module by John MacFarlane, which was slimmed down and rewritten for the needs of the package. Lunamark provides speedy markdown parsing for the rest of the package. On top of Lunamark sits code for the plain TeX, LaTeX, and ConTeXt formats by Vít Novotný.
Paket | markdown |
Fehlermeldungen | https://github.com/Witiko/markdown/issues |
Ankündigungen | https://github.com/Witiko/markdown/releases |
Repository | https://github.com/Witiko/markdown |
Entwickler | https://github.com/Witiko/markdown/pulls |
Version | 2.23.0-0-g0b22f91 2023-04-27 |
Lizenzen | The LaTeX Project Public License 1.3c |
Copyright | 2009–2016 John MacFarlane, Hans Hagen 2016–2023 Vít Novotný |
Betreuer | Vít Novotný |
TDS-Archiv | markdown.tds.zip |
Enthalten in | TeX Live als markdown MiKTeX als markdown |
Themen | Markup |