summaryrefslogtreecommitdiff
path: root/macros/generic/markdown/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'macros/generic/markdown/README.md')
-rw-r--r--macros/generic/markdown/README.md110
1 files changed, 67 insertions, 43 deletions
diff --git a/macros/generic/markdown/README.md b/macros/generic/markdown/README.md
index 217cd6710e..5a87521f0f 100644
--- a/macros/generic/markdown/README.md
+++ b/macros/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"