CTAN Comprehensive TeX Archive Network

Directory macros/generic/markdown

README.md

Markdown

license ci release docker-witiko/markdown matrix discord chatgpt

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

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 MK tool from our official Docker image on document.tex:

docker run --rm -v "$PWD"/workdir:/workdir -w /workdir witiko/markdown \
  latexmk -pdf -shell-escape -silent document.tex

Alternatively, you can install Live (can take up to several hours) and use its MK tool:

latexmk -cd -pdf -shell-escape -silent workdir/document.tex

A PDF document named workdir/document.pdf should be produced and contain the following output:banner

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
        permissions:
          contents: write
        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 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 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:

  1. 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 engine, such as Lua (luatex markdown.ins). The manual will reside in the file markdown.md and the CSS stylesheet markdown.css.
  2. The technical documentation for either the released version or the latest development version, which can be typeset by running the MK tool on the markdown.dtx file (latexmkmarkdown.dtx) after [installing the Markdown package][install].MK should be included in your distribution. The typeset documentation will reside in the file markdown.pdf.
  3. Tutorials and example documents by Lian Tze Lim at Overleaf:
  4. Journal articles published by TUGboat:
  5. Journal articles published by CSTUG Bulletin (in Czech and Slovak):
  6. Talks:
  7. Theses:

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.
Fixes for issues

359

and

368

were graciously sponsored by the International Software Testing Qualifications Board (ISTQB).

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 engine, such Lua (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 package.

Running the MK 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 comments and marked up using the ltxdockit document class. Support for typesetting the documentation is provided by the doc 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 byMakefile 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 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 file that is included in your distribution like this:

\cite{Novotny:2017:UMI}
\bibliography{tugboat}

Download the contents of this package in one zip archive (1.4M).

markdown – Converting and rendering markdown documents inside

The package provides facilities for the conversion of markdown markup to plain . These are provided both in form of a Lua module and in form of plain , , and Cont macro packages that enable the direct inclusion of markdown documents inside documents.

Packagemarkdown
Bug trackerhttps://github.com/Witiko/markdown/issues
Announcementshttps://github.com/Witiko/markdown/releases
Repositoryhttps://github.com/Witiko/markdown
Developershttps://github.com/Witiko/markdown/pulls
Version3.4.2-0-ga45cf0ed 2024-03-09
LicensesThe Project Public License 1.3c
Copyright2009–2016 John MacFarlane, Hans Hagen
2016–2024 Vít Starý Novotný
MaintainerVít Starý Novotný
TDS archivemarkdown.tds.zip
Contained inTeX Live as markdown
MiKTeX as markdown
TopicsMarkup
...
Guest Book Sitemap Contact Contact Author