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.md230
1 files changed, 195 insertions, 35 deletions
diff --git a/macros/generic/markdown/README.md b/macros/generic/markdown/README.md
index 62d857935a..0543947bd6 100644
--- a/macros/generic/markdown/README.md
+++ b/macros/generic/markdown/README.md
@@ -1,11 +1,14 @@
Markdown
========
+[![license](https://img.shields.io/github/license/witiko/markdown)](LICENSE)
[![release](https://img.shields.io/github/release/witiko/markdown.svg)][release]
-[![ci](https://github.com/Witiko/markdown/workflows/Test/badge.svg)][ci]
+[![docker pulls](https://img.shields.io/docker/pulls/witiko/markdown)][docker-witiko/markdown]
+[![docker image size](https://img.shields.io/docker/image-size/witiko/markdown)][docker-witiko/markdown]
+[![ci](https://github.com/witiko/markdown/actions/workflows/main.yml/badge.svg)][ci]
- [release]: https://github.com/Witiko/markdown/releases/latest "Releases · Witiko/markdown"
- [ci]: https://github.com/Witiko/markdown/actions "GitHub Actions"
+ [release]: https://github.com/Witiko/markdown/releases/latest "Releases · Witiko/markdown"
+ [ci]: https://github.com/Witiko/markdown/actions "GitHub Actions"
The Markdown package converts [markdown][] markup to TeX commands. The
functionality is provided both as a Lua module, and as plain TeX, LaTeX, and
@@ -15,24 +18,155 @@ 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"
+ [markdown]: https://daringfireball.net/projects/markdown/basics "Daring Fireball: Markdown Basics"
- ![banner](banner.png "An example LaTeX document using the Markdown package")
+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:
+
+``` latex
+\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][docker-witiko/markdown] 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][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](markdown.png "An example LaTeX document using the Markdown package")
+
+Congratulations, you have just typeset your first Markdown document! 🥳
+
+ [tex-live]: https://www.tug.org/texlive/ "TeX Live - TeX Users Group"
+
+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][docker-witiko/markdown] as a drop-in replacement
+for [the `texlive/texlive:latest` Docker image][docker-texlive/texlive]!
+The following example shows a [GitHub Actions][github-actions] pipeline, which
+will automatically typeset and prerelease a PDF document:
+
+``` yaml
+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][techdoc-latest] for the Markdown package.
+
+ [docker-witiko/markdown]: https://hub.docker.com/r/witiko/markdown/tags "witiko/markdown - Docker Image"
+ [docker-texlive/texlive]: https://hub.docker.com/r/texlive/texlive/tags "texlive/texlive - Docker Image"
+
+ [github-actions]: https://docs.github.com/actions "GitHub Actions Documentation"
+
+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:
+
+``` markdown
+Hello *Markdown*! $a_x + b_x = c_x$
+```
+
+Next, run [the Lua command-line interface (CLI)][lua-cli] from
+[our official Docker image][docker-witiko/markdown] 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:
+
+``` tex
+Hello \markdownRendererEmphasis{Markdown}!
+$a\markdownRendererEmphasis{x + b}x = c_x$\relax
+```
+
+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
+
+``` tex
+Hello \markdownRendererEmphasis{Markdown}!
+$a_x + b_x = c_x$\relax
+```
+
+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.
+
+ [lua-cli]: https://mirrors.ctan.org/macros/generic/markdown/markdown.html#lua-command-line-interface "Markdown Package User Manual"
Further information
-------------------
For further information, consult one of the following:
-1. The [user manual][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][techdoc], which can be typeset by running the
- [LaTeXMK][] tool on the `markdown.dtx` file
- (`latexmk markdown.dtx`) after [installing the Markdown package][install].
- [LaTeXMK][] should be included in your TeX distribution. The typeset
- documentation will reside in the file `markdown.pdf`.
+1. The user manual for either [the released version][manual-tex-live] or
+ [the latest development version][manual-latest], 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][techdoc-tex-live]
+ or [the latest development version][techdoc-latest], which can be typeset by
+ running the [LaTeXMK][] tool on the `markdown.dtx` file (`latexmk
+ markdown.dtx`) after [installing the Markdown package][install].
+ [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][liantze] at [Overleaf][]:
- [How to write in Markdown on Overleaf][overleaf-1],
- [Markdown into LaTeX with Style][overleaf-2],
@@ -42,13 +176,15 @@ For further information, consult one of the following:
- [Using Markdown in LaTeX documents][overleaf-6].
4. My journal articles published by [TUGboat][]:
- [Using Markdown inside TeX documents][tb119],
- - [Markdown 2.7.0: Towards lightweight markup in TeX][tb124], and
- - [Making Markdown into a Microwave Meal][tb129].
+ - [Markdown 2.7.0: Towards lightweight markup in TeX][tb124],
+ - [Making Markdown into a Microwave Meal][tb129], and
+ - [Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX][tb131-preprint].
5. My journal articles published by [CSTUG][] (in Czech):
- [Rendering Markdown inside TeX Documents][10.5300/2016-1-4/78], and
- [Markdown 2.8.1: Boldly Unto the Throne of Lightweight Markup in TeX][10.5300/2020-1-2/48].
6. My talks:
- - [Five Years of Markdown in LaTeX: What, Why, How, and Whereto][pv212-fall2020] (in Czech).
+ - [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]).
[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"
@@ -57,28 +193,36 @@ 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"
+ [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-preprint]: https://tug.org/TUGboat/production/42-2/tb131novotny-markdown.pdf "Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX"
+ [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"
[10.5300/2016-1-4/78]: https://bulletin.cstug.cz/pdf/2016-1-4.pdf#page=80 "Rendering Markdown inside TeX Documents"
[10.5300/2020-1-2/48]: https://bulletin.cstug.cz/pdf/2020-1-2.pdf#page=50 "Markdown 2.8.1: Boldly Unto the Throne of Lightweight Markup in TeX"
[pv212-fall2020]: https://is.muni.cz/el/fi/podzim2020/PV212/index.qwarp?prejit=5595952
- [install]: http://mirrors.ctan.org/macros/generic/markdown/markdown.html#installation "Markdown Package User Manual"
- [liantze]: http://liantze.penguinattack.org/ "Rants from the Lab"
- [manual]: http://mirrors.ctan.org/macros/generic/markdown/markdown.html "Markdown Package User Manual"
- [overleaf]: https://www.overleaf.com/ "Overleaf: Real-time Collaborative Writing and Publishing Tools with Integrated PDF Preview"
- [techdoc]: http://mirrors.ctan.org/macros/generic/markdown/markdown.pdf "A Markdown Interpreter for TeX"
- [tugboat]: https://www.tug.org/tugboat/ "TUGboat - Communications of the TeX Users Group"
- [cstug]: https://www.cstug.cz/ "Československé sdružení uživatelů TeXu"
+ [install]: https://mirrors.ctan.org/macros/generic/markdown/markdown.html#installation "Markdown Package User Manual"
+ [liantze]: https://liantze.penguinattack.org/ "Rants from the Lab"
+ [overleaf]: https://www.overleaf.com/ "Overleaf: Real-time Collaborative Writing and Publishing Tools with Integrated PDF Preview"
+ [tugboat]: https://www.tug.org/tugboat/ "TUGboat - Communications of the TeX Users Group"
+ [cstug]: https://www.cstug.cz/ "Československé sdružení uživatelů TeXu"
+
+ [manual-latest]: https://witiko.github.io/markdown "Markdown Package User Manual"
+ [manual-tex-live]: https://mirrors.ctan.org/macros/generic/markdown/markdown.html "Markdown Package User Manual"
+
+ [techdoc-latest]: https://github.com/Witiko/markdown/releases/download/latest/markdown.pdf "A Markdown Interpreter for TeX"
+ [techdoc-tex-live]: https://mirrors.ctan.org/macros/generic/markdown/markdown.pdf "A Markdown Interpreter for TeX"
Acknowledgements
----------------
-| Logo | Acknowledgement |
-| ------------- | ------------- |
+| Logo | Acknowledgement |
+| ------------- | --------------- |
| [<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. |
| [<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][]. |
@@ -88,16 +232,16 @@ Acknowledgements
[mu]: https://www.muni.cz/en "Masaryk University"
[Omedym]: https://www.omedym.com/ "Omedym"
- [option-pipe-tables]: http://mirrors.ctan.org/macros/generic/markdown/markdown.html#pipe-tables "Markdown Package User Manual"
- [option-shift-headings]: http://mirrors.ctan.org/macros/generic/markdown/markdown.html#option-shiftheadings "Markdown Package User Manual"
- [option-slice]: http://mirrors.ctan.org/macros/generic/markdown/markdown.html#slice "Markdown Package User Manual"
- [option-table-captions]: http://mirrors.ctan.org/macros/generic/markdown/markdown.html#option-tablecaptions "Markdown Package User Manual"
+ [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"
+ [option-table-captions]: https://mirrors.ctan.org/macros/generic/markdown/markdown.html#option-tablecaptions "Markdown Package User Manual"
Contributing
------------
Apart from the example markdown documents, tests, and continuous integration,
-which are placed in the `examples/`, `tests/`, and `.circleci/` directories,
+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
@@ -118,6 +262,12 @@ 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][docker-witiko/markdown], 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.
+
[doc]: https://ctan.org/pkg/doc "doc – Format LaTeX documentation"
[DocStrip]: https://ctan.org/pkg/docstrip "docstrip – Remove comments from file"
[LaTeXMK]: https://ctan.org/pkg/latexmk "latexmk – Fully automated LaTeX document generation"
@@ -130,7 +280,7 @@ Citing Markdown
When citing Markdown in academic papers and theses, please use the following
BibTeX entry:
-```bib
+``` bib
@article{novotny17markdown,
author = {V\'{i}t Novotn\'{y}},
year = {2017},
@@ -144,3 +294,13 @@ BibTeX entry:
urldate = {2020-07-31},
}
```
+
+Alternatively, you can use the `Novotny:2017:UMI` key from the [`tugboat.bib`][tugboat.bib]
+BibTeX file that is included in your TeX distribution like this:
+
+``` tex
+\cite{Novotny:2017:UMI}
+\bibliography{tugboat}
+```
+
+ [tugboat.bib]: http://mirrors.ctan.org/info/digests/tugboat/biblio/tugboat.bib