TomaT3/markdown

:notebook_with_decorative_cover: A package for converting and rendering markdown documents in TeX

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

Further information

For further information, consult one of the following:

1. The user manual, which can be produced by interpreting the markdown.ins file using a Unicode-aware TeX engine, such as XeTeX (xetex markdown.ins) or LuaTeX (luatex markdown.ins). The manual will reside in the file markdown.md and the CSS stylesheet markdown.css.
2. The technical documentation, which can be typeset by running the LaTeXMK tool on the markdown.dtx file (latexmk markdown.dtx) after installing the Markdown package. LaTeXMK should be included in your TeX distribution. The typeset documentation will reside in the file markdown.pdf.
3. Tutorials and example documents by Lian Tze Lim at Overleaf:
   • How to write in Markdown on Overleaf,
   • Markdown into LaTeX with Style,
   • Writing Markdown in LaTeX Documents,
   • Writing Beamer Slides with Markdown,
   • Writing Posters with Markdown, and
   • Using Markdown in LaTeX documents.
4. My journal articles published by TUGboat:
   • Using Markdown inside TeX documents, and
   • Markdown 2.7.0: Towards lightweight markup in TeX.
5. My journal articles published by CSTUG (in Czech):
   • Rendering Markdown inside TeX Documents, and
   • Markdown 2.8.1: Boldly Unto the Throne of Lightweight Markup in TeX.

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

Apart from the example markdown documents, tests, and continuous integration, which are placed in the examples/, tests/, and .circleci/ 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 as XeTeX (xetex markdown.ins) or LuaTeX (luatex markdown.ins), several files are produced from the markdown.dtx document. In markdown.dtx, the boundaries between the produced files are marked up using an XML-like syntax provided by the DocStrip 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. 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.

Citing Markdown

When citing Markdown in academic papers and theses, please use the following BibTeX entry:

@article{novotny17markdown,
  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},
}