https://github.com/Witiko/markdown Skip to content Sign up * Why GitHub? + Features + Mobile + Actions + Codespaces + Packages + Security + Code review + Issues + Integrations + GitHub Sponsors + Customer stories * Team * Enterprise * Explore + Explore GitHub + Learn and contribute + Topics + Collections + Trending + Learning Lab + Open source guides + Connect with others + The ReadME Project + Events + Community forum + GitHub Education + GitHub Stars program * Marketplace * Pricing + Plans + Compare plans + Contact Sales + Education [ ] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this user All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} Witiko / markdown Public forked from jgm/lunamark * Notifications * Fork 49 * Star 199 * A package for converting and rendering markdown documents in TeX ctan.org/pkg/markdown LPPL-1.3c License 199 stars 49 forks Star Notifications * Code * Issues 25 * Pull requests 0 * Discussions * Actions * Projects 0 * Wiki * Security * Insights More * Code * Issues * Pull requests * Discussions * Actions * Projects * Wiki * Security * Insights main Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags 4 branches 32 tags Code This branch is up to date with main. Contribute * This branch is not ahead of the upstream main. No new commits yet. Enjoy your day! * Open pull request Latest commit @Witiko Witiko Add missing contentBlocks option to example in user manual ... 9a1be7a Jan 6, 2022 Add missing `contentBlocks` option to example in user manual 9a1be7a Git stats * 1,538 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .github/workflows Add markdown document renderers to unit tests Jan 6, 2022 examples Fix non-compact lists in the examples Dec 27, 2021 libraries Remove a workaround for api7/lua-tinyyaml#10 Sep 12, 2021 tests Add markdown document renderers to unit tests Jan 6, 2022 .gitignore Add example LaTeX themes to .gitignore Apr 9, 2021 .gitmodules Replace peposso/lua-tinyyaml with api7/lua-tinyyaml Sep 7, 2021 .markdownlint.yaml Fix errors reported by MarkdownLint Aug 26, 2021 Dockerfile Stop using the latest-with-cache TeX Live Docker image tag Dec 30, 2021 LICENSE Sublicense the code as LPPL v1.3c Jul 1, 2021 Makefile Only push the latest Docker image once Jan 5, 2022 README.md Add markdown document renderers Jan 6, 2022 docstrip.cfg Prepare the package for the 2.10.0 release Aug 6, 2021 latexmkrc Add index to the documentation Aug 26, 2021 markdown.dtx Add missing contentBlocks option to example in user manual Jan 6, 2022 markdown.ins Finish the default LaTeX3 jekyllData renderer prototypes Sep 10, 2021 markdown.ist Add index to the documentation Aug 26, 2021 markdown.png Move banner.png to markdown.png Sep 2, 2021 View code [ ] Markdown Your first Markdown document Use Markdown for continuous integration Peek under the hood Further information Acknowledgements Contributing Citing Markdown README.md Markdown license release docker pulls docker image size ci 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: 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 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: 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 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 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. 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, + Markdown 2.7.0: Towards lightweight markup in TeX, + Making Markdown into a Microwave Meal, and + Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX. 5. Journal articles of me and my students published by CSTUG (in Czech and Slovak): + Rendering Markdown inside TeX Documents, + Markdown 2.8.1: Boldly Unto the Throne of Lightweight Markup in TeX, + Markdown 2.10.0: LaTeX Themes & Snippets, and + Direct Typesetting of Various Document Formats in TeX Using the Pandoc Utility. 6. My talks: + Five Years of Markdown in LaTeX: What, Why, How, and Whereto (in Czech), and + Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX (slides). Acknowledgements Logo Acknowledgement I gratefully acknowledge the funding from the [68747470733a2f2f7777] Faculty of Informatics at the Masaryk University in Brno, Czech Republic, for the development of the Markdown package. Extensive user documentation for the Markdown [68747470733a2f2f6364] package was kindly written by Lian Tze Lim and published by Overleaf. Support for content slicing (Lua options [68747470733a2f2f7062] 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 .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 as XeTeX (xetex markdown.ins) or 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 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. 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. 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} About A package for converting and rendering markdown documents in TeX ctan.org/pkg/markdown Resources Readme License LPPL-1.3c License Stars 199 stars Watchers 7 watching Forks 49 forks Releases 31 2.12.0 Latest Dec 30, 2021 + 30 releases Packages 0 No packages published Languages * TeX 97.3% * Makefile 1.3% * Other 1.4% * (c) 2022 GitHub, Inc. * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.