diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/markdown/README.md')
-rw-r--r-- | Master/texmf-dist/doc/generic/markdown/README.md | 110 |
1 files changed, 67 insertions, 43 deletions
diff --git a/Master/texmf-dist/doc/generic/markdown/README.md b/Master/texmf-dist/doc/generic/markdown/README.md index 217cd6710e7..5a87521f0fc 100644 --- a/Master/texmf-dist/doc/generic/markdown/README.md +++ b/Master/texmf-dist/doc/generic/markdown/README.md @@ -4,24 +4,26 @@ Markdown [![license](https://img.shields.io/github/license/witiko/markdown)](LICENSE) [![ci](https://github.com/witiko/markdown/actions/workflows/main.yml/badge.svg)][ci] [![release](https://img.shields.io/github/release/witiko/markdown)][release] -  -[![matrix](https://img.shields.io/matrix/witiko-markdown:matrix.org?label=matrix%20chat)][matrix] -[![discord](https://img.shields.io/discord/1011667276908474440?label=discord%20chat&color=blueviolet)][discord] - - [release]: https://github.com/Witiko/markdown/releases/latest "Releases · Witiko/markdown" - [ci]: https://github.com/Witiko/markdown/actions "GitHub Actions" - [matrix]: https://matrix.to/#/#witiko-markdown:matrix.org "The Matrix Chat Space for the Markdown package" - [discord]: https://discord.gg/8xJsPghzSH "The Discord Chat Space for the Markdown package" - -The Markdown package converts [markdown][] markup to TeX commands. The +[![docker-witiko/markdown](https://img.shields.io/docker/v/witiko/markdown/latest?label=docker)][docker-witiko/markdown] +[![matrix](https://img.shields.io/matrix/witiko-markdown:matrix.org?label=matrix)][matrix] +[![discord](https://img.shields.io/discord/1011667276908474440?label=discord&color=blueviolet)][discord] +[![chatgpt](https://img.shields.io/badge/gpt-9cf)][chatgpt] + + [release]: https://github.com/Witiko/markdown/releases/latest "Releases · Witiko/markdown" + [ci]: https://github.com/Witiko/markdown/actions "GitHub Actions" + [matrix]: https://matrix.to/#/#witiko-markdown:matrix.org "The Matrix Chat Space for the Markdown package" + [discord]: https://discord.gg/8xJsPghzSH "The Discord Chat Space for the Markdown package" + [chatgpt]: https://chat.openai.com/g/g-I3K0DweJe-markdown-package-for-tex "ChatGPT - Markdown package for TeX" + +The Markdown package converts [CommonMark][] 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. 😉 +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. 😉 - [markdown]: https://daringfireball.net/projects/markdown/basics "Daring Fireball: Markdown Basics" + [commonmark]: https://commonmark.org/ "CommonMark: A strongly defined, highly compatible specification of Markdown" Your first Markdown document ---------------------------- @@ -56,12 +58,12 @@ Next, run the [LaTeXMK][] tool from [our official Docker image][docker-witiko/markdown] on `document.tex`: docker run --rm -v "$PWD"/workdir:/workdir -w /workdir witiko/markdown \ - latexmk -lualatex -silent document.tex + latexmk -pdf -shell-escape -silent document.tex Alternatively, you can install [TeX Live][tex-live] (can take up to several hours) and use its [LaTeXMK][] tool: - latexmk -cd -lualatex -silent workdir/document.tex + latexmk -cd -pdf -shell-escape -silent workdir/document.tex A PDF document named `workdir/document.pdf` should be produced and contain the following output: @@ -95,6 +97,8 @@ jobs: - 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 @@ -114,7 +118,7 @@ In fact, this is how we automatically produce Peek under the hood ------------------- -Remember how we said that the Markdown package converts [markdown][] markup to +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 @@ -180,26 +184,32 @@ For further information, consult one of the following: - [Writing Beamer Slides with Markdown][overleaf-4], - [Writing Posters with Markdown][overleaf-5], and - [Using Markdown in LaTeX documents][overleaf-6]. -4. My journal articles published by [TUGboat][]: +4. Journal articles published by [TUGboat][]: - [Using Markdown inside TeX documents][tb119], - [Markdown 2.7.0: Towards lightweight markup in TeX][tb124], - [Making Markdown into a Microwave Meal][tb129], - [Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX][tb131], - [Markdown 2.15.0: What's New?][tb133], - - [Markdown 2.17.1: What's New, What's Next?][tb135], and - - [Attributes in Markdown][tb136]. -5. Journal articles of me and my students published by [CSTUG Bulletin][csbul] (in Czech and Slovak): + - [Markdown 2.17.1: What's New, What's Next?][tb135], + - [Attributes in Markdown][tb136], + - Markdown 3 at TUG 2023: Reflections from the Q&A session ([preprint][tb138]), and + - Fast Regression Testing of TeX Packages: The Unreasonable Effectiveness of Batching ([work in progress][tb139]). +5. Journal articles published by [CSTUG Bulletin][csbul] (in Czech and Slovak): - [Rendering Markdown inside TeX Documents][10.5300/2016-1-4/78], - [Markdown 2.8.1: Boldly Unto the Throne of Lightweight Markup in TeX][10.5300/2020-1-2/48], - [Markdown 2.10.0: LaTeX Themes & Snippets][10.5300/2021-1-4/76], - - [Direct Typesetting of Various Document Formats in TeX Using the Pandoc Utility][10.5300/2021-1-4/83], and - - [High-Level Languages for TeX][10.5300/2022-1-4/35]. -6. Talks by me and my students: - - [Five Years of Markdown in LaTeX: What, Why, How, and Whereto][pv212-fall2020] (in Czech), and - - [Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX][tb131-video] ([slides][tb131-slides]). - - [A Gentle Introduction to Markdown for Writers][tb134-video] ([slides][tb134-slides], [example][tb134-example]). -7. Theses by my students: + - [Direct Typesetting of Various Document Formats in TeX Using the Pandoc Utility][10.5300/2021-1-4/83], + - [High-Level Languages for TeX][10.5300/2022-1-4/35], and + - Markdown 3: What's New, What's Next? ([preprint][10.5300/2023-?-?/??]). +6. Talks: + - [Five Years of Markdown in LaTeX: What, Why, How, and Whereto][pv212-fall2020] (in Czech), + - [Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX][tb131-video] ([slides][tb131-slides]), + - [A Self-Publisher's Take on Markdown and TeX][tb134-01-video] ([slides][tb134-01-slides]), and + - [A Gentle Introduction to Markdown for Writers][tb134-02-video] ([slides][tb134-02-slides], [example][tb134-02-example]), and + - [Markdown 3: What's New, What's Next?][tb137-video] ([slides][tb137-slides]). +7. Theses: - [Generic TeX Writer for the Pandoc Document Converter][thesis-umhg5] + - [An implementation of the CommonMark standard into the Markdown package for TeX][thesis-r7z7l] [overleaf-1]: https://www.overleaf.com/learn/latex/Articles/How_to_write_in_Markdown_on_Overleaf "How to write in Markdown on Overleaf" [overleaf-2]: https://www.overleaf.com/learn/latex/Articles/Markdown_into_LaTeX_with_Style "Markdown into LaTeX with Style" @@ -208,19 +218,25 @@ For further information, consult one of the following: [overleaf-5]: https://www.overleaf.com/latex/examples/writing-posters-with-markdown/jtbgmmgqrqmh "Writing Posters with Markdown" [overleaf-6]: https://www.overleaf.com/latex/examples/using-markdown-in-latex-documents/whdrnpcpnwrm "Using Markdown in LaTeX documents" - [tb119]: https://www.tug.org/TUGboat/tb38-2/tb119novotny.pdf "Using Markdown inside TeX documents" - [tb124]: https://www.tug.org/TUGboat/tb40-1/tb124novotny-markdown.pdf "Markdown 2.7.0: Towards lightweight markup in TeX" - [tb129]: https://www.tug.org/TUGboat/tb41-3/tb129novotny-frozen.pdf "Making Markdown into a Microwave Meal" - [tb131]: https://www.tug.org/TUGboat/tb42-2/tb131novotny-markdown.pdf "Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX" - [tb133]: https://www.tug.org/TUGboat/tb43-1/tb133novotny-markdown.pdf "Markdown 2.15.0: What's New?" - [tb135]: https://www.overleaf.com/read/pgwrhhskmgfm "Markdown 2.17.1: What's New, What's Next?" - [tb136]: https://www.overleaf.com/read/dshtsnnmtshs "Attributes in Markdown" - - [tb131-slides]: https://tug.org/tug2021/assets/pdf/tug2021-novotny-slides.pdf "Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX" - [tb131-video]: https://youtu.be/THmPkAncMnc "Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX" - [tb134-slides]: https://tug.org/tug2022/assets/pdf/Tereza_Vrabcová-TUG2022-slides.pdf "A Gentle Introduction to Markdown for Writers" - [tb134-example]: https://tug.org/tug2022/assets/pdf/Tereza_Vrabcová-TUG2022-example.pdf "A Gentle Introduction to Markdown for Writers" - [tb134-video]: https://youtu.be/cqbKgjAlNjo?t=2h10m35s "A Gentle Introduction to Markdown for Writers" + [tb119]: https://www.tug.org/TUGboat/tb38-2/tb119novotny.pdf "Using Markdown inside TeX documents" + [tb124]: https://www.tug.org/TUGboat/tb40-1/tb124novotny-markdown.pdf "Markdown 2.7.0: Towards lightweight markup in TeX" + [tb129]: https://www.tug.org/TUGboat/tb41-3/tb129novotny-frozen.pdf "Making Markdown into a Microwave Meal" + [tb131]: https://www.tug.org/TUGboat/tb42-2/tb131novotny-markdown.pdf "Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX" + [tb133]: https://www.tug.org/TUGboat/tb43-1/tb133novotny-markdown.pdf "Markdown 2.15.0: What's New?" + [tb135]: https://www.tug.org/TUGboat/tb43-3/tb135novotny-markdown.pdf "Markdown 2.17.1: What's New, What's Next?" + [tb136]: https://www.tug.org/TUGboat/tb44-1/tb136novotny-markdown-attr.pdf "Attributes in Markdown" + [tb138]: https://www.overleaf.com/read/mjghwhrbgmfj "Markdown 3 at TUG 2023: Reflections from the Q&A session" + [tb139]: https://github.com/witiko/fast-regression-testing/releases/download/latest/main.pdf "Fast Regression Testing of TeX Packages: The Unreasonable Effectiveness of Batching" + + [tb131-slides]: https://tug.org/tug2021/assets/pdf/tug2021-novotny-slides.pdf "Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX" + [tb131-video]: https://youtu.be/i2GJMnLCZls "Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX" + [tb134-01-slides]: https://tug.org/tug2022/assets/served/Lloyd_Prentice-TUG2022-prentice-selfpub-slides.pdf "A Self-Publisher's Take on Markdown and TeX" + [tb134-01-video]: https://youtu.be/OhwzT3TcLj8 "A Self-Publisher's Take on Markdown and TeX" + [tb134-02-slides]: https://tug.org/tug2022/assets/pdf/Tereza_Vrabcová-TUG2022-slides.pdf "A Gentle Introduction to Markdown for Writers" + [tb134-02-example]: https://tug.org/tug2022/assets/pdf/Tereza_Vrabcová-TUG2022-example.pdf "A Gentle Introduction to Markdown for Writers" + [tb134-02-video]: https://youtu.be/FhN_x9rsR4M "A Gentle Introduction to Markdown for Writers" + [tb137-slides]: https://tug.org/tug2023/files/sa-03-novotny-markdown3/novotny-markdown3-slides.pdf "Markdown 3: What's New, What's Next?" + [tb137-video]: https://youtu.be/U8XjTOhJkg0 "Markdown 3: What's New, What's Next?" [10.5300/2016-1-4/78]: https://www.doi.org/10.5300/2016-1-4/78 "Rendering Markdown inside TeX Documents" [10.5300/2020-1-2/48]: https://www.doi.org/10.5300/2020-1-2/48 "Markdown 2.8.1: Boldly Unto the Throne of Lightweight Markup in TeX" @@ -228,7 +244,9 @@ For further information, consult one of the following: [10.5300/2021-1-4/83]: https://www.doi.org/10.5300/2021-1-4/83 "Direct Typesetting of Various Document Formats in TeX Using the Pandoc Utility" [10.5300/2022-1-4/35]: https://www.doi.org/10.5300/2022-1-4/35 "High-Level Languages for TeX" - [pv212-fall2020]: https://is.muni.cz/elearning/warp?qurl=%2Fel%2Ffi%2Fpodzim2020%2FPV212%2Findex.qwarp;prejit=5595952 + [10.5300/2023-?-?/??]: https://github.com/witiko/markdown-3-whats-new-whats-next/releases/download/latest/main.pdf "Markdown 3: What's New, What's Next?" + + [pv212-fall2020]: https://is.muni.cz/elearning/io/?qurl=%2Fel%2Ffi%2Fpodzim2020%2FPV212%2Findex.qwarp;prejit=5595952 [install]: https://mirrors.ctan.org/macros/generic/markdown/markdown.html#installation "Markdown Package User Manual" [liantze]: http://liantze.penguinattack.org/ "Rants from the Lab" @@ -243,6 +261,7 @@ For further information, consult one of the following: [techdoc-tex-live]: https://mirrors.ctan.org/macros/generic/markdown/markdown.pdf "A Markdown Interpreter for TeX" [thesis-umhg5]: https://is.muni.cz/th/umhg5/?lang=en "Generic TeX Writer for the Pandoc Document Converter" + [thesis-r7z7l]: https://is.muni.cz/th/r7z7l/?lang=en "An implementation of the CommonMark standard into the Markdown package for TeX" Acknowledgements ---------------- @@ -252,12 +271,17 @@ Acknowledgements | [<img width="150" src="https://www.fi.muni.cz/images/fi-logo.png">][fimu] | I gratefully acknowledge the funding from the [Faculty of Informatics][fimu] at the [Masaryk University][mu] 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][]. | | [<img width="150" src="https://cdn.overleaf.com/img/ol-brand/overleaf_og_logo.png">][overleaf] | Extensive user documentation for the Markdown package was kindly written by [Lian Tze Lim][liantze] and published by [Overleaf][]. | | [<img width="150" src="https://pbs.twimg.com/profile_images/1004769879319334912/6Bh1UthD.jpg">][omedym] | Support for content slicing (Lua options [`shiftHeadings`][option-shift-headings] and [`slice`][option-slice]) and pipe tables (Lua options [`pipeTables`][option-pipe-tables] and [`tableCaptions`][option-table-captions]) was graciously sponsored by [David Vins][dvins] and [Omedym][]. | +| [<img width="150" src="https://www.istqb.org/static/istqb-logo-1b043e800a580724ad223567f9ea57c0.png">][istqb] | Fixes for issues [#359][issue-359] and [#368][issue-368] were graciously sponsored by the [International Software Testing Qualifications Board (ISTQB)][istqb]. | [dvins]: https://github.com/dvins "David Vins" [fimu]: https://www.fi.muni.cz/index.html.en "Faculty of Informatics, Masaryk University" + [ISTQB]: https://www.istqb.org/ "International Software Testing Qualifications Board" [mu]: https://www.muni.cz/en "Masaryk University" [Omedym]: https://www.omedym.com/ "Omedym" + [issue-359]: https://github.com/witiko/markdown/issues/359 "First item of a fancy list forms a separate list" + [issue-368]: https://github.com/witiko/markdown/issues/368 "Tables nested in list items have empty lines" + [option-pipe-tables]: https://mirrors.ctan.org/macros/generic/markdown/markdown.html#pipe-tables "Markdown Package User Manual" [option-shift-headings]: https://mirrors.ctan.org/macros/generic/markdown/markdown.html#option-shiftheadings "Markdown Package User Manual" [option-slice]: https://mirrors.ctan.org/macros/generic/markdown/markdown.html#slice "Markdown Package User Manual" |