diff options
Diffstat (limited to 'macros/generic/markdown/markdown.md')
-rw-r--r-- | macros/generic/markdown/markdown.md | 302 |
1 files changed, 0 insertions, 302 deletions
diff --git a/macros/generic/markdown/markdown.md b/macros/generic/markdown/markdown.md deleted file mode 100644 index 9488ded486..0000000000 --- a/macros/generic/markdown/markdown.md +++ /dev/null @@ -1,302 +0,0 @@ - ---- -title: Markdown Package User Manual -author: Vít Novotný -date: \markdownVersion{} (\markdownLastModified{}) ---- - - -<link href="https://afeld.github.io/emoji-css/emoji.css" rel="stylesheet" /> - -Introduction -============ -The [Markdown package][pkg] converts [markdown][] markup to \TeX{} commands. The -functionality is provided both as a Lua module and as plain \TeX{}, \LaTeX{}, and -\Hologo{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. 😉 - - [markdown]: https://daringfireball.net/projects/markdown/basics - (Daring Fireball: Markdown Basics) - [pkg]: https://ctan.org/pkg/markdown - (CTAN: Package markdown) - - -This document is a user manual for the [Markdown package][pkg]. It provides -tutorials and code examples. For an in-depth description of the package -requirements, interfaces, and implementation, please refer to the [technical -documentation][techdoc]. - - [techdoc]: http://mirrors.ctan.org/macros/generic/markdown/markdown.pdf - (A Markdown Interpreter for TeX) - - -Requirements ------------- - -The package requires either [our official Docker image][docker], which contains -the latest development version of the Markdown package, or a \TeX{} -distribution: [\TeX{} Live][tl] ≥ 2018 is known to work with the current -version of the Markdown package and so are recent versions of [Mik\TeX{}][mik]. -If you are using an older, incomplete, or atypical \TeX{} distribution, please -consult the [technical documentation][techdoc] for a detailed list of -requirements. - - [docker]: https://hub.docker.com/r/witiko/markdown/tags (witiko/markdown - Docker Image) - [tl]: https://www.tug.org/texlive/ (TeX Live - TeX Users Group) - [mik]: https://miktex.org/ (Home - MiKTeXorg) - -Installation ------------- - -If Markdown is not included in your \TeX{} distribution, you will need to -install it. - -First, download the package from the repository using Git: -``` sh -git clone https://github.com/witiko/markdown -`````` -Next, enter the directory named `markdown` and run the `make base` command using -GNU Make: -``` sh -cd markdown -make base -`````` -This should produce the following files: - - * `markdown.lua`, the Lua module, - * `libraries/markdown-tinyyaml.lua`, an external library for reading \acro{yaml}, - * `markdown-cli.lua`, the Lua command-line interface, - * `markdown.tex`, the plain \TeX{} macro package, - * `markdown.sty`, the \LaTeX{} package, - * `markdownthemewitiko_dot.sty`, the `witiko/dot` \LaTeX{} theme, - * `markdownthemewitiko_graphicx_http.sty`, the `witiko/graphicx/http` \LaTeX{} theme, - * `markdownthemewitiko_tilde.sty`, the `witiko/tilde` \LaTeX{} theme, and - * `t-markdown.tex`, the \Hologo{ConTeXt} module. - -### Local Installation - -To perform a local installation, place the above files into your \TeX{} -directory structure. This is generally where the individual files should be -placed: - - * `⟨TEXMF⟩/tex/luatex/markdown/markdown.lua` - * `⟨TEXMF⟩/tex/luatex/markdown/markdown-tinyyaml.lua` - * `⟨TEXMF⟩/scripts/markdown/markdown-cli.lua` - * `⟨TEXMF⟩/tex/generic/markdown/markdown.tex` - * `⟨TEXMF⟩/tex/latex/markdown/markdown.sty` - * `⟨TEXMF⟩/tex/latex/markdown/markdownthemewitiko_dot.sty` - * `⟨TEXMF⟩/tex/latex/markdown/markdownthemewitiko_graphicx_http.sty` - * `⟨TEXMF⟩/tex/latex/markdown/markdownthemewitiko_tilde.sty` - * `⟨TEXMF⟩/tex/context/third/markdown/t-markdown.tex` - -where `⟨TEXMF⟩` corresponds to a root of your \TeX{} distribution, such as -`/usr/share/texmf` and `~/texmf` on UN\*X systems or -`C:\Users\`\meta{Your username}`\texmf` on Windows systems. When in doubt, -consult the manual of your \TeX{} distribution. - -### Portable Installation - -Alternatively, you can also store the above files in the same folder as your -\TeX{} document and distribute them together. This way your document can be -portably typeset on legacy \TeX{} distributions. - -Since Markdown version 2.10.0, the file `markdown.tex` must be placed in -a directory named `markdown` due to [issue #74][issue-74]. - - [issue-74]: https://github.com/witiko/markdown/issues/74 (Does not compile if user names own document markdown.tex) - - -First Document --------------- - -In this section, we will take the necessary steps to typeset our first markdown -document in \TeX{}. This will serve as our first hands-on experience with the -package and also as a reassurance that the package has been correctly installed. - -If you are using [our official Docker image][docker], you need to prefix all -commands in this section with `docker run --rm -v "$PWD"/workdir:/workdir -w -/workdir witiko/markdown`. For example, instead of `luatex document.tex`, you -would execute the following command: -``` sh -docker run --rm -v "$PWD"/workdir:/workdir -w /workdir witiko/markdown \ - luatex document.tex -`````` - -### Using Lua - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input hello -\bye -``````` - -#### Using the Lua Module - -Using a text editor, create a text document named `hello.lua` with the -following content: -``` lua -#!/usr/bin/env texlua -local ran_ok, kpse = pcall(require, "kpse") -if ran_ok then kpse.set_program_name("luatex") end -local markdown = require("markdown") -local convert = markdown.new() -print(convert("Hello *world*!")) -``````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua hello.lua > hello.tex -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the text -“Hello *world*!” Invoking pdfTeX should have the same effect: -``` sh -texlua hello.lua > hello.tex -pdftex document.tex -`````` - -#### Using the Lua Command-Line Interface - -Using a text editor, create a text document named `hello.md` with the -following content: -``` md -Hello *world*! -`````` -Next, invoke LuaTeX from the terminal: -``` sh -texlua ⟨CLI pathname⟩ -- hello.md hello.tex -luatex document.tex -`````` -where \meta{CLI pathname} corresponds to the location of the Lua CLI script file, -such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or -`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows -systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI -script file using [Kpathsea][]. - - [Kpathsea]: https://tug.org/kpathsea/ (Kpathsea - TeX Users Group) - -A PDF document named `document.pdf` should be produced and contain the text “Hello -*world*!” Invoking pdfTeX should have the same effect: -``` sh -texlua ⟨CLI pathname⟩ -- hello.md hello.tex -pdftex document.tex -`````` - -### Using Plain \TeX{} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\markdownBegin -Hello *world*! -\markdownEnd -\bye -``````` -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the text -“Hello *world*!” Invoking pdfTeX should have the same effect: -``` sh -pdftex --shell-escape document.tex -``````` - -### Using \LaTeX{} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage{markdown} -\begin{document} -\begin{markdown} -Hello *world*! -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the text “Hello -*world*!” Invoking pdfTeX should have the same effect: -``` sh -pdflatex --shell-escape document.tex -`````` - -*** - -As the next step, try typesetting the example documents distributed along with -the Markdown package: -``` sh -git clone https://github.com/witiko/markdown -cd markdown/examples -lualatex latex.tex -`````` -A PDF document named `latex.pdf` should be produced. Open the text documents -`latex.tex` and `example.md` in a text editor to see how the example documents -are structured. Try changing the documents and typesetting them as follows: -``` sh -lualatex latex.tex -`````` -to see the effect of your changes. - -### Using \Hologo{ConTeXt} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\starttext -\startmarkdown -Hello *world*! -\stopmarkdown -\stoptext -``````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the text “Hello -*world*!” Invoking pdfTeX should have the same effect: -``` sh -texexec --passon=--shell-escape document.tex -`````` - -*** - -As the next step, try typesetting the example documents distributed along with -the Markdown package: -``` sh -git clone https://github.com/witiko/markdown -cd markdown/examples -context context.tex -`````` -A PDF document named `context.pdf` should be produced. Open the text documents -`context.tex` and `example.md` in a text editor to see how the example documents -are structured. Try changing the documents and typesetting them as follows: -``` sh -context context.tex -`````` -to see the effect of your changes. - -Examples -======== - -In this section, I will describe the individual parts of the Markdown package. -Each part will be shown by example, leaving the implementation details to the -[technical documentation][techdoc]. - - [techdoc]: https://mirrors.ctan.org/macros/generic/markdown/markdown.pdf - (A Markdown Interpreter for \TeX{}) - -/markdown-interfaces.md -/markdown-options.md -/markdown-tokens.md - |