diff options
Diffstat (limited to 'Master/texmf-dist/source/generic/markdown/markdown.dtx')
| -rw-r--r-- | Master/texmf-dist/source/generic/markdown/markdown.dtx | 2795 |
1 files changed, 2234 insertions, 561 deletions
diff --git a/Master/texmf-dist/source/generic/markdown/markdown.dtx b/Master/texmf-dist/source/generic/markdown/markdown.dtx index d32712738b9..fad63a37918 100644 --- a/Master/texmf-dist/source/generic/markdown/markdown.dtx +++ b/Master/texmf-dist/source/generic/markdown/markdown.dtx @@ -1,12 +1,13 @@ % \iffalse +%<@@=markdown> %<*driver> \documentclass{ltxdockit} \usepackage[american]{babel} -\usepackage{amsmath,btxdockit,doc,fancyvrb,graphicx,hologo,microtype,minted} -\usepackage{fontspec} -\defaultfontfeatures[\rmfamily,\sffamily,\ttfamily]{} +\usepackage{amsmath,btxdockit,doc,fancyvrb,graphicx,hologo,microtype,minted,varioref} % Set up the style. +\usepackage{fontspec} +\defaultfontfeatures[\rmfamily,\sffamily,\ttfamily]{} \emergencystretch=1em \fvset{gobble=0,frame=single} \setcounter{secnumdepth}{4} @@ -30,29 +31,47 @@ % Define some markup. \let\pkg\relax % A package name +\def\inline#1{% Inline code + \textcolor{spot}{\text{\texttt{#1}}}} +\newcommand\acro[1]{% An acronym + \textsc{\MakeLowercase{#1}}} + +% Set up index. +\DisableCrossrefs +\usepackage{makeidx} +\usepackage[columns=1, totoc]{idxlayout} +\makeindex + \newcommand\mdef[1]{% A TeX macro definition + \index{#1@\cs{#1}|textit}% \phantomsection\label{macro:#1}\textcolor{spot}{\cs{#1}}} -\newcommand\m[1]{% A TeX macro reference +\newcommand\mref[1]{% A TeX macro reference + \index{#1@\cs{#1}}% \hyperref[macro:#1]{\textcolor{spot}{\cs{#1}}}} -\newcommand\envmdef[1]{% A TeX macro definition - \phantomsection\label{environment:#1}\t`#1`} -\newcommand\envm[1]{% A LaTeX environment reference - \hyperref[environment:#1]{\t`#1`}} + +\newcommand\envmdef[1]{% A LaTeX environment definition + \index{#1@\texttt{#1}|textit}% + \phantomsection\label{environment:#1}\inline{#1}} +\newcommand\envmref[1]{% A LaTeX environment reference + \index{#1@\texttt{#1}}% + \hyperref[environment:#1]{\inline{#1}}} + \newcommand\luamdef[1]{% A Lua object / method definition - \phantomsection\label{lua:#1}\t`#1`} -\newcommand\luam[1]{% A Lua object / method reference - \hyperref[lua:#1]{\t`#1`}} -\def\inline#1{% Inline code - \textcolor{spot}{\text{\texttt{#1}}}} -\def\t`#1`{\inline{#1}} + \index{#1@\texttt{#1}|textit}% + \phantomsection\label{lua:#1}\inline{#1}} +\newcommand\luamref[1]{% A Lua object / method reference + \index{#1@\texttt{#1}}% + \hyperref[lua:#1]{\inline{#1}}} + \newcommand\Optitem[2][]{\penalty -1000\relax % An option item definition + \index{#2@\texttt{#2}|textit}% \phantomsection\label{opt:#2}\optitem[#1]{#2}} \newcommand\Valitem[2][]{\penalty -1000\relax % A value item definition + \index{#2@\texttt{#2}}% \phantomsection\label{opt:#2}\valitem[#1]{#2}} \newcommand\Opt[1]{% An option / value item reference - \hyperref[opt:#1]{\t`#1`}} -\newcommand\acro[1]{% An acronym - \textsc{\MakeLowercase{#1}}} + \index{#1@\texttt{#1}}% + \hyperref[opt:#1]{\inline{#1}}} % Set up markdown. \usepackage[ @@ -62,23 +81,24 @@ headerAttributes, hybrid, html, + jekyllData, stripPercentSigns, underscores=false, theme=witiko/dot, theme=witiko/graphicx/http, + theme=witiko/markdown/techdoc, ]{markdown} -\markdownSetup{ - renderers = { - codeSpan = {\inline{#1}}, - link = {#1\footnote{See \url{#3}.}}, - headingFour = {% - \paragraph{#1}\leavevmode - \def\markdownRendererInterblockSeparator{% - \let\markdownRendererInterblockSeparator\par - }% - \noindent - }, - }, + +% Set up Unicode characters. +\usepackage{newunicodechar} +\newunicodechar{☒}{\markdownRendererTickedBox} +\newunicodechar{⌛}{\markdownRendererHalfTickedBox} +\newunicodechar{☐}{\markdownRendererUntickedBox} +\IfFileExists{emoji.sty}{ + \usepackage{emoji} + \newunicodechar{😉}{\emoji{winking-face}} +}{ + \newunicodechar{😉}{;-)} } % Set up the catcodes. @@ -86,94 +106,24 @@ \catcode`\^^B=8 % When we occasionally need subscripts , we will use `^^B` (STX). % Set up the title page. -\titlepage{% - title={A Markdown Interpreter for \TeX{}}, - subtitle={}, - url={https://github.com/witiko/markdown}, - author={Vít Novotný}, - email={witiko@mail.muni.cz}, - revision=\markdownVersion, - date={\today}} -\hypersetup{% - pdftitle={A Markdown Interpreter for \TeX{}}, - pdfauthor={Vít Novotný}} +\begin{markdown} +--- +title: A Markdown Interpreter for \TeX +url: https://github.com/witiko/markdown +author: Vít Novotný +email: witiko@mail.muni.cz +revision: \markdownVersion +date: \markdownLastModified +--- +\end{markdown} \CodelineIndex +% Set up the figures. +\usepackage{tikz} +\usepackage{mathabx,pgf-umlsd,tikz} +\usetikzlibrary{automata,arrows.meta,positioning,shapes.geometric} + % Set up the bibliography. -\begin{filecontents}[overwrite,nosearch,noheader]{markdown.bib} -@book{tantau21, - author = {Till Tantau and Joseph Wright and Vedran Miletić}, - title = {The Beamer class}, - date = {2021-02-10}, - url = {http://mirrors.ctan.org/macros/latex/contrib/beamer/doc/beameruserguide.pdf}, - urldate = {2021-02-11}} -@online{sotkov17, - author = {Sotkov, Anton}, - title = {File transclusion syntax for Markdown}, - date = {2017-01-19}, - url = {https://github.com/iainc/Markdown-Content-Blocks}, - urldate = {2018-01-08}} -@book{luatex17, - author = {{Lua\TeX{} development team}}, - title = {Lua\TeX{} reference manual}, - year = {2017}, - month = {2}, - url = {http://www.luatex.org/svn/trunk/manual/luatex.pdf}, - urldate = {2018-01-08}} -@book{latex17, - author = {Braams, Johannes and Carlisle, David and Jeffrey, Alan and - Lamport, Leslie and Mittelbach, Frank and Rowley, Chris and - Schöpf, Rainer}, - title = {The \Hologo{LaTeX2e} Sources}, - date = {2017-04-15}, - url = {http://mirrors.ctan.org/macros/latex/base/source2e.pdf}, - urldate = {2018-01-08}} -@book{mittelbach17, - author = {Mittelbach, Frank}, - title = {The \texttt{doc} and \texttt{shortvrb} Packages}, - date = {2017-04-15}, - url = {http://mirrors.ctan.org/macros/latex/base/doc.pdf}, - urldate = {2018-02-19}} -@book{poore17, - author = {Poore, Geoffrey M.}, - title = {The \texttt{minted} Package}, - subtitle = {Highlighted source code in \LaTeX}, - date = {2017-07-19}, - version = {v2.5}, - url = {http://mirrors.ctan.org/macros/latex/contrib/minted/minted.pdf}, - urldate = {2020-09-01}} -@online{novotny15, - author = {Novotný, Vít}, - year = {2015}, - title = {TeXový interpret jazyka Markdown (markdown.sty)}, - location = {Brno, Czech Republic}, - publisher = {Masaryk University}, - url = {https://www.muni.cz/en/research/projects/32984}, - urldate = {2018-02-19}} -@book{ierusalimschy13, - author = {Ierusalimschy, Roberto}, - year = {2013}, - title = {Programming in Lua}, - edition = {3}, - isbn = {978-85-903798-5-0}, - pagetotal = {xviii, 347}, - location = {Rio de Janeiro}, - publisher = {PUC-Rio}} -@book{knuth86, - author = {Knuth, Donald Ervin}, - year = {1986}, - title = {The \TeX{}book}, - edition = {3}, - isbn = {0-201-13447-0}, - pagetotal = {ix, 479}, - publisher = {Addison-Wesley}} -@online{novotny21, - author = {Novotný, Vít}, - title = {\Hologo{LaTeX2e} no longer keys packages by pathnames}, - date = {2021-02-20}, - url = {https://github.com/latex3/latex2e/issues/510}, - urldate = {2021-02-21}} -\end{filecontents} \usepackage[ backend=biber, style=numeric, @@ -183,10 +133,9 @@ \addbibresource{markdown.bib} \begin{document} -\printtitlepage -\tableofcontents \DocInput{markdown.dtx} -\printbibliography +\printbibliography[heading=bibintoc] +\printindex \end{document} %</driver> %<*manual-css> @@ -542,12 +491,329 @@ abbr { } %</manual-css> +%<*techdoc-block-diagram> +\begingroup +\ifx\du\undefined\newlength{\du}\fi +\setlength{\du}{15\unitlength} +\begin{tikzpicture} +\pgftransformxscale{1.000000} +\pgftransformyscale{-1.23800} +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000} +\pgfsetfillcolor{dialinecolor} +\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000} +\pgfsetfillcolor{dialinecolor} +\fill (4.282853\du,-3.750000\du)--(4.282853\du,-1.850000\du)--(11.971656\du,-1.850000\du)--(11.971656\du,-3.750000\du)--cycle; +\pgfsetlinewidth{0.040000\du} +\pgfsetdash{}{0pt} +\pgfsetdash{}{0pt} +\pgfsetmiterjoin +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\draw (4.282853\du,-3.750000\du)--(4.282853\du,-1.850000\du)--(11.971656\du,-1.850000\du)--(11.971656\du,-3.750000\du)--cycle; +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\node at (8.127254\du,-2.705000\du){\LaTeX{} layer}; +\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000} +\pgfsetfillcolor{dialinecolor} +\fill (-5.055135\du,-3.788555\du)--(-5.055135\du,-1.888555\du)--(2.894865\du,-1.888555\du)--(2.894865\du,-3.788555\du)--cycle; +\pgfsetlinewidth{0.040000\du} +\pgfsetdash{}{0pt} +\pgfsetdash{}{0pt} +\pgfsetmiterjoin +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\draw (-5.055135\du,-3.788555\du)--(-5.055135\du,-1.888555\du)--(2.894865\du,-1.888555\du)--(2.894865\du,-3.788555\du)--cycle; +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\node at (-1.080135\du,-2.743555\du){\Hologo{ConTeXt} layer}; +\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000} +\pgfsetfillcolor{dialinecolor} +\fill (-8.200000\du,-0.224996\du)--(-8.200000\du,1.675004\du)--(11.870000\du,1.675004\du)--(11.870000\du,-0.224996\du)--cycle; +\pgfsetlinewidth{0.040000\du} +\pgfsetdash{}{0pt} +\pgfsetdash{}{0pt} +\pgfsetmiterjoin +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\draw (-8.200000\du,-0.224996\du)--(-8.200000\du,1.675004\du)--(11.870000\du,1.675004\du)--(11.870000\du,-0.224996\du)--cycle; +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\node at (1.835000\du,0.820004\du){Plain \TeX{} layer}; +\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000} +\pgfsetfillcolor{dialinecolor} +\fill (-11.150000\du,3.325006\du)--(-11.150000\du,5.225006\du)--(11.800000\du,5.225006\du)--(11.800000\du,3.325006\du)--cycle; +\pgfsetlinewidth{0.040000\du} +\pgfsetdash{}{0pt} +\pgfsetdash{}{0pt} +\pgfsetmiterjoin +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\draw (-11.150000\du,3.325006\du)--(-11.150000\du,5.225006\du)--(11.800000\du,5.225006\du)--(11.800000\du,3.325006\du)--cycle; +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\node at (0.325000\du,4.370006\du){Lua layer}; +\pgfsetlinewidth{0.040000\du} +\pgfsetdash{}{0pt} +\pgfsetdash{}{0pt} +\pgfsetbuttcap +{ +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetfillcolor{dialinecolor} +\pgfsetarrowsstart{stealth} +\pgfsetarrowsend{stealth} +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\draw (-9.906400\du,-5.181570\du)--(-9.937836\du,3.024193\du); +} +\pgfsetlinewidth{0.040000\du} +\pgfsetdash{}{0pt} +\pgfsetdash{}{0pt} +\pgfsetbuttcap +{ +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetfillcolor{dialinecolor} +\pgfsetarrowsstart{stealth} +\pgfsetarrowsend{stealth} +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\draw (-6.919693\du,-5.181570\du)--(-6.938734\du,-0.450800\du); +} +\pgfsetlinewidth{0.040000\du} +\pgfsetdash{}{0pt} +\pgfsetdash{}{0pt} +\pgfsetbuttcap +{ +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetfillcolor{dialinecolor} +\pgfsetarrowsstart{stealth} +\pgfsetarrowsend{stealth} +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\draw (-1.063746\du,-5.175791\du)--(-1.063746\du,-3.975793\du); +} +\definecolor{dialinecolor}{rgb}{1.000000, 1.000000, 1.000000} +\pgfsetfillcolor{dialinecolor} +\fill (-10.972500\du,-7.267480\du)--(-10.972500\du,-5.367480\du)--(11.977500\du,-5.367480\du)--(11.977500\du,-7.267480\du)--cycle; +\pgfsetlinewidth{0.040000\du} +\pgfsetdash{}{0pt} +\pgfsetdash{}{0pt} +\pgfsetmiterjoin +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\draw (-10.972500\du,-7.267480\du)--(-10.972500\du,-5.367480\du)--(11.977500\du,-5.367480\du)--(11.977500\du,-7.267480\du)--cycle; +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\node at (0.502500\du,-6.322480\du){User code}; +\pgfsetlinewidth{0.040000\du} +\pgfsetdash{}{0pt} +\pgfsetdash{}{0pt} +\pgfsetbuttcap +{ +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetfillcolor{dialinecolor} +\pgfsetarrowsstart{stealth} +\pgfsetarrowsend{stealth} +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\draw (8.149986\du,-5.159541\du)--(8.149986\du,-3.959543\du); +} +\pgfsetlinewidth{0.040000\du} +\pgfsetdash{}{0pt} +\pgfsetdash{}{0pt} +\pgfsetbuttcap +{ +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetfillcolor{dialinecolor} +\pgfsetarrowsstart{stealth} +\pgfsetarrowsend{stealth} +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\draw (-1.074995\du,-1.634548\du)--(-1.074995\du,-0.434550\du); +} +\pgfsetlinewidth{0.040000\du} +\pgfsetdash{}{0pt} +\pgfsetdash{}{0pt} +\pgfsetbuttcap +{ +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetfillcolor{dialinecolor} +\pgfsetarrowsstart{stealth} +\pgfsetarrowsend{stealth} +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\draw (8.138736\du,-1.618298\du)--(8.138736\du,-0.418300\du); +} +\pgfsetlinewidth{0.040000\du} +\pgfsetdash{}{0pt} +\pgfsetdash{}{0pt} +\pgfsetbuttcap +{ +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetfillcolor{dialinecolor} +\pgfsetarrowsstart{stealth} +\pgfsetarrowsend{stealth} +\definecolor{dialinecolor}{rgb}{0.000000, 0.000000, 0.000000} +\pgfsetstrokecolor{dialinecolor} +\draw (1.689638\du,1.881695\du)--(1.689638\du,3.081693\du); +} +\end{tikzpicture} +\endgroup +%</techdoc-block-diagram> +%<*techdoc-bibliography> +@book{tantau21, + author = {Till Tantau and Joseph Wright and Vedran Miletić}, + title = {The Beamer class}, + date = {2021-02-10}, + url = {https://mirrors.ctan.org/macros/latex/contrib/beamer/doc/beameruserguide.pdf}, + urldate = {2021-02-11}} +@online{sotkov17, + author = {Sotkov, Anton}, + title = {File transclusion syntax for Markdown}, + date = {2017-01-19}, + url = {https://github.com/iainc/Markdown-Content-Blocks}, + urldate = {2018-01-08}} +@book{luatex17, + author = {{Lua\TeX{} development team}}, + title = {Lua\TeX{} reference manual}, + year = {2017}, + month = {2}, + url = {http://www.luatex.org/svn/trunk/manual/luatex.pdf}, + urldate = {2018-01-08}} +@book{latex17, + author = {Braams, Johannes and Carlisle, David and Jeffrey, Alan and + Lamport, Leslie and Mittelbach, Frank and Rowley, Chris and + Schöpf, Rainer}, + title = {The \Hologo{LaTeX2e} Sources}, + date = {2017-04-15}, + url = {https://mirrors.ctan.org/macros/latex/base/source2e.pdf}, + urldate = {2018-01-08}} +@book{mittelbach17, + author = {Mittelbach, Frank}, + title = {The \texttt{doc} and \texttt{shortvrb} Packages}, + date = {2017-04-15}, + url = {https://mirrors.ctan.org/macros/latex/base/doc.pdf}, + urldate = {2018-02-19}} +@book{poore17, + author = {Poore, Geoffrey M.}, + title = {The \texttt{minted} Package}, + subtitle = {Highlighted source code in \LaTeX}, + date = {2017-07-19}, + version = {v2.5}, + url = {https://mirrors.ctan.org/macros/latex/contrib/minted/minted.pdf}, + urldate = {2020-09-01}} +@online{novotny15, + author = {Novotný, Vít}, + year = {2015}, + title = {TeXový interpret jazyka Markdown (markdown.sty)}, + location = {Brno, Czech Republic}, + publisher = {Masaryk University}, + url = {https://www.muni.cz/en/research/projects/32984}, + urldate = {2018-02-19}} +@book{ierusalimschy13, + author = {Ierusalimschy, Roberto}, + year = {2013}, + title = {Programming in Lua}, + edition = {3}, + isbn = {978-85-903798-5-0}, + pagetotal = {xviii, 347}, + location = {Rio de Janeiro}, + publisher = {PUC-Rio}} +@book{knuth86, + author = {Knuth, Donald Ervin}, + year = {1986}, + title = {The \TeX{}book}, + edition = {3}, + isbn = {0-201-13447-0}, + pagetotal = {ix, 479}, + publisher = {Addison-Wesley}} +@online{novotny21, + author = {Novotný, Vít}, + title = {\Hologo{LaTeX2e} no longer keys packages by pathnames}, + date = {2021-02-20}, + url = {https://github.com/latex3/latex2e/issues/510}, + urldate = {2021-02-21}} +%</techdoc-bibliography> +%<*latex-themes-witiko-markdown-techdoc> +\ProvidesPackage{markdownthemewitiko_markdown_techdoc}[2021/09/10] +\RequirePackage{etoolbox} +\markdownSetup{ + renderers = { + codeSpan = {\inline{#1}}, + link = {#1\footnote{See \url{#3}.}}, + headingFour = {% + \paragraph{#1}\leavevmode + \def\markdownRendererInterblockSeparator{% + \let\markdownRendererInterblockSeparator\par + }% + \noindent + }, + jekyllDataEnd = {% + \AfterEndPreamble{% + \printtitlepage + \tableofcontents + {\def\addcontentsline##1##2##3{}\listoffigures}% + }% + }, + }, +} +\markdownSetupSnippet{options}{ + renderers = { + dlBegin = {\begin{optionlist}}, + dlItem = { + #1 + \begingroup + \markdownSetup{ + renderers = { + dlBegin = { + \begingroup + \markdownSetup{ + renderers = { + dlItem = {\item[####1]}, + dlItemEnd = {}}} + \begin{valuelist} + }, + dlEnd = { + \end{valuelist} + \endgroup + }, + }, + }% + }, + dlItemEnd = {\endgroup}, + dlEnd = {\end{optionlist}}, + } +} +\RequirePackage{expl3} +\ExplSyntaxOn +\keys_define:nn + { markdown/jekyllData } + { + author .code:n = + { + \gdef\ltd@title@author { #1 } + \hypersetup{ pdfauthor = { #1 } } + }, + title .code:n = + { + \gdef\ltd@title@title { #1 } + \gdef\ltd@title@subtitle { } + \hypersetup{ pdftitle = { #1 } } + }, + date .code:n = { \gdef\ltd@title@date { #1 } }, + email .code:n = { \gdef\ltd@title@email { #1 } }, + revision .code:n = { \gdef\ltd@title@revision { #1 } }, + url .code:n = { \gdef\ltd@title@url { #1 } }, + } +\ExplSyntaxOff +%</latex-themes-witiko-markdown-techdoc> %<*manual> --- title: Markdown Package User Manual author: Vít Novotný -date: v\markdownVersion{} (\markdownLastModified{}) +date: \markdownVersion{} (\markdownLastModified{}) --- % \fi @@ -564,7 +830,7 @@ functionality is provided both as a Lua module and as plain \TeX{}, \LaTeX{}, an 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. ;-) +syntax is encouraged. 😉 [markdown]: https://daringfireball.net/projects/markdown/basics (Daring Fireball: Markdown Basics) @@ -573,8 +839,8 @@ syntax is encouraged. ;-) % This document is a technical documentation for the \pkg{Markdown} package. It % consists of three sections. This section introduces the package and outlines -% its prerequisites. Section \ref{sec:interfaces} describes the interfaces -% exposed by the package. Section \ref{sec:implementation} describes the +% its prerequisites. Section \vref{sec:interfaces} describes the interfaces +% exposed by the package. Section \vref{sec:implementation} describes the % implementation of the package. The technical documentation contains only a % limited number of tutorials and code examples. You can find more of these in % the [user manual.][manual] @@ -597,12 +863,12 @@ documentation][techdoc]. % \fi % \begin{macrocode} local metadata = { - version = "2.10.1", + version = "$(VERSION)", comment = "A module for the conversion from markdown to plain TeX", author = "John MacFarlane, Hans Hagen, Vít Novotný", copyright = {"2009-2016 John MacFarlane, Hans Hagen", "2016-2021 Vít Novotný"}, - license = "LPPL 1.3" + license = "LPPL 1.3c" } % \end{macrocode} @@ -614,33 +880,6 @@ local metadata = { if not modules then modules = { } end modules['markdown'] = metadata % \end{macrocode} -% \par -% \begin{markdown} -% -% Feedback -%--------- -% Please use the \pkg{Markdown} project page on -% [GitHub](https://github.com/witiko/markdown/issues) to report bugs and submit -% feature requests. If you do not want to report a bug or request a feature but -% are simply in need of assistance, you might want to consider posting your -% question on the [\TeX-\LaTeX{} Stack Exchange.](https://tex.stackexchange.com) -% -% Acknowledgements -%----------------- -% The Lunamark Lua module provides speedy markdown parsing for the package. I -% would like to thank John Macfarlane, the creator of Lunamark, for releasing -% Lunamark under a permissive license. -% -% Funding by the the Faculty of Informatics at the Masaryk~University -% in~Brno~[@novotny15] is gratefully acknowledged. -% -% The \TeX{} implementation of the package draws inspiration from several -% sources including the source code of \Hologo{LaTeX2e}, the \pkg{minted} -% package by Geoffrey M. Poore, which likewise tackles the issue of -% interfacing with an external interpreter from \TeX{}, the \pkg{filecontents} -% package by Scott Pakin and others. -% -% \end{markdown} % \iffalse %</lua> %<*manual> @@ -648,36 +887,38 @@ modules['markdown'] = metadata Requirements ------------ -The package requires a working \TeX{} distribution. [\TeX{} Live][tl] ≥ 2013 is -known to work and so are recent installation of [Mik\TeX{}][mik]. If you are -using a minimal installation of a \TeX{} distribution, please consult the -[technical documentation][techdoc] for a detailed list of required packages. +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 ------------ -The package comes pre-installed with [\TeX{} Live][tl] ≥ 2016 and with recent -installations of [MikTeX][mik]. Unless you explicitly wish to use the latest -version of the package, you are encouraged to skip this step. +If Markdown is not included in your \TeX{} distribution, you will need to +install it. -To install the package, first download the package from the repository -using Git: +First, download the package from the repository using Git: ``` sh git clone https://github.com/witiko/markdown `````` -Next, enter the directory named `markdown` and interpret the file named -`markdown.ins` file using a Unicode-aware \TeX{} engine, such as XeTeX or -LuaTeX: +Next, enter the directory named `markdown` and run the `make base` command using +GNU Make: ``` sh cd markdown -luatex markdown.ins +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, @@ -692,16 +933,17 @@ 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>/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 + * `⟨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. @@ -788,7 +1030,14 @@ local md5 = require("md5") % \begin{markdown} % % All the abovelisted modules are statically linked into the current version of -% the Lua\TeX{} engine~[@luatex17, Section 3.3]. +% the Lua\TeX{} engine~[@luatex17, Section 3.3]. Beside these, we also carry +% the following third-party Lua libraries: +% +% \pkg{api7/lua-tinyyaml} +% +%: A library that provides a regex-based recursive descent \acro{yaml} +% (subset) parser that is used to read \acro{yaml} metadata when the +% \Opt{jekyllData} option is enabled. % % \end{markdown} % \iffalse @@ -802,17 +1051,17 @@ local md5 = require("md5") % \label{sec:texprerequisites} % The plain \TeX{} part of the package requires that the plain \TeX{} % format (or its superset) is loaded, all the Lua prerequisites (see -% Section \ref{sec:luaprerequisites}), and the following Lua module: +% Section \vref{sec:luaprerequisites}), and the following Lua module: % % \pkg{Lua File System} % %: A library that provides access to the filesystem via \acro{os}-specific % syscalls. It is used by the plain \TeX{} code to create the cache -% directory specified by the \m{markdownOptionCacheDir} macro before +% directory specified by the \mref{markdownOptionCacheDir} macro before % interfacing with the \pkg{Lunamark} library. \pkg{Lua File System} is % included in all releases of Lua\TeX{} (\TeX Live${}\geq{}2008$). % -% The plain \TeX{} code makes use of the \luam{isdir} method that was added +% The plain \TeX{} code makes use of the \luamref{isdir} method that was added % to the \pkg{Lua File System} library by the Lua\TeX{} engine % developers~[@luatex17, Section 3.2]. % @@ -820,12 +1069,12 @@ local md5 = require("md5") % engine~[@luatex17, Section~3.3]. % % Unless you convert markdown documents to \TeX{} manually using the Lua -% command-line interface (see Section~\ref{sec:lua-cli-interface}), the plain +% command-line interface (see Section \vref{sec:lua-cli-interface}), the plain % \TeX{} part of the package will require that either the Lua\TeX{} -% \m{directlua} primitive or the shell access file stream 18 is available in +% \mref{directlua} primitive or the shell access file stream 18 is available in % your \TeX{} engine. If only the shell access file stream is available in your % \TeX{} engine (as is the case with \hologo{pdfTeX} and \Hologo{XeTeX}) or if -% you enforce the use of shell using the \m{markdownMode} macro, then unless +% you enforce the use of shell using the \mref{markdownMode} macro, then unless % your \TeX{} engine is globally configured to enable shell access, you will % need to provide the `-shell-escape` parameter to your engine when typesetting % a document. @@ -854,14 +1103,14 @@ local md5 = require("md5") % \fi % \begin{markdown} % a \TeX{} engine that extends \Hologo{eTeX}, all the plain \TeX{} -% prerequisites (see Section \ref{sec:texprerequisites}), and the following +% prerequisites (see Section \vref{sec:texprerequisites}), and the following % \Hologo{LaTeX2e} packages: % % \pkg{keyval} % %: A package that enables the creation of parameter sets. This package is -% used to provide the \m{markdownSetup} macro, the package options -% processing, as well as the parameters of the \envm{markdown*} \LaTeX{} +% used to provide the \mref{markdownSetup} macro, the package options +% processing, as well as the parameters of the \envmref{markdown*} \LaTeX{} % environment. % % \end{markdown} @@ -882,56 +1131,85 @@ local md5 = require("md5") % \par % \begin{markdown} % -% The following packages are soft prerequisites and will not be loaded -% if the `plain` package option has been enabled (see Section -% \ref{sec:latexplain}): +% The following packages are soft prerequisites. They are only used to provide +% default token renderer prototypes (see sections +% \vref{sec:texrendererprototypes} and +% \vref{sec:latexdefaultrendererprototypes}) or \LaTeX{} themes (see Section +% \vref{sec:latexthemes}) and will not be loaded if the `plain` package option +% has been enabled (see Section \vref{sec:latexplain}): % % \pkg{url} % -%: A package that provides the \m{url} macro for the typesetting of -% \acro{url}s. It is used to provide the default token renderer -% prototype (see Section \ref{sec:texrendererprototypes}) for links. +%: A package that provides the \mref{url} macro for the typesetting of +% links. % % \pkg{graphicx} % -%: A package that provides the \m{includegraphics} macro for the typesetting -% of images. It is used to provide the corresponding default token renderer -% prototype (see Section \ref{sec:texrendererprototypes}). +%: A package that provides the \mref{includegraphics} macro for the typesetting +% of images. % % \pkg{paralist} % -%: A package that provides the \envm{compactitem}, \envm{compactenum}, and -% \envm{compactdesc} macros for the typesetting of tight bulleted lists, -% ordered lists, and definition lists. It is used to provide the -% corresponding default token renderer prototypes (see Section -% \ref{sec:texrendererprototypes}). +%: A package that provides the \envmref{compactitem}, \envmref{compactenum}, and +% \envmref{compactdesc} macros for the typesetting of tight bulleted lists, +% ordered lists, and definition lists. % % \pkg{ifthen} % %: A package that provides a concise syntax for the inspection of macro % values. It is used to determine whether or not the \pkg{paralist} package % should be loaded based on the user options, in the `witiko/dot` \LaTeX{} -% theme (see Section \ref{sec:latexthemes}), and to provide default token -% renderer prototypes (see Section \ref{sec:texrendererprototypes}). +% theme (see Section \vref{sec:latexthemes}), and to provide default token +% renderer prototypes. % % \pkg{fancyvrb} % -%: A package that provides the \m{VerbatimInput} macros for the verbatim -% inclusion of files containing code. It is used to provide the -% corresponding default token renderer prototype (see Section -% \ref{sec:texrendererprototypes}). +%: A package that provides the \mref{VerbatimInput} macros for the verbatim +% inclusion of files containing code. % % \pkg{csvsimple} % -%: A package that provides the default token renderer prototype for -% iA\,Writer content blocks with the \acro{csv} filename extension (see -% Section \ref{sec:texrendererprototypes}). +%: A package that provides the \mref{csvautotabular} macro for typesetting +% \acro{csv} files in the default renderer prototypes for iA\,Writer +% content blocks. % % \pkg{gobble} % -%: A package that provides the \m{\@gobblethree} \TeX{} command that -% is used in the default renderer prototype for citations (see -% Section \ref{sec:texrendererprototypes}). +%: A package that provides the \mref{\@gobblethree} \TeX{} command that +% is used in the default renderer prototype for citations. The package +% is included in \TeX Live${}\geq{}2016$. +% +% \pkg{amsmath} and \pkg{amssymb} +% +%: Packages that provide symbols used for drawing ticked and unticked +% boxes. +% +% \pkg{catchfile} +% +%: A package that catches the contents of a file and puts it in a macro. It +% is used in the `witiko/graphicx/http` \LaTeX{} theme, see Section +% \vref{sec:latexthemes}. +% +% \pkg{grffile} +% +%: A package that extends the name processing of package graphics to support +% a larger range of file names in $2006\leq{}$\TeX{} Live${}\leq{}2019$. +% Since \TeX{} Live${}\geq{}2020$, the functionality of the package has +% been integrated in the \LaTeXe{} kernel. It is used in the `witiko/dot` +% and `witiko/graphicx/http` \LaTeX{} themes, see Section +% \vref{sec:latexthemes}. +% +% \pkg{etoolbox} +% +%: A package that is used to polyfill the general hook management system in +% the default renderer prototypes for \acro{yaml} metadata, see Section +% \ref{sec:latexyamlmetadata}. +% +% \pkg{expl3} +% +%: A package that enables the expl3 language from the \LaTeX3 kernel in +% \TeX{} Live${}\leq{}2019$. It is used in the default renderer prototypes +% for \acro{yaml} metadata, see Section \ref{sec:latexyamlmetadata}. % % \end{markdown} % \iffalse @@ -944,14 +1222,46 @@ local md5 = require("md5") %### \Hologo{ConTeXt} Prerequisites % The \Hologo{ConTeXt} part of the package requires that either the Mark II or % the Mark IV format is loaded, all the plain \TeX{} prerequisites (see -% Section \ref{sec:texprerequisites}), and the following \Hologo{ConTeXt} +% Section \vref{sec:texprerequisites}), and the following \Hologo{ConTeXt} % modules: % % \pkg{m-database} % %: A module that provides the default token renderer prototype for % iA\,Writer content blocks with the \acro{csv} filename extension (see -% Section \ref{sec:texrendererprototypes}). +% Section \vref{sec:texrendererprototypes}). +% +% Feedback +%--------- +% Please use the \pkg{Markdown} project page on +% [GitHub](https://github.com/witiko/markdown/issues) to report bugs and submit +% feature requests. If you do not want to report a bug or request a feature but +% are simply in need of assistance, you might want to consider posting your +% question to the [\TeX-\LaTeX{} Stack Exchange.](https://tex.stackexchange.com) +% community question answering web site under the `markdown` tag. +% +% Acknowledgements +%----------------- +% The Lunamark Lua module provides speedy markdown parsing for the package. I +% would like to thank John Macfarlane, the creator of Lunamark, for releasing +% Lunamark under a permissive license, which enabled its use in the Markdown +% package. +% +% Extensive user documentation for the Markdown package was kindly written by +% Lian Tze Lim and published by Overleaf. +% +% Funding by the the Faculty of Informatics at the Masaryk~University +% in~Brno~[@novotny15] is gratefully acknowledged. +% +% Support for content slicing (Lua options \Opt{shiftHeadings} and \Opt{slice}) +% and pipe tables (Lua options \Opt{pipeTables} and \Opt{tableCaptions}) was +% graciously sponsored by David Vins and Omedym. +% +% The \TeX{} implementation of the package draws inspiration from several +% sources including the source code of \Hologo{LaTeX2e}, the \pkg{minted} +% package by Geoffrey M. Poore, which likewise tackles the issue of +% interfacing with an external interpreter from \TeX{}, the \pkg{filecontents} +% package by Scott Pakin and others. % % Interfaces %=========== @@ -960,12 +1270,25 @@ local md5 = require("md5") % along with usage notes and examples. It is aimed at the user of the package. % % Since neither \TeX{} nor Lua provide interfaces as a language construct, the -% separation to interfaces and implementations is purely abstract. It serves as -% a means of structuring this documentation and as a promise to the user that -% if they only access the package through the interface, the future minor -% versions of the package should remain backwards compatible. -% -% \end{markdown} +% separation to interfaces and implementations is a *gentlemen's agreement*. It +% serves as a means of structuring this documentation and as a promise to the +% user that if they only access the package through the interface, the future +% minor versions of the package should remain backwards compatible. +% +% Figure \vref{fig:block-diagram} shows the high-level structure of the Markdown +% package: The translation from markdown to \TeX{} *token renderers* is exposed +% by the Lua layer. The plain \TeX{} layer exposes the conversion capabilities +% of Lua as \TeX{} macros. The \LaTeX{} and \Hologo{ConTeXt} layers provide +% syntactic sugar on top of plain \TeX{} macros. The user can interface with +% any and all layers. +% +% \end{markdown} +% \begin{figure} +% \centering +% \input markdown-figure-block-diagram +% \caption{A block diagram of the \pkg{Markdown} package} +% \label{fig:block-diagram} +% \end{figure} % \iffalse %</context> %<*manual> @@ -977,6 +1300,15 @@ 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 @@ -1145,7 +1477,7 @@ 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]: http://mirrors.ctan.org/macros/generic/markdown/markdown.pdf + [techdoc]: https://mirrors.ctan.org/macros/generic/markdown/markdown.pdf (A Markdown Interpreter for \TeX{}) /markdown-interfaces.md @@ -1191,7 +1523,7 @@ module and a command-line interface (CLI). % % The Lua interface provides the conversion from \acro{utf}-\oldstylenums8 % encoded markdown to plain \TeX{}. This interface is used by the plain \TeX{} -% implementation (see Section \ref{sec:teximplementation}) and will be of +% implementation (see Section \vref{sec:teximplementation}) and will be of % interest to the developers of other packages and Lua modules. % % The Lua interface is implemented by the `markdown` Lua module. @@ -1208,7 +1540,7 @@ local M = {metadata = metadata} % The Lua interface exposes the \luamdef{new}`(options)` method. This % method creates converter functions that perform the conversion from markdown % to plain \TeX{} according to the table `options` that contains options -% recognized by the Lua interface. (see Section \ref{sec:luaoptions}). The +% recognized by the Lua interface. (see Section \vref{sec:luaoptions}). The % `options` parameter is optional; when unspecified, the behaviour will be % the same as if `options` were an empty table. % @@ -1402,26 +1734,7 @@ package. local defaultOptions = {} % \end{macrocode} % \begingroup -% \markdownSetup{ -% renderers = { -% dlBegin = {\begin{optionlist}}, -% dlItem = { -% #1 -% \begingroup -% \markdownSetup{ -% renderers = { -% dlBegin = { -% \begingroup -% \markdownSetup{ -% renderers = { -% dlItem = {\item[####1]}, -% dlItemEnd = {}}} -% \begin{valuelist}}, -% dlEnd = { -% \end{valuelist} -% \endgroup}}}}, -% dlItemEnd = {\endgroup}, -% dlEnd = {\end{optionlist}}}} +% \markdownSetup{snippet=witiko/markdown/techdoc/options} % \par % \iffalse %</lua,lua-cli> @@ -1608,7 +1921,7 @@ defaultOptions.cacheDir = "." The frozen cache makes it possible to later typeset a plain \TeX{} document that contains markdown documents without invoking Lua using - the \m{markdownOptionFrozenCache} plain \TeX{} option. As a result, the + the \mref{markdownOptionFrozenCache} plain \TeX{} option. As a result, the plain \TeX{} document becomes more portable, but further changes in the order and the content of markdown documents will not be reflected. @@ -3257,7 +3570,7 @@ defaultOptions.contentBlocks = false % : The filename of the JSON file that maps filename extensions to programming language names in the iA\,Writer content blocks. -% See Section~\ref{sec:texcontentblockrenderers} for more information. +% See Section \vref{sec:texcontentblockrenderers} for more information. % \end{markdown} % \iffalse @@ -3698,7 +4011,7 @@ defaultOptions.fencedCode = false The frozen cache makes it possible to later typeset a plain \TeX{} document that contains markdown documents without invoking Lua using - the \m{markdownOptionFrozenCache} plain \TeX{} option. As a result, the + the \mref{markdownOptionFrozenCache} plain \TeX{} option. As a result, the plain \TeX{} document becomes more portable, but further changes in the order and the content of markdown documents will not be reflected. @@ -4471,7 +4784,7 @@ defaultOptions.html = false #### Option `hybrid` -`hybrid` (default value: `true`) +`hybrid` (default value: `false`) % \fi % \begin{markdown} @@ -4759,6 +5072,146 @@ defaultOptions.inlineFootnotes = false %</lua,lua-cli> %<*manual-options> +#### Option `jekyllData` + +`jekyllData` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{jekyllData}{\opt{true}, \opt{false}} +% +: true + + : Enable the Pandoc `yaml_metadata_block` syntax extension for entering + metadata in \acro{yaml}: + + ~~~~~~ yaml + --- + title: 'This is the title: it contains a colon' + author: + - Author One + - Author Two + keywords: [nothing, nothingness] + abstract: | + This is the abstract. + + It consists of two paragraphs. + --- + ~~~~~~~~~~~ + +: false + + : Disable the Pandoc `yaml_metadata_block` syntax extension for entering + metadata in \acro{yaml}. + +% \end{markdown} +% \iffalse + +##### Plain \TeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\def\markdownOptionJekyllData{true} +\def\markdownRendererJekyllDataString#1#2{\gdef\name{#2}} +\def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}} +\def\markdownRendererJekyllDataEnd{% + \name{} is \age{} years old.} +\markdownBegin +--- +name: Jane Doe +age: 99 +--- +\markdownEnd +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Jane Doe is 99 years old. + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[jekyllData]{markdown} +\markdownSetup{ + renderers = { + jekyllDataString = {\gdef\name{#2}}, + jekyllDataNumber = {\gdef\age{#2}}, + jekyllDataEnd = {\name{} is \age{} years old.}, + } +} +\begin{document} + +\begin{markdown} +--- +name: Jane Doe +age: 99 +--- +\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 +following text: + +> Jane Doe is 99 years old. + +##### \Hologo{ConTeXt} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownOptionJekyllData{true} +\def\markdownRendererJekyllDataString#1#2{\gdef\name{#2}} +\def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}} +\def\markdownRendererJekyllDataEnd{% + \name{} is \age{} years old.} +\starttext + +\startmarkdown +--- +name: Jane Doe +age: 99 +--- +\stopmarkdown + +\stoptext +``````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Jane Doe is 99 years old. + +%</manual-options> +%<*lua,lua-cli> +% \fi +% \begin{macrocode} +defaultOptions.jekyllData = false +% \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual-options> + #### Option `pipeTables` {#pipe-tables} `pipeTables` (default value: `false`) @@ -5244,7 +5697,7 @@ defaultOptions.slice = "^ $" : true : Convert any ellipses in the input to the - \m{markdownRendererEllipsis} \TeX{} macro. + \mref{markdownRendererEllipsis} \TeX{} macro. : false @@ -5442,12 +5895,12 @@ defaultOptions.smartEllipses = false : Make the number in the first item of an ordered lists significant. The item numbers will be passed to the - \m{markdownRendererOlItemWithNumber} \TeX{} macro. + \mref{markdownRendererOlItemWithNumber} \TeX{} macro. : false : Ignore the numbers in the ordered list items. Each item will only - produce a \m{markdownRendererOlItem} \TeX{} macro. + produce a \mref{markdownRendererOlItem} \TeX{} macro. % \end{markdown} % \iffalse @@ -5687,7 +6140,7 @@ defaultOptions.stripIndent = false : false - : Enable the Pandoc `table_captions` syntax extension. + : Disable the Pandoc `table_captions` syntax extension. % \end{markdown} % \iffalse @@ -5772,6 +6225,106 @@ defaultOptions.tableCaptions = false %</lua,lua-cli> %<*manual-options> +#### Option `taskLists` + +`taskLists` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{taskLists}{\opt{true}, \opt{false}} +% +: true + + : Enable the Pandoc `task_lists` syntax extension. + + + ``` md + - [ ] an unticked task list item + - [/] a half-checked task list item + - [X] a ticked task list item + `````` + +: false + + : Disable the Pandoc `task_lists` syntax extension. + +% \end{markdown} +% \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[taskLists]{markdown} +\markdownSetup{ + renderers = { + untickedBox = No, + halfTickedBox = Maybe, + tickedBox = Yes, + }, +} +\begin{document} +\begin{markdown} +- [ ] you can't. +- [/] I can? +- [X] I can! +\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 +following text: + +> - No you can't. +> - Maybe I can? +> - Yes I can! + +##### \Hologo{ConTeXt} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownOptionTaskLists{true} +\def\markdownRendererUntickedBox{No} +\def\markdownRendererHalftickedBox{Maybe} +\def\markdownRendererTickedBox{Yes} +\starttext +\startmarkdown +- [ ] you can't. +- [/] I can? +- [X] I can! +\stopmarkdown +\stoptext +```````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> - No you can't. +> - Maybe I can? +> - Yes I can! + +%</manual-options> +%<*lua,lua-cli> +% \fi +% \begin{macrocode} +defaultOptions.taskLists = false +% \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual-options> + #### Option `texComments` `texComments` (default value: `false`) @@ -5892,10 +6445,10 @@ defaultOptions.texComments = false : Lists whose bullets do not consist of multiple paragraphs will be passed to the - \m{markdownRendererOlBeginTight}, \m{markdownRendererOlEndTight}, - \m{markdownRendererUlBeginTight}, \m{markdownRendererUlEndTight}, - \m{markdownRendererDlBeginTight}, and - \m{markdownRendererDlEndTight} \TeX{} macros. + \mref{markdownRendererOlBeginTight}, \mref{markdownRendererOlEndTight}, + \mref{markdownRendererUlBeginTight}, \mref{markdownRendererUlEndTight}, + \mref{markdownRendererDlBeginTight}, and + \mref{markdownRendererDlEndTight} \TeX{} macros. : false @@ -6117,11 +6670,61 @@ defaultOptions.underscores = true % %### Command-Line Interface % \label{sec:lua-cli-interface} -% To provide finer control over the conversion and to simplify debugging, a -% command-line Lua interface for converting a Markdown document to \TeX{} is -% also provided. -% -% \end{markdown} +% The high-level operation of the Markdown package involves the communication +% between several programming layers: the plain \TeX{} layer hands markdown +% documents to the Lua layer. Lua converts the documents to \TeX{}, and hands +% the converted documents back to plain \TeX{} layer for typesetting, see +% Figure \vref{fig:sequence-diagram-tex-interface}. +% +% This procedure has the advantage of being fully automated. However, it also +% has several important disadvantages: The converted \TeX{} documents are +% cached on the file system, taking up increasing amount of space. Unless the +% \TeX{} engine includes a Lua interpreter, the package also requires shell +% access, which opens the door for a malicious actor to access the system. +% Last, but not least, the complexity of the procedure impedes debugging. +% +% A solution to the above problems is to decouple the conversion from the +% typesetting. For this reason, a command-line Lua interface for converting a +% markdown document to \TeX{} is also provided, see +% Figure \vref{fig:sequence-diagram-lua-cli}. +% +% \end{markdown} +% \begin{figure} +% \centering +% \begin{sequencediagram} +% \newthread{user}{User}{} +% \newinst[4]{tex}{\TeX{}}{} +% \newinst[4]{lua}{Lua}{} +% \begin{call}{user}{\footnotesize\cs{jobname.tex}}{tex}{\footnotesize\cs{jobname.pdf}} +% \begin{call}{tex}{\footnotesize\cs{jobname.markdown.in}}{lua}{\footnotesize\cs{jobname.markdown.out}} +% \end{call} +% \begin{call}{tex}{\footnotesize\cs{input}\cs{jobname.markdown.out}}{tex}{} +% \end{call} +% \end{call} +% \end{sequencediagram} +% \caption[A sequence diagram of typesetting a document using the \TeX{} +% interface]{A sequence diagram of the Markdown package typesetting a +% markdown document using the \TeX{} interface} +% \label{fig:sequence-diagram-tex-interface} +% \end{figure} +% \begin{figure} +% \centering +% \begin{sequencediagram} +% \newthread{user}{User}{} +% \newinst[4]{tex}{\TeX{}}{} +% \newinst[4]{lua}{Lua}{} +% \begin{call}{user}{\footnotesize$\langle$\textit{document}$\rangle$\texttt{.md}}{lua}{\footnotesize$\langle$\textit{document}$\rangle$\texttt{.tex}} +% \end{call} +% \begin{call}{user}{\footnotesize\cs{jobname.tex}}{tex}{\footnotesize\cs{jobname.pdf}} +% \begin{call}{tex}{\footnotesize\cs{input} $\langle$\textit{document}$\rangle$}{tex}{} +% \end{call} +% \end{call} +% \end{sequencediagram} +% \caption[A sequence diagram of typesetting a document using the Lua CLI]% +% {A sequence diagram of the Markdown package typesetting a markdown document +% using the Lua command-line interface} +% \label{fig:sequence-diagram-lua-cli} +% \end{figure} % \begin{macrocode} HELP_STRING = [[ @@ -6173,14 +6776,14 @@ for i = 1, #arg do % Unless the `-`{}`-` argument has been specified before, an argument % containing the equals sign (`=`) is assumed to be an option specification in % a \meta{key}`=`\meta{value} format. The available options are listed in -% Section~\ref{sec:luaoptions}. +% Section \vref{sec:luaoptions}. % \end{markdown} % \begin{macrocode} elseif arg[i]:match("=") then key, value = arg[i]:match("(.-)=(.*)") % \end{macrocode} % \begin{markdown} -% The \luam{defaultOptions} table is consulted to identify whether \meta{value} +% The \luamref{defaultOptions} table is consulted to identify whether \meta{value} % should be parsed as a string or as a boolean. % \end{markdown} % \begin{macrocode} @@ -6264,10 +6867,6 @@ end % \input hello % ``````` % -% This shows another advantage of using the command-line interface compared to -% using a higher-level \TeX{} interface: it is unnecessary to provide shell -% access for the \TeX{} engine. -% % \end{markdown} % \iffalse %</lua-cli> @@ -6335,13 +6934,13 @@ pdftex --shell-escape document.tex % % The plain \TeX{} interface provides macros for the typesetting of markdown % input from within plain \TeX{}, for setting the Lua interface options (see -% Section \ref{sec:luaoptions}) used during the conversion from markdown to +% Section \vref{sec:luaoptions}) used during the conversion from markdown to % plain \TeX{} and for changing the way markdown the tokens are rendered. % % \end{markdown} % \begin{macrocode} -\def\markdownLastModified{2021/08/31}% -\def\markdownVersion{2.10.1}% +\def\markdownLastModified{$(LAST_MODIFIED)}% +\def\markdownVersion{$(VERSION)}% % \end{macrocode} % \par % \begin{markdown} @@ -6352,15 +6951,15 @@ pdftex --shell-escape document.tex % \input markdown % ``````` % \noindent It is expected that the special plain \TeX{} characters have the -% expected category codes, when \m{input}ting the file. +% expected category codes, when \mref{input}ting the file. % %### Typesetting Markdown % \label{sec:textypesetting} % The interface exposes the \mdef{markdownBegin}, \mdef{markdownEnd}, and % \mdef{markdownInput} macros. % -% The \m{markdownBegin} macro marks the beginning of a markdown document -% fragment and the \m{markdownEnd} macro marks its end. +% The \mref{markdownBegin} macro marks the beginning of a markdown document +% fragment and the \mref{markdownEnd} macro marks its end. % % \end{markdown} % \begin{macrocode} @@ -6370,24 +6969,24 @@ pdftex --shell-escape document.tex % \par % \begin{markdown} % -% You may prepend your own code to the \m{markdownBegin} macro and redefine the -% \m{markdownEnd} macro to produce special effects before and after the +% You may prepend your own code to the \mref{markdownBegin} macro and redefine the +% \mref{markdownEnd} macro to produce special effects before and after the % markdown block. % % There are several limitations to the macros you need to be aware of. -% The first limitation concerns the \m{markdownEnd} macro, which must be +% The first limitation concerns the \mref{markdownEnd} macro, which must be % visible directly from the input line buffer (it may not be produced as a % result of input expansion). Otherwise, it will not be recognized as the end -% of the markdown string. As a corrolary, the \m{markdownEnd} string +% of the markdown string. As a corrolary, the \mref{markdownEnd} string % may not appear anywhere inside the markdown input. % % Another limitation concerns spaces at the right end of an input line. In % markdown, these are used to produce a forced line break. However, any such % spaces are removed before the lines enter the input buffer of -% \TeX{}~[@knuth86, p. 46]. As a corrolary, the \m{markdownBegin} macro also +% \TeX{}~[@knuth86, p. 46]. As a corrolary, the \mref{markdownBegin} macro also % ignores them. % -% The \m{markdownBegin} and \m{markdownEnd} macros will also consume the rest +% The \mref{markdownBegin} and \mref{markdownEnd} macros will also consume the rest % of the lines at which they appear. In the following example plain \TeX{} % code, the characters `c`, `e`, and `f` will not appear in the output. % @@ -6401,11 +7000,11 @@ pdftex --shell-escape document.tex % \bye % ``````` % -% Note that you may also not nest the \m{markdownBegin} and \m{markdownEnd} +% Note that you may also not nest the \mref{markdownBegin} and \mref{markdownEnd} % macros. % % The following example plain \TeX{} code showcases the usage of the -% \m{markdownBegin} and \m{markdownEnd} macros: +% \mref{markdownBegin} and \mref{markdownEnd} macros: % % ``` tex % \input markdown @@ -6415,7 +7014,7 @@ pdftex --shell-escape document.tex % \bye % ``````` % -% The \m{markdownInput} macro accepts a single parameter containing the +% The \mref{markdownInput} macro accepts a single parameter containing the % filename of a markdown document and expands to the result of the conversion % of the input markdown document to plain \TeX{}. % @@ -6427,10 +7026,10 @@ pdftex --shell-escape document.tex % \begin{markdown} % % This macro is not subject to the abovelisted limitations of the -% \m{markdownBegin} and \m{markdownEnd} macros. +% \mref{markdownBegin} and \mref{markdownEnd} macros. % % The following example plain \TeX{} code showcases the usage of the -% \m{markdownInput} macro: +% \mref{markdownInput} macro: % % ``` tex % \input markdown @@ -6443,7 +7042,7 @@ pdftex --shell-escape document.tex % % The plain \TeX{} options are represented by \TeX{} commands. Some of them map % directly to the options recognized by the Lua interface (see -% Section~\ref{sec:luaoptions}), while some of them are specific to the plain +% Section \vref{sec:luaoptions}), while some of them are specific to the plain % \TeX{} interface. % % \end{markdown} @@ -6467,7 +7066,7 @@ interfaces. %#### Finalizing and Freezing the Cache % The \mdef{markdownOptionFinalizeCache} option corresponds to the Lua % interface \Opt{finalizeCache} option, which creates an output file -% \m{markdownOptionFrozenCacheFileName} (frozen cache) that contains a mapping +% \mref{markdownOptionFrozenCacheFileName} (frozen cache) that contains a mapping % between an enumeration of the markdown documents in the plain \TeX{} document % and their auxiliary files cached in the \Opt{cacheDir} directory. % @@ -6486,7 +7085,7 @@ interfaces. % \begin{markdown} % The \mdef{markdownOptionFrozenCache} option uses the mapping previously -% created by the \m{markdownOptionFinalizeCache} option, +% created by the \mref{markdownOptionFinalizeCache} option, % \iffalse created by the Lua interface \Opt{finalizeCache} option, % \fi @@ -6497,18 +7096,18 @@ defaults to `false`. % The standard usage of the above two options is as follows: % \iffalse -The standard usage of the \Opt{finalizeCache} and \m{markdownOptionFrozenCache} +The standard usage of the \Opt{finalizeCache} and \mref{markdownOptionFrozenCache} options is as follows: % \fi 1. Remove the \Opt{cacheDir} cache directory with stale auxiliary cache files. -% 2. Enable the \m{markdownOptionFinalizeCache} option. +% 2. Enable the \mref{markdownOptionFinalizeCache} option. % \iffalse 2. Enable the \Opt{finalizeCache} option. % \fi 3. Typeset the plain \TeX{} document to populate and finalize the cache. -4. Enable the \m{markdownOptionFrozenCache} option. +4. Enable the \mref{markdownOptionFrozenCache} option. 5. Publish the source code of the plain \TeX{} document and the \Opt{cacheDir} directory. @@ -6527,13 +7126,13 @@ For more information, see the examples for the \Opt{finalizeCache} option. % % The \mdef{markdownOptionHelperScriptFileName} macro sets the filename of the % helper Lua script file that is created during the conversion from markdown to -% plain \TeX{} in \TeX{} engines without the \m{directlua} primitive. It -% defaults to \m{jobname}`.markdown.lua`, where \m{jobname} is the base name +% plain \TeX{} in \TeX{} engines without the \mref{directlua} primitive. It +% defaults to \mref{jobname}`.markdown.lua`, where \mref{jobname} is the base name % of the document being typeset. % % The expansion of this macro must not contain quotation marks (`"`) or % backslash symbols (`\`). Mind that \TeX{} engines tend to -% put quotation marks around \m{jobname}, when it contains spaces. +% put quotation marks around \mref{jobname}, when it contains spaces. % % \end{markdown} % \begin{macrocode} @@ -6544,9 +7143,9 @@ For more information, see the examples for the \Opt{finalizeCache} option. % % The \mdef{markdownOptionInputTempFileName} macro sets the filename of the % temporary input file that is created during the conversion from markdown to -% plain \TeX{} in \m{markdownMode} other than `2`. It defaults to -% \m{jobname}`.markdown.out`. The same limitations as in the case of the -% \m{markdownOptionHelperScriptFileName} macro apply here. +% plain \TeX{} in \mref{markdownMode} other than `2`. It defaults to +% \mref{jobname}`.markdown.out`. The same limitations as in the case of the +% \mref{markdownOptionHelperScriptFileName} macro apply here. % % \end{markdown} % \begin{macrocode} @@ -6557,9 +7156,9 @@ For more information, see the examples for the \Opt{finalizeCache} option. % % The \mdef{markdownOptionOutputTempFileName} macro sets the filename of the % temporary output file that is created during the conversion from markdown to -% plain \TeX{} in \m{markdownMode} other than `2`. It defaults to -% \m{jobname}`.markdown.out`. The same limitations apply here as in the case -% of the \m{markdownOptionHelperScriptFileName} macro. +% plain \TeX{} in \mref{markdownMode} other than `2`. It defaults to +% \mref{jobname}`.markdown.out`. The same limitations apply here as in the case +% of the \mref{markdownOptionHelperScriptFileName} macro. % % \end{markdown} % \begin{macrocode} @@ -6570,9 +7169,9 @@ For more information, see the examples for the \Opt{finalizeCache} option. % % The \mdef{markdownOptionErrorTempFileName} macro sets the filename of the % temporary output file that is created when a Lua error is encountered during -% the conversion from markdown to plain \TeX{} in \m{markdownMode} other than -% `2`. It defaults to \m{jobname}`.markdown.err`. The same limitations -% apply here as in the case of the \m{markdownOptionHelperScriptFileName} +% the conversion from markdown to plain \TeX{} in \mref{markdownMode} other than +% `2`. It defaults to \mref{jobname}`.markdown.err`. The same limitations +% apply here as in the case of the \mref{markdownOptionHelperScriptFileName} % macro. % % \end{markdown} @@ -6591,7 +7190,7 @@ For more information, see the examples for the \Opt{finalizeCache} option. % your \TeX{} engine for the package to function correctly. We need this macro % to make the Lua implementation aware where it should store the helper files. % The same limitations apply here as in the case of the -% \m{markdownOptionHelperScriptFileName} macro. +% \mref{markdownOptionHelperScriptFileName} macro. % % \end{markdown} % \begin{macrocode} @@ -6602,10 +7201,10 @@ For more information, see the examples for the \Opt{finalizeCache} option. % % The \mdef{markdownOptionCacheDir} macro corresponds to the Lua interface % \Opt{cacheDir} option that sets the path to the directory that will contain -% the produced cache files. The option defaults to `_markdown_`\m{jobname}, +% the produced cache files. The option defaults to `_markdown_`\mref{jobname}, % which is a similar naming scheme to the one used by the \pkg{minted} \LaTeX{} % package. The same limitations apply here as in the case of the -% \m{markdownOptionHelperScriptFileName} macro. +% \mref{markdownOptionHelperScriptFileName} macro. % % \end{markdown} % \begin{macrocode} @@ -6619,7 +7218,7 @@ For more information, see the examples for the \Opt{finalizeCache} option. % file (frozen cache) that will contain a mapping between an enumeration of the % markdown documents in the plain \TeX{} document and their auxiliary cache % files. The option defaults to `frozenCache.tex`. The same limitations apply -% here as in the case of the \m{markdownOptionHelperScriptFileName} macro. +% here as in the case of the \mref{markdownOptionHelperScriptFileName} macro. % % \end{markdown} % \begin{macrocode} @@ -6695,13 +7294,13 @@ bug](https://github.com/witiko/markdown/issues). % %#### Lua Interface Options % The following macros map directly to the options recognized by the Lua -% interface (see Section \ref{sec:luaoptions}) and are not processed by the +% interface (see Section \vref{sec:luaoptions}) and are not processed by the % plain \TeX{} implementation, only passed along to Lua. They are undefined, which % makes them fall back to the default values provided by the Lua interface. % % For the macros that correspond to the non-boolean options recognized by the % Lua interface, the same limitations apply here in the case of the -% \m{markdownOptionHelperScriptFileName} macro. +% \mref{markdownOptionHelperScriptFileName} macro. % % \end{markdown} % \begin{macrocode} @@ -6721,6 +7320,7 @@ bug](https://github.com/witiko/markdown/issues). \let\markdownOptionHtml\undefined \let\markdownOptionHybrid\undefined \let\markdownOptionInlineFootnotes\undefined +\let\markdownOptionJekyllData\undefined \let\markdownOptionPipeTables\undefined \let\markdownOptionPreserveTabs\undefined \let\markdownOptionShiftHeadings\undefined @@ -6729,6 +7329,7 @@ bug](https://github.com/witiko/markdown/issues). \let\markdownOptionStartNumber\undefined \let\markdownOptionStripIndent\undefined \let\markdownOptionTableCaptions\undefined +\let\markdownOptionTaskLists\undefined \let\markdownOptionTeXComments\undefined \let\markdownOptionTightLists\undefined % \end{macrocode} @@ -6781,7 +7382,7 @@ A PDF document named `document.pdf` should be produced and contain the text % % The \mdef{markdownOptionStripPercentSigns} macro controls whether a percent % sign (`%`) at the beginning of a line will be discarded when buffering -% Markdown input (see Section~\ref{sec:buffering}) or not. Notably, this +% Markdown input (see Section \vref{sec:buffering}) or not. Notably, this % enables the use of markdown when writing \TeX{} package documentation using % the \pkg{Doc} \LaTeX{}~package~[@mittelbach17] or similar. The recognized % values of the macro are `true` (discard) and `false` (retain). It defaults @@ -6819,10 +7420,99 @@ In this section, I will describe the individual token renderers. % % The following \TeX{} macros may occur inside the output of the % converter functions exposed by the Lua interface (see Section -% \ref{sec:luaconversion}) and represent the parsed markdown tokens. These +% \vref{sec:luaconversion}) and represent the parsed markdown tokens. These % macros are intended to be redefined by the user who is typesetting a % document. By default, they point to the corresponding prototypes (see Section -% \ref{sec:texrendererprototypes}). +% \vref{sec:texrendererprototypes}). + +#### Tickbox Renderers +The macros named \mdef{markdownRendererTickedBox}, +\mdef{markdownRendererHalfTickedBox}, and \mdef{markdownRendererUntickedBox} +represent ticked and unticked boxes, respectively. These macros will either be +produced, when the \Opt{taskLists} option is enabled, or when the Ballot Box +with X (☒, U+2612), Hourglass (⌛, U+231B) or Ballot Box (☐, U+2610) Unicode +characters are encountered in the markdown input, respectively. + +% \end{markdown} +% +% \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[taskLists]{markdown} +\markdownSetup{ + renderers = { + untickedBox = No, + tickedBox = Yes, + }, +} +\begin{document} +\begin{markdown} +- [ ] you can't. +- [x] I can! +\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 +following text: + +> - No you can't. +> - Yes I can! + +##### \Hologo{ConTeXt} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownOptionTaskLists{true} +\def\markdownRendererUntickedBox{No} +\def\markdownRendererTickedBox{Yes} +\starttext +\startmarkdown +- [ ] you can't. +- [x] I can! +\stopmarkdown +\stoptext +```````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> - No you can't. +> - Yes I can! + +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererTickedBox{% + \markdownRendererTickedBoxPrototype}% +\def\markdownRendererHalfTickedBox{% + \markdownRendererHalfTickedBoxPrototype}% +\def\markdownRendererUntickedBox{% + \markdownRendererUntickedBoxPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} #### Interblock Separator Renderer The \mdef{markdownRendererInterblockSeparator} macro represents a separator @@ -7762,7 +8452,7 @@ and the title of the content block. The \mdef{markdownRendererContentBlockOnlineImage} macro represents an iA\,Writer online image content block. The macro receives the same arguments -as \m{markdownRendererContentBlock}. +as \mref{markdownRendererContentBlock}. % \end{markdown} % @@ -9413,6 +10103,29 @@ a block quote. The macro receives no arguments. % \end{markdown} % % \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererBlockQuoteBegin{% + \markdownRendererBlockQuoteBeginPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererBlockQuoteEnd} macro represents the end of a block +quote. The macro receives no arguments. + +% \end{markdown} +% +% \iffalse ##### Plain \TeX{} Example {.unnumbered} @@ -9531,29 +10244,6 @@ following text: % \fi % % \begin{macrocode} -\def\markdownRendererBlockQuoteBegin{% - \markdownRendererBlockQuoteBeginPrototype}% -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} - -The \mdef{markdownRendererBlockQuoteEnd} macro represents the end of a block -quote. The macro receives no arguments. - -% \end{markdown} -% -% \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} \def\markdownRendererBlockQuoteEnd{% \markdownRendererBlockQuoteEndPrototype}% % \end{macrocode} @@ -9695,6 +10385,328 @@ following text except for the filename, which may differ: %</tex> %<*manual-tokens> % \fi +% \begin{markdown} + +#### YAML Metadata Renderers +The \mdef{markdownRendererJekyllDataBegin} macro represents the beginning of a +\acro{yaml} document. This macro will only be produced when the \Opt{jekyllData} +option is enabled. The macro receives no arguments. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataBegin{% + \markdownRendererJekyllDataBeginPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererJekyllDataEnd} macro represents the end of a +\acro{yaml} document. This macro will only be produced when the +\Opt{jekyllData} option is enabled. The macro receives no arguments. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataEnd{% + \markdownRendererJekyllDataEndPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererJekyllDataMappingBegin} macro represents the +beginning of a mapping in a \acro{yaml} document. This macro will only be +produced when the \Opt{jekyllData} option is enabled. The macro receives two +arguments: the scalar key in the parent structure, cast to a string following +\acro{yaml} serialization rules, and the number of items in the mapping. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataMappingBegin{% + \markdownRendererJekyllDataMappingBeginPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererJekyllDataMappingEnd} macro represents the +end of a mapping in a \acro{yaml} document. This macro will only be produced +when the \Opt{jekyllData} option is enabled. The macro receives no arguments. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataMappingEnd{% + \markdownRendererJekyllDataMappingEndPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererJekyllDataSequenceBegin} macro represents the +beginning of a sequence in a \acro{yaml} document. This macro will only be +produced when the \Opt{jekyllData} option is enabled. The macro receives two +arguments: the scalar key in the parent structure, cast to a string following +\acro{yaml} serialization rules, and the number of items in the sequence. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataSequenceBegin{% + \markdownRendererJekyllDataSequenceBeginPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererJekyllDataBoolean} macro represents a boolean scalar +value in a \acro{yaml} document. This macro will only be produced when the +\Opt{jekyllData} option is enabled. The macro receives two arguments: the +scalar key in the parent structure, and the scalar value, both cast to a string +following \acro{yaml} serialization rules. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataBoolean{% + \markdownRendererJekyllDataBooleanPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererJekyllDataNumber} macro represents a numeric scalar +value in a \acro{yaml} document. This macro will only be produced when the +\Opt{jekyllData} option is enabled. The macro receives two arguments: the +scalar key in the parent structure, and the scalar value, both cast to a string +following \acro{yaml} serialization rules. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataNumber{% + \markdownRendererJekyllDataNumberPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererJekyllDataString} macro represents a string scalar +value in a \acro{yaml} document. This macro will only be produced when the +\Opt{jekyllData} option is enabled. The macro receives two arguments: the +scalar key in the parent structure, cast to a string following \acro{yaml} +serialization rules, and the scalar value. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataString{% + \markdownRendererJekyllDataStringPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererJekyllDataEmpty} macro represents an empty scalar +value in a \acro{yaml} document. This macro will only be produced when the +\Opt{jekyllData} option is enabled. The macro receives one argument: the +scalar key in the parent structure, cast to a string following \acro{yaml} +serialization rules. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataEmpty{% + \markdownRendererJekyllDataEmptyPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> + +##### Plain \TeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\def\markdownOptionJekyllData{true} +\def\markdownRendererJekyllDataString#1#2{\gdef\name{#2}} +\def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}} +\def\markdownRendererJekyllDataEnd{% + \name{} is \age{} years old.} +\markdownBegin +--- +name: Jane Doe +age: 99 +--- +\markdownEnd +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Jane Doe is 99 years old. + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[jekyllData]{markdown} +\markdownSetup{ + renderers = { + jekyllDataString = {\gdef\name{#2}}, + jekyllDataNumber = {\gdef\age{#2}}, + jekyllDataEnd = {\name{} is \age{} years old.}, + } +} +\begin{document} + +\begin{markdown} +--- +name: Jane Doe +age: 99 +--- +\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 +following text: + +> Jane Doe is 99 years old. + +##### \Hologo{ConTeXt} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownOptionJekyllData{true} +\def\markdownRendererJekyllDataString#1#2{\gdef\name{#2}} +\def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}} +\def\markdownRendererJekyllDataEnd{% + \name{} is \age{} years old.} +\starttext + +\startmarkdown +--- +name: Jane Doe +age: 99 +--- +\stopmarkdown + +\stoptext +``````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Jane Doe is 99 years old. + +% \fi % % \begin{markdown} @@ -10267,7 +11279,7 @@ following text: The \mdef{markdownRendererTextCite} macro represents a string of one or more text citations. This macro will only be produced, when the \Opt{citations} option is enabled. The macro receives parameters in the same -format as the \m{markdownRendererCite} macro. +format as the \mref{markdownRendererCite} macro. % \end{markdown} % @@ -10650,11 +11662,11 @@ following text: % \begin{markdown} % % The following \TeX{} macros provide definitions for the token renderers (see -% Section \ref{sec:texrenderersuser}) that have not been redefined by the +% Section \vref{sec:texrenderersuser}) that have not been redefined by the % user. These macros are intended to be redefined by macro package authors % who wish to provide sensible default token renderers. They are also redefined % by the \LaTeX{} and \Hologo{ConTeXt} implementations (see sections -% \ref{sec:lateximplementation} and \ref{sec:contextimplementation}). +% \vref{sec:lateximplementation} and \vref{sec:contextimplementation}). % % \end{markdown} % \begin{macrocode} @@ -10706,6 +11718,16 @@ following text: \def\markdownRendererBlockQuoteEndPrototype{}% \def\markdownRendererInputVerbatimPrototype#1{}% \def\markdownRendererInputFencedCodePrototype#1#2{}% +\def\markdownRendererJekyllDataBooleanPrototype#1#2{}% +\def\markdownRendererJekyllDataEmptyPrototype#1{}% +\def\markdownRendererJekyllDataNumberPrototype#1#2{}% +\def\markdownRendererJekyllDataStringPrototype#1#2{}% +\def\markdownRendererJekyllDataBeginPrototype{}% +\def\markdownRendererJekyllDataEndPrototype{}% +\def\markdownRendererJekyllDataSequenceBeginPrototype#1#2{}% +\def\markdownRendererJekyllDataSequenceEndPrototype{}% +\def\markdownRendererJekyllDataMappingBeginPrototype#1#2{}% +\def\markdownRendererJekyllDataMappingEndPrototype{}% \def\markdownRendererHeadingOnePrototype#1{}% \def\markdownRendererHeadingTwoPrototype#1{}% \def\markdownRendererHeadingThreePrototype#1{}% @@ -10718,6 +11740,9 @@ following text: \def\markdownRendererTextCitePrototype#1{}% \def\markdownRendererTablePrototype#1#2#3{}% \def\markdownRendererInlineHtmlCommentPrototype#1{}% +\def\markdownRendererTickedBoxPrototype{}% +\def\markdownRendererHalfTickedBoxPrototype{}% +\def\markdownRendererUntickedBoxPrototype{}% % \end{macrocode} % \par % \begin{markdown} @@ -10726,7 +11751,7 @@ following text: % The \mdef{markdownInfo}, \mdef{markdownWarning}, and \mdef{markdownError} % macros perform logging for the Markdown package. Their first argument % specifies the text of the info, warning, or error message. -% The \m{markdownError} macro receives a second argument that provides a help +% The \mref{markdownError} macro receives a second argument that provides a help % text. You may redefine these macros to redirect and process the info, % warning, and error messages. % @@ -10745,9 +11770,9 @@ following text: % \par % \begin{markdown} % -% The \mdef{markdownReadAndConvert} macro implements the \m{markdownBegin} +% The \mdef{markdownReadAndConvert} macro implements the \mref{markdownBegin} % macro. The first argument specifies the token sequence that will terminate -% the markdown input (\m{markdownEnd} in the instance of the \m{markdownBegin} +% the markdown input (\mref{markdownEnd} in the instance of the \mref{markdownBegin} % macro) when the plain \TeX{} special characters have had their category % changed to *other*. The second argument specifies the token sequence % that will actually be inserted into the document, when the ending token @@ -10775,7 +11800,7 @@ following text: % \begin{markdown} % The macro is exposed in the interface, so that the user can create their own % markdown environments. Due to the way the arguments are passed to Lua (see -% Section \ref{sec:directlua}), the first argument may not contain the +% Section \vref{sec:directlua}), the first argument may not contain the % string `]]` (regardless of the category code of the bracket symbol (`]`)). % % The \mdef{markdownMode} macro specifies how the plain \TeX{} implementation @@ -10783,13 +11808,13 @@ following text: % as follows: % % - `0` – Shell escape via the 18 output file stream -% - `1` – Shell escape via the Lua \luam{os.execute} method +% - `1` – Shell escape via the Lua \luamref{os.execute} method % - `2` – Direct Lua access % % By defining the macro, the user can coerce the package to use a specific mode. % If the user does not define the macro prior to loading the plain \TeX{} % implementation, the correct value will be automatically detected. The outcome -% of changing the value of \m{markdownMode} after the implementation has been +% of changing the value of \mref{markdownMode} after the implementation has been % loaded is undefined. % % \end{markdown} @@ -10836,8 +11861,8 @@ idioms, such as package options and environments. The \LaTeX{} interface accepts the same options as the plain \TeX{} interface, but now the options are specified as \meta{key}${}={}$\meta{value} pairs and -they are passed either as package options, in the \m{markdownSetup} command, or -as parameters for the \envm{markdown*} \LaTeX{} environment. +they are passed either as package options, in the \mref{markdownSetup} command, or +as parameters for the \envmref{markdown*} \LaTeX{} environment. Using a text editor, create a text document named `document.tex` with the following content: @@ -10879,10 +11904,10 @@ pdflatex --shell-escape document.tex % % The \LaTeX{} interface provides \LaTeX{} environments for the typesetting of % markdown input from within \LaTeX{}, facilities for setting Lua interface -% options (see Section \ref{sec:luaoptions}) used during the conversion from +% options (see Section \vref{sec:luaoptions}) used during the conversion from % markdown to plain \TeX{}, and facilities for changing the way markdown tokens % are rendered. The rest of the interface is inherited from the plain \TeX{} -% interface (see Section \ref{sec:texinterface}). +% interface (see Section \vref{sec:texinterface}). % % The \LaTeX{} interface is implemented by the `markdown.sty` file, which % can be loaded from the \LaTeX{} document preamble as follows: @@ -10892,10 +11917,10 @@ pdflatex --shell-escape document.tex % \end{Verbatim} % \begin{markdown} % where \meta{options} are the \LaTeX{} interface options (see Section -% \ref{sec:latexoptions}). Note that \meta{options} inside the \m{usepackage} +% \vref{sec:latexoptions}). Note that \meta{options} inside the \mref{usepackage} % macro may not set the `markdownRenderers` (see Section -% \ref{sec:latexrenderers}) and `markdownRendererPrototypes` (see Section -% \ref{sec:latexrendererprototypes}) keys. This limitation is due to the way +% \vref{sec:latexrenderers}) and `markdownRendererPrototypes` (see Section +% \vref{sec:latexrendererprototypes}) keys. This limitation is due to the way % \Hologo{LaTeX2e} parses package options. % % \end{markdown} @@ -10904,12 +11929,12 @@ pdflatex --shell-escape document.tex % %### Typesetting Markdown % The interface exposes the \envmdef{markdown} and \envmdef{markdown*} -% \LaTeX{} environments, and redefines the \m{markdownInput} command. +% \LaTeX{} environments, and redefines the \mref{markdownInput} command. % -% The \envm{markdown} and \envm{markdown*} \LaTeX{} environments are used to +% The \envmref{markdown} and \envmref{markdown*} \LaTeX{} environments are used to % typeset markdown document fragments. The starred version of the -% \envm{markdown} environment accepts \LaTeX{} interface options (see -% Section \ref{sec:latexoptions}) as its only argument. These options will +% \envmref{markdown} environment accepts \LaTeX{} interface options (see +% Section \vref{sec:latexoptions}) as its only argument. These options will % only influence this markdown document fragment. % % \end{markdown} @@ -10919,17 +11944,17 @@ pdflatex --shell-escape document.tex % \end{macrocode} % \markdownBegin % -% You may prepend your own code to the \m{markdown} macro and append your own -% code to the \m{endmarkdown} macro to produce special effects before and after -% the \envm{markdown} \LaTeX{} environment (and likewise for the starred +% You may prepend your own code to the \mref{markdown} macro and append your own +% code to the \mref{endmarkdown} macro to produce special effects before and after +% the \envmref{markdown} \LaTeX{} environment (and likewise for the starred % version). % -% Note that the \envm{markdown} and \envm{markdown*} \LaTeX{} environments are -% subject to the same limitations as the \m{markdownBegin} and \m{markdownEnd} +% Note that the \envmref{markdown} and \envmref{markdown*} \LaTeX{} environments are +% subject to the same limitations as the \mref{markdownBegin} and \mref{markdownEnd} % macros exposed by the plain \TeX{} interface. % % The following example \LaTeX{} code showcases the usage of the -% \envm{markdown} and \envm{markdown*} environments: +% \envmref{markdown} and \envmref{markdown*} environments: % ``` tex % \documentclass{article} \documentclass{article} % \usepackage{markdown} \usepackage{markdown} @@ -10942,16 +11967,16 @@ pdflatex --shell-escape document.tex % \end{document} \end{document} % ``````` % -% The \m{markdownInput} macro accepts a single mandatory parameter containing +% The \mref{markdownInput} macro accepts a single mandatory parameter containing % the filename of a markdown document and expands to the result of the % conversion of the input markdown document to plain \TeX{}. Unlike the -% \m{markdownInput} macro provided by the plain \TeX{} interface, this macro -% also accepts \LaTeX{} interface options (see Section \ref{sec:latexoptions}) +% \mref{markdownInput} macro provided by the plain \TeX{} interface, this macro +% also accepts \LaTeX{} interface options (see Section \vref{sec:latexoptions}) % as its optional argument. These options will only influnce this markdown % document. % % The following example \LaTeX{} code showcases the usage of the -% \m{markdownInput} macro: +% \mref{markdownInput} macro: % ``` tex % \documentclass{article} % \usepackage{markdown} @@ -10970,18 +11995,18 @@ pdflatex --shell-escape document.tex % part is optional, and \meta{key} will be interpreted as \meta{key}`=true` % if the `=`\meta{value} part has been omitted. % -% Except for the `plain` option described in Section \ref{sec:latexplain}, and -% the \LaTeX{} themes described in Section \ref{sec:latexthemes}, and the -% \LaTeX{} setup snippets described in Section \ref{sec:latexsetupsnippets}, +% Except for the `plain` option described in Section \vref{sec:latexplain}, and +% the \LaTeX{} themes described in Section \vref{sec:latexthemes}, and the +% \LaTeX{} setup snippets described in Section \vref{sec:latexsetupsnippets}, % \LaTeX{} options map directly to the options recognized by the plain -% \TeX{} interface (see Section \ref{sec:texoptions}) and to the markdown token +% \TeX{} interface (see Section \vref{sec:texoptions}) and to the markdown token % renderers and their prototypes recognized by the plain \TeX{} interface (see -% Sections \ref{sec:texrenderersuser} and \ref{sec:texrendererprototypes}). +% Sections \vref{sec:texrenderersuser} and \vref{sec:texrendererprototypes}). % % The \LaTeX{} options may be specified when loading the \LaTeX{} package, when -% using the \envm{markdown*} \LaTeX{} environment or the \m{markdownInput} -% macro (see Section \ref{sec:latexinterface}), or via the \mdef{markdownSetup} -% macro. The \m{markdownSetup} macro receives the options to set up as its only +% using the \envmref{markdown*} \LaTeX{} environment or the \mref{markdownInput} +% macro (see Section \vref{sec:latexinterface}), or via the \mdef{markdownSetup} +% macro. The \mref{markdownSetup} macro receives the options to set up as its only % argument: % % \markdownEnd @@ -10992,7 +12017,7 @@ pdflatex --shell-escape document.tex % \begin{markdown} % % We may also store \LaTeX{} options as *setup snippets* and invoke them later -% using the \mdef{markdownSetupSnippet} macro. The \m{markdownSetupSnippet} +% using the \mdef{markdownSetupSnippet} macro. The \mref{markdownSetupSnippet} % macro receives two arguments: the name of the setup snippet and the options % to store: % @@ -11014,8 +12039,8 @@ pdflatex --shell-escape document.tex % \end{macrocode} % \begin{markdown} % -% See Section \ref{sec:latexthemes} for information on interactions between -% setup snippets and \LaTeX{} themes. See Section \ref{sec:latexsetupsnippets} +% See Section \vref{sec:latexthemes} for information on interactions between +% setup snippets and \LaTeX{} themes. See Section \vref{sec:latexsetupsnippets} % for information about invoking the stored setup snippets. % % \end{markdown} @@ -11040,8 +12065,8 @@ other packages used in a document. Additionally, if we redefine token renderers and renderer prototypes ourselves, the default definitions will bring no benefit to us. Using the `plain` package option, we can keep the default definitions from the plain \TeX{} implementation (see Section -\ref{sec:textokenrendererprototypes}) and prevent the soft \LaTeX{} -prerequisites in Section \ref{sec:latexprerequisites} from being loaded: +\vref{sec:textokenrendererprototypes}) and prevent the soft \LaTeX{} +prerequisites in Section \vref{sec:latexprerequisites} from being loaded: ``` tex \usepackage[plain]{markdown} @@ -11084,7 +12109,7 @@ high-level goals without low-level programming. % (\texttt{_}), the theme name is a value that is *qualified* and contains no % underscores, and a value is qualified if and only if it contains at least one % forward slash. Themes are inspired by the Beamer \LaTeX{} package, which -% provides similar functionality with its \m{usetheme} macro [@tantau21, +% provides similar functionality with its \mref{usetheme} macro [@tantau21, % Section 15.1]. % % Theme names must be qualified to minimize naming conflicts between different @@ -11103,7 +12128,7 @@ high-level goals without low-level programming. % package named `markdownthemewitiko_beamer_MU.sty`. % % If the \LaTeX{} option with key `theme` is (repeatedly) specified in the -% \m{usepackage} macro, the loading of the theme(s) will be postponed in +% \mref{usepackage} macro, the loading of the theme(s) will be postponed in % first-in-first-out order until after the Markdown \LaTeX{} package has been % loaded. Otherwise, the theme(s) will be loaded immediately. For example, % there is a theme named `witiko/dot`, which typesets fenced code blocks with @@ -11163,7 +12188,7 @@ would use the following code in the preamble of your document: % \begin{markdown} % % The \LaTeX{} themes have a useful synergy with the setup snippets (see -% Section \ref{sec:latexoptions}): To make it less likely that different +% Section \vref{sec:latexoptions}): To make it less likely that different % themes will define setup snippets with the same name, we will prepend % \meta{theme name}`/` before the snippet name and use the result as the % snippet name. For example, if the `witiko/dot` theme defines the `product` @@ -11239,7 +12264,7 @@ Example themes provided with the Markdown package include: % \end{document} % ```````` % Typesetting the above document produces the output shown in -% Figure~\ref{fig:witiko/dot}. +% Figure \vref{fig:witiko/dot}. % ``` dot Various formats of mathemathical formulae \label{fig:witiko/dot} % digraph tree { % margin = 0; @@ -11266,7 +12291,7 @@ Example themes provided with the Markdown package include: % ``` The theme requires a Unix-like operating system with GNU Diffutils and Graphviz installed. The theme also requires shell access unless the - \m{markdownOptionFrozenCache} plain \TeX{} option is enabled. + \mref{markdownOptionFrozenCache} plain \TeX{} option is enabled. % \markdownEnd % \iffalse @@ -11347,19 +12372,19 @@ conference article: % \usepackage[theme=witiko/graphicx/http]{markdown} % \begin{document} % \begin{markdown} -%  % \end{markdown} % \end{document} % ``````` % Typesetting the above document produces the output shown in -% Figure~\ref{fig:witiko/graphicx/http}. -%  The theme requires the \pkg{catchfile} \LaTeX{} package and a Unix-like operating system with GNU Coreutils `md5sum` and either GNU Wget or cURL installed. The theme also requires shell access unless the - \m{markdownOptionFrozenCache} plain \TeX{} option is enabled. + \mref{markdownOptionFrozenCache} plain \TeX{} option is enabled. % \markdownEnd % \iffalse @@ -11373,7 +12398,7 @@ following content: \usepackage[theme=witiko/graphicx/http]{markdown} \begin{document} \begin{markdown} - \end{markdown} \end{document} @@ -11385,7 +12410,7 @@ lualatex document.tex A PDF document named `document.pdf` should be produced and contain the following image: ->  %</manual-options> @@ -11393,7 +12418,6 @@ following image: % \fi % \begin{macrocode} \ProvidesPackage{markdownthemewitiko_graphicx_http}[2021/03/22]% -\RequirePackage{catchfile} % \end{macrocode} % \iffalse %</latex-themes-witiko-graphicx-http> @@ -11456,7 +12480,7 @@ following text, where the middot (`·`) denotes a non-breaking space: % \par % \begin{markdown} % -% Please, see Section~\ref{sec:latexthemesimplementation} for implementation +% Please, see Section \vref{sec:latexthemesimplementation} for implementation % details of the example themes. #### \LaTeX{} setup snippets @@ -11520,7 +12544,7 @@ The following ordered list will be preceded by roman numerals: %#### Plain \TeX{} Interface Options % The following options map directly to the option macros exposed by the plain -% \TeX{} interface (see Section \ref{sec:texoptions}). +% \TeX{} interface (see Section \vref{sec:texoptions}). % % \markdownEnd % \iffalse @@ -11564,6 +12588,8 @@ The following ordered list will be preceded by roman numerals: \def\markdownOptionFootnotes{#1}}% \define@key{markdownOptions}{fencedCode}[true]{% \def\markdownOptionFencedCode{#1}}% +\define@key{markdownOptions}{jekyllData}[true]{% + \def\markdownOptionJekyllData{#1}}% \define@key{markdownOptions}{hashEnumerators}[true]{% \def\markdownOptionHashEnumerators{#1}}% \define@key{markdownOptions}{headerAttributes}[true]{% @@ -11590,6 +12616,8 @@ The following ordered list will be preceded by roman numerals: \def\markdownOptionStripIndent{#1}}% \define@key{markdownOptions}{tableCaptions}[true]{% \def\markdownOptionTableCaptions{#1}}% +\define@key{markdownOptions}{taskLists}[true]{% + \def\markdownOptionTaskLists{#1}}% \define@key{markdownOptions}{texComments}[true]{% \def\markdownOptionTeXComments{#1}}% \define@key{markdownOptions}{tightLists}[true]{% @@ -11602,7 +12630,7 @@ The following ordered list will be preceded by roman numerals: % \par % \begin{markdown} % -% The \m{markdownOptionFinalizeCache} and \m{markdownOptionFrozenCache} plain +% The \mref{markdownOptionFinalizeCache} and \mref{markdownOptionFrozenCache} plain % \TeX{} options are exposed through \LaTeX{} options with keys `finalizeCache` % and `frozenCache`. % @@ -11640,8 +12668,8 @@ The following ordered list will be preceded by roman numerals: % \begin{markdown} % % The following example \LaTeX{} code showcases a possible configuration of -% plain \TeX{} interface options \m{markdownOptionHybrid}, -% \m{markdownOptionSmartEllipses}, and \m{markdownOptionCacheDir}. +% plain \TeX{} interface options \mref{markdownOptionHybrid}, +% \mref{markdownOptionSmartEllipses}, and \mref{markdownOptionCacheDir}. % ``` tex % \markdownSetup{ % hybrid, @@ -11656,7 +12684,7 @@ The following ordered list will be preceded by roman numerals: % The \LaTeX{} interface recognizes an option with the `renderers` key, % whose value must be a list of options that map directly to the markdown token % renderer macros exposed by the plain \TeX{} interface (see Section -% \ref{sec:texrenderersuser}). +% \vref{sec:texrenderersuser}). % % \end{markdown} % \begin{macrocode} @@ -11756,6 +12784,26 @@ The following ordered list will be preceded by roman numerals: \renewcommand\markdownRendererInputVerbatim[1]{#1}}% \define@key{markdownRenderers}{inputFencedCode}{% \renewcommand\markdownRendererInputFencedCode[2]{#1}}% +\define@key{markdownRenderers}{jekyllDataBoolean}{% + \renewcommand\markdownRendererJekyllDataBoolean[2]{#1}}% +\define@key{markdownRenderers}{jekyllDataEmpty}{% + \renewcommand\markdownRendererJekyllDataEmpty[1]{#1}}% +\define@key{markdownRenderers}{jekyllDataNumber}{% + \renewcommand\markdownRendererJekyllDataNumber[2]{#1}}% +\define@key{markdownRenderers}{jekyllDataString}{% + \renewcommand\markdownRendererJekyllDataString[2]{#1}}% +\define@key{markdownRenderers}{jekyllDataBegin}{% + \renewcommand\markdownRendererJekyllDataBegin{#1}}% +\define@key{markdownRenderers}{jekyllDataEnd}{% + \renewcommand\markdownRendererJekyllDataEnd{#1}}% +\define@key{markdownRenderers}{jekyllDataSequenceBegin}{% + \renewcommand\markdownRendererJekyllDataSequenceBegin[2]{#1}}% +\define@key{markdownRenderers}{jekyllDataSequenceEnd}{% + \renewcommand\markdownRendererJekyllDataSequenceEnd{#1}}% +\define@key{markdownRenderers}{jekyllDataMappingBegin}{% + \renewcommand\markdownRendererJekyllDataMappingBegin[2]{#1}}% +\define@key{markdownRenderers}{jekyllDataMappingEnd}{% + \renewcommand\markdownRendererJekyllDataMappingEnd{#1}}% \define@key{markdownRenderers}{headingOne}{% \renewcommand\markdownRendererHeadingOne[1]{#1}}% \define@key{markdownRenderers}{headingTwo}{% @@ -11780,12 +12828,18 @@ The following ordered list will be preceded by roman numerals: \renewcommand\markdownRendererTable[3]{#1}}% \define@key{markdownRenderers}{inlineHtmlComment}{% \renewcommand\markdownRendererInlineHtmlComment[1]{#1}}% +\define@key{markdownRenderers}{tickedBox}{% + \renewcommand\markdownRendererTickedBox{#1}}% +\define@key{markdownRenderers}{halfTickedBox}{% + \renewcommand\markdownRendererHalfTickedBox{#1}}% +\define@key{markdownRenderers}{untickedBox}{% + \renewcommand\markdownRendererUntickedBox{#1}}% % \end{macrocode} % \par % \begin{markdown} % % The following example \LaTeX{} code showcases a possible configuration of the -% \m{markdownRendererLink} and \m{markdownRendererEmphasis} markdown token +% \mref{markdownRendererLink} and \mref{markdownRendererEmphasis} markdown token % renderers. % ``` tex % \markdownSetup{ @@ -11801,7 +12855,7 @@ The following ordered list will be preceded by roman numerals: % The \LaTeX{} interface recognizes an option with the `rendererPrototypes` % key, whose value must be a list of options that map directly to the markdown % token renderer prototype macros exposed by the plain \TeX{} interface (see -% Section \ref{sec:texrendererprototypes}). +% Section \vref{sec:texrendererprototypes}). % % \end{markdown} % \begin{macrocode} @@ -11901,6 +12955,26 @@ The following ordered list will be preceded by roman numerals: \renewcommand\markdownRendererInputVerbatimPrototype[1]{#1}}% \define@key{markdownRendererPrototypes}{inputFencedCode}{% \renewcommand\markdownRendererInputFencedCodePrototype[2]{#1}}% +\define@key{markdownRendererPrototypes}{jekyllDataBoolean}{% + \renewcommand\markdownRendererJekyllDataBooleanPrototype[2]{#1}}% +\define@key{markdownRendererPrototypes}{jekyllDataEmpty}{% + \renewcommand\markdownRendererJekyllDataEmptyPrototype[1]{#1}}% +\define@key{markdownRendererPrototypes}{jekyllDataNumber}{% + \renewcommand\markdownRendererJekyllDataNumberPrototype[2]{#1}}% +\define@key{markdownRendererPrototypes}{jekyllDataString}{% + \renewcommand\markdownRendererJekyllDataStringPrototype[2]{#1}}% +\define@key{markdownRendererPrototypes}{jekyllDataBegin}{% + \renewcommand\markdownRendererJekyllDataBeginPrototype{#1}}% +\define@key{markdownRendererPrototypes}{jekyllDataEnd}{% + \renewcommand\markdownRendererJekyllDataEndPrototype{#1}}% +\define@key{markdownRendererPrototypes}{jekyllDataSequenceBegin}{% + \renewcommand\markdownRendererJekyllDataSequenceBeginPrototype[2]{#1}}% +\define@key{markdownRendererPrototypes}{jekyllDataSequenceEnd}{% + \renewcommand\markdownRendererJekyllDataSequenceEndPrototype{#1}}% +\define@key{markdownRendererPrototypes}{jekyllDataMappingBegin}{% + \renewcommand\markdownRendererJekyllDataMappingBeginPrototype[2]{#1}}% +\define@key{markdownRendererPrototypes}{jekyllDataMappingEnd}{% + \renewcommand\markdownRendererJekyllDataMappingEndPrototype{#1}}% \define@key{markdownRendererPrototypes}{headingOne}{% \renewcommand\markdownRendererHeadingOnePrototype[1]{#1}}% \define@key{markdownRendererPrototypes}{headingTwo}{% @@ -11925,12 +12999,18 @@ The following ordered list will be preceded by roman numerals: \renewcommand\markdownRendererTablePrototype[3]{#1}}% \define@key{markdownRendererPrototypes}{inlineHtmlComment}{% \renewcommand\markdownRendererInlineHtmlCommentPrototype[1]{#1}}% +\define@key{markdownRendererPrototypes}{tickedBox}{% + \renewcommand\markdownRendererTickedBoxPrototype{#1}}% +\define@key{markdownRendererPrototypes}{halfTickedBox}{% + \renewcommand\markdownRendererHalfTickedBoxPrototype{#1}}% +\define@key{markdownRendererPrototypes}{untickedBox}{% + \renewcommand\markdownRendererUntickedBoxPrototype{#1}}% % \end{macrocode} % \par % \begin{markdown} % % The following example \LaTeX{} code showcases a possible configuration of the -% \m{markdownRendererImagePrototype} and \m{markdownRendererCodeSpanPrototype} +% \mref{markdownRendererImagePrototype} and \mref{markdownRendererCodeSpanPrototype} % markdown token renderer prototypes. % ``` tex % \markdownSetup{ @@ -12003,7 +13083,7 @@ texexec --passon=--shell-escape document.tex % The \Hologo{ConTeXt} interface provides a start-stop macro pair for the % typesetting of markdown input from within \Hologo{ConTeXt}. The rest of the % interface is inherited from the plain \TeX{} interface (see Section -% \ref{sec:texinterface}). +% \vref{sec:texinterface}). % % \end{markdown} % \begin{macrocode} @@ -12020,7 +13100,7 @@ texexec --passon=--shell-escape document.tex % \usemodule[t][markdown] % ``````` % \noindent It is expected that the special plain \TeX{} characters have the -% expected category codes, when \m{input}ting the file. +% expected category codes, when \mref{input}ting the file. % %### Typesetting Markdown % The interface exposes the \mdef{startmarkdown} and \mdef{stopmarkdown} macro @@ -12034,16 +13114,16 @@ texexec --passon=--shell-escape document.tex % \par % \begin{markdown} % -% You may prepend your own code to the \m{startmarkdown} macro and redefine the -% \m{stopmarkdown} macro to produce special effects before and after the +% You may prepend your own code to the \mref{startmarkdown} macro and redefine the +% \mref{stopmarkdown} macro to produce special effects before and after the % markdown block. % -% Note that the \m{startmarkdown} and \m{stopmarkdown} macros -% are subject to the same limitations as the \m{markdownBegin} and -% \m{markdownEnd} macros exposed by the plain \TeX{} interface. +% Note that the \mref{startmarkdown} and \mref{stopmarkdown} macros +% are subject to the same limitations as the \mref{markdownBegin} and +% \mref{markdownEnd} macros exposed by the plain \TeX{} interface. % % The following example \Hologo{ConTeXt} code showcases the usage of the -% \m{startmarkdown} and \m{stopmarkdown} macros: +% \mref{startmarkdown} and \mref{stopmarkdown} macros: % ``` tex % \usemodule[t][markdown] % \starttext @@ -12057,13 +13137,22 @@ texexec --passon=--shell-escape document.tex %=============== % \label{sec:implementation} % This part of the documentation describes the implementation of the interfaces -% exposed by the package (see Section \ref{sec:interfaces}) and is aimed at the +% exposed by the package (see Section \vref{sec:interfaces}) and is aimed at the % developers of the package, as well as the curious users. % +% Figure \vref{fig:block-diagram} shows the high-level structure of the Markdown +% package: The translation from markdown to \TeX{} *token renderers* is +% performed by the Lua layer. The plain \TeX{} layer provides default +% definitions for the token renderers. The \LaTeX{} and \Hologo{ConTeXt} layers +% correct idiosyncrasies of the respective \TeX{} formats, and provide +% format-specific default definitions for the token renderers. +% +% \end{markdown} % \iffalse %</context> %<*lua> % \fi +% \begin{markdown} % % Lua Implementation %------------------- @@ -12075,7 +13164,7 @@ texexec --passon=--shell-escape document.tex % other formats, such as DocBook, Groff, or \acro{HTML}. These were stripped % from the module and the remaining markdown reader and plain \TeX{} writer % were hidden behind the converter functions exposed by the Lua interface (see -% Section \ref{sec:luainterface}). +% Section \vref{sec:luainterface}). % % \end{markdown} % \begin{macrocode} @@ -12234,7 +13323,7 @@ end % % The \luamdef{util.rope_to_string} method converts a rope `rope` to a % string and returns it. For the definition of a rope, see the definition of -% the \luam{util.walk} method. +% the \luamref{util.walk} method. % % \end{markdown} % \begin{macrocode} @@ -12248,7 +13337,7 @@ end % \begin{markdown} % % The \luamdef{util.rope_last} method retrieves the last item in a rope. For -% the definition of a rope, see the definition of the \luam{util.walk} method. +% the definition of a rope, see the definition of the \luamref{util.walk} method. % % \end{markdown} % \begin{macrocode} @@ -14480,16 +15569,16 @@ end % %### Plain \TeX{} Writer % \label{sec:texwriter} -% This section documents the \luam{writer} object, which implements the +% This section documents the \luamref{writer} object, which implements the % routines for producing the \TeX{} output. The object is an amalgamate of the % generic, \TeX{}, \LaTeX{} writer objects that were located in the % `lunamark/writer/generic.lua`, `lunamark/writer/tex.lua`, and % `lunamark/writer/latex.lua` files in the Lunamark Lua module. % % Although not specified in the Lua interface (see Section -% \ref{sec:luainterface}), the \luam{writer} object is exported, so that the +% \vref{sec:luainterface}), the \luamref{writer} object is exported, so that the % curious user could easily tinker with the methods of the objects produced by -% the \luam{writer.new} method described below. The user should be aware, +% the \luamref{writer.new} method described below. The user should be aware, % however, that the implementation may change in a future revision. % % \end{markdown} @@ -14501,10 +15590,10 @@ M.writer = {} % % The \luamdef{writer.new} method creates and returns a new \TeX{} writer % object associated with the Lua interface options (see Section -% \ref{sec:luaoptions}) `options`. When `options` are unspecified, it is +% \vref{sec:luaoptions}) `options`. When `options` are unspecified, it is % assumed that an empty table was passed to the method. % -% The objects produced by the \luam{writer.new} method expose instance methods +% The objects produced by the \luamref{writer.new} method expose instance methods % and variables of their own. As a convention, I will refer to these % \meta{member}s as `writer->`\meta{member}. All member variables are % immutable unless explicitly stated otherwise. @@ -14518,7 +15607,7 @@ function M.writer.new(options) % \par % \begin{markdown} % -% Make the `options` table inherit from the \luam{defaultOptions} table. +% Make the `options` table inherit from the \luamref{defaultOptions} table. % % \end{markdown} % \begin{macrocode} @@ -14530,7 +15619,7 @@ function M.writer.new(options) % % Parse the \Opt{slice} option and define \luamdef{writer->slice\_begin} % \luamdef{writer->slice\_end}, and \luamdef{writer->is\_writing}. The -% \luam{writer->is\_writing} member variable is mutable. +% \luamref{writer->is\_writing} member variable is mutable. % % \end{markdown} % \begin{macrocode} @@ -14681,29 +15770,12 @@ function M.writer.new(options) % \par % \begin{markdown} % -% Define a table \luamdef{escaped_chars} containing the mapping from special -% plain \TeX{} characters (including the active pipe character (`|`) of -% \Hologo{ConTeXt}) to their escaped variants. Define tables -% \luamdef{escaped_uri_chars}, \luamdef{escaped_citation_chars}, and -% \luamdef{escaped_minimal_strings} containing the mapping from special plain -% characters and character strings that need to be escaped even in content -% that will not be typeset. +% Define tables \luamdef{escaped_uri_chars}, \luamdef{escaped_citation_chars}, +% and \luamdef{escaped_minimal_strings} containing the mapping from special +% plain characters and character strings that always need to be escaped. % % \end{markdown} % \begin{macrocode} - local escaped_chars = { - ["{"] = "\\markdownRendererLeftBrace{}", - ["}"] = "\\markdownRendererRightBrace{}", - ["$"] = "\\markdownRendererDollarSign{}", - ["%"] = "\\markdownRendererPercentSign{}", - ["&"] = "\\markdownRendererAmpersand{}", - ["_"] = "\\markdownRendererUnderscore{}", - ["#"] = "\\markdownRendererHash{}", - ["^"] = "\\markdownRendererCircumflex{}", - ["\\"] = "\\markdownRendererBackslash{}", - ["~"] = "\\markdownRendererTilde{}", - ["|"] = "\\markdownRendererPipe{}", - } local escaped_uri_chars = { ["{"] = "\\markdownRendererLeftBrace{}", ["}"] = "\\markdownRendererRightBrace{}", @@ -14714,27 +15786,54 @@ function M.writer.new(options) ["{"] = "\\markdownRendererLeftBrace{}", ["}"] = "\\markdownRendererRightBrace{}", ["%"] = "\\markdownRendererPercentSign{}", - ["#"] = "\\markdownRendererHash{}", ["\\"] = "\\markdownRendererBackslash{}", + ["#"] = "\\markdownRendererHash{}", } local escaped_minimal_strings = { ["^^"] = "\\markdownRendererCircumflex\\markdownRendererCircumflex ", + ["☒"] = "\\markdownRendererTickedBox{}", + ["⌛"] = "\\markdownRendererHalfTickedBox{}", + ["☐"] = "\\markdownRendererUntickedBox{}", } % \end{macrocode} % \par % \begin{markdown} % -% Use the \luam{escaped_chars}, \luam{escaped_uri_chars}, -% \luam{escaped_citation_chars}, and \luam{escaped_minimal_strings} tables -% to create the \luamdef{escape}, \luamdef{escape_citation}, and -% \luamdef{escape_uri} escaper functions. +% Define a table \luamdef{escaped_chars} containing the mapping from special +% plain \TeX{} characters (including the active pipe character (`|`) of +% \Hologo{ConTeXt}) that need to be escaped for typeset content. % % \end{markdown} % \begin{macrocode} - local escape = util.escaper(escaped_chars) + local escaped_chars = { + ["{"] = "\\markdownRendererLeftBrace{}", + ["}"] = "\\markdownRendererRightBrace{}", + ["%"] = "\\markdownRendererPercentSign{}", + ["\\"] = "\\markdownRendererBackslash{}", + ["#"] = "\\markdownRendererHash{}", + ["$"] = "\\markdownRendererDollarSign{}", + ["&"] = "\\markdownRendererAmpersand{}", + ["_"] = "\\markdownRendererUnderscore{}", + ["^"] = "\\markdownRendererCircumflex{}", + ["~"] = "\\markdownRendererTilde{}", + ["|"] = "\\markdownRendererPipe{}", + } +% \end{macrocode} +% \par +% \begin{markdown} +% +% Use the \luamref{escaped_chars}, \luamref{escaped_uri_chars}, +% \luamref{escaped_citation_chars}, and \luamref{escaped_minimal_strings} tables +% to create the \luamdef{escape}, \luamdef{escape_citation}, +% \luamdef{escape_uri}, and \luamdef{escape_minimal} escaper functions. +% +% \end{markdown} +% \begin{macrocode} + local escape = util.escaper(escaped_chars, escaped_minimal_strings) local escape_citation = util.escaper(escaped_citation_chars, escaped_minimal_strings) local escape_uri = util.escaper(escaped_uri_chars, escaped_minimal_strings) + local escape_minimal = util.escaper({}, escaped_minimal_strings) % \end{macrocode} % \par % \begin{markdown} @@ -14744,15 +15843,15 @@ function M.writer.new(options) % function that will transform an input citation name `c` to the output format, % and \luamdef{writer->uri} as a function that will transform an input % \acro{uri} `u` to the output format. If the \Opt{hybrid} option is enabled, -% use identity functions. Otherwise, use the \luam{escape}, -% \luam{escape_citation}, and \luam{escape_uri} functions. +% use the \luamref{escape_minimal}. Otherwise, use the \luamref{escape}, +% \luamref{escape_citation}, and \luamref{escape_uri} functions. % % \end{markdown} % \begin{macrocode} if options.hybrid then - self.string = function(s) return s end - self.citation = function(c) return c end - self.uri = function(u) return u end + self.string = escape_minimal + self.citation = escape_minimal + self.uri = escape_minimal else self.string = escape self.citation = escape_citation @@ -14763,8 +15862,8 @@ function M.writer.new(options) % \begin{markdown} % % Define \luamdef{writer->escape} as a function that will transform an input -% plain text span to the output format. Unlike the \luam{writer->string} -% function, \luam{writer->escape} always uses the \luam{escape} function, +% plain text span to the output format. Unlike the \luamref{writer->string} +% function, \luamref{writer->escape} always uses the \luamref{escape} function, % even when the \Opt{hybrid} option is enabled. % % \end{markdown} @@ -14851,9 +15950,9 @@ function M.writer.new(options) % \begin{markdown} % % The \luamdef{languages_json} table maps programming language filename -% extensions to fence infostrings. All \luam{options.contentBlocksLanguageMap} +% extensions to fence infostrings. All `options.`\luamref{contentBlocksLanguageMap} % files located by the KPathSea library are loaded into a chain of tables. -% \luam{languages_json} corresponds to the first table and is chained with +% \luamref{languages_json} corresponds to the first table and is chained with % the rest via Lua metatables. % % \end{markdown} @@ -14866,7 +15965,7 @@ function M.writer.new(options) % \begin{markdown} % % If the KPathSea library is unavailable, perhaps because we are using -% LuaMeta\TeX, we will only locate the \luam{options.contentBlocksLanguageMap} +% LuaMeta\TeX, we will only locate the `options.`\luamref{contentBlocksLanguageMap} % in the current working directory: % % \end{markdown} @@ -15066,6 +16165,24 @@ function M.writer.new(options) % \par % \begin{markdown} % +% Define \luamdef{writer->tickbox} as a function that will transform a +% number `f` to the output format. +% +% \end{markdown} +% \begin{macrocode} + function self.tickbox(f) + if f == 1.0 then + return "☒ " + elseif f == 0.0 then + return "☐ " + else + return "⌛ " + end + end +% \end{macrocode} +% \par +% \begin{markdown} +% % Define \luamdef{writer->strong} as a function that will transform a strongly % emphasized span `s` of input text to the output format. % @@ -15123,9 +16240,104 @@ function M.writer.new(options) % \par % \begin{markdown} % +% Define \luamdef{writer->jekyllData} as a function that will transform an +% input \acro{yaml} table `d` to the output format. The table is the value for +% the key `p` in the parent table; if `p` is nil, then the table has no parent. +% All scalar keys and values encountered in the table will be cast to a string +% following \acro{yaml} serialization rules. String values will also be +% transformed using the function `t`. +% +% \end{markdown} +% \begin{macrocode} + function self.jekyllData(d, t, p) + if not self.is_writing then return "" end + + local buf = {} + + local keys = {} + for k, _ in pairs(d) do + table.insert(keys, k) + end + table.sort(keys) + + if not p then + table.insert(buf, "\\markdownRendererJekyllDataBegin") + end + + if #d > 0 then + table.insert(buf, "\\markdownRendererJekyllDataSequenceBegin{") + table.insert(buf, self.uri(p or "null")) + table.insert(buf, "}{") + table.insert(buf, #keys) + table.insert(buf, "}") + else + table.insert(buf, "\\markdownRendererJekyllDataMappingBegin{") + table.insert(buf, self.uri(p or "null")) + table.insert(buf, "}{") + table.insert(buf, #keys) + table.insert(buf, "}") + end + + for _, k in ipairs(keys) do + local v = d[k] + local typ = type(v) + k = tostring(k or "null") + if typ == "table" and next(v) ~= nil then + table.insert( + buf, + self.jekyllData(v, t, k) + ) + else + k = self.uri(k) + v = tostring(v) + if typ == "boolean" then + table.insert(buf, "\\markdownRendererJekyllDataBoolean{") + table.insert(buf, k) + table.insert(buf, "}{") + table.insert(buf, v) + table.insert(buf, "}") + elseif typ == "number" then + table.insert(buf, "\\markdownRendererJekyllDataNumber{") + table.insert(buf, k) + table.insert(buf, "}{") + table.insert(buf, v) + table.insert(buf, "}") + elseif typ == "string" then + table.insert(buf, "\\markdownRendererJekyllDataString{") + table.insert(buf, k) + table.insert(buf, "}{") + table.insert(buf, t(v)) + table.insert(buf, "}") + elseif typ == "table" then + table.insert(buf, "\\markdownRendererJekyllDataEmpty{") + table.insert(buf, k) + table.insert(buf, "}") + else + error(format("Unexpected type %s for value of " .. + "YAML key %s", typ, k)) + end + end + end + + if #d > 0 then + table.insert(buf, "\\markdownRendererJekyllDataSequenceEnd") + else + table.insert(buf, "\\markdownRendererJekyllDataMappingEnd") + end + + if not p then + table.insert(buf, "\\markdownRendererJekyllDataEnd") + end + + return buf + end +% \end{macrocode} +% \par +% \begin{markdown} +% % Define \luamdef{writer->active\_headings} as a stack of identifiers % of the headings that are currently active. The -% \luam{writer->active\_headings} member variable is mutable. +% \luamref{writer->active\_headings} member variable is mutable. % % \end{markdown} % \begin{macrocode} @@ -15271,8 +16483,8 @@ function M.writer.new(options) % \end{markdown} % \begin{macrocode} function self.set_state(s) - previous_state = self.get_state() - for key, value in pairs(state) do + local previous_state = self.get_state() + for key, value in pairs(s) do self[key] = value end return previous_state @@ -15283,14 +16495,14 @@ function M.writer.new(options) % % Define \luamdef{writer->defer_call} as a function that will encapsulate the % input function `f`, so that `f` is called with the state of the writer at the -% time of calling \luam{writer->defer_call}. +% time of calling \luamref{writer->defer_call}. % % \end{markdown} % \begin{macrocode} function self.defer_call(f) - state = self.get_state() + local previous_state = self.get_state() return function(...) - state = self.set_state(state) + local state = self.set_state(previous_state) local return_value = f(...) self.set_state(state) return return_value @@ -15305,7 +16517,7 @@ end % %### Parsers % The \luamdef{parsers} hash table stores \acro{peg} patterns that are -% static and can be reused between different \luam{reader} objects. +% static and can be reused between different \luamref{reader} objects. % % \end{markdown} % \begin{macrocode} @@ -15403,7 +16615,47 @@ parsers.spnl = parsers.optionalspace * (parsers.newline * parsers.optionalspace)^-1 parsers.line = parsers.linechar^0 * parsers.newline parsers.nonemptyline = parsers.line - parsers.blankline - +% \end{macrocode} +% \begin{figure} +% \hspace*{-0.1\textwidth} +% \begin{minipage}{1.2\textwidth} +% \centering +% \begin{tikzpicture}[shorten >=1pt, line width=0.1mm, >={Stealth[length=2mm]}, node distance=4.5cm, on grid, auto] +% \node[state, initial by diamond, accepting] (noop) {initial}; +% \node[state] (odd_backslash) [above right=of noop] {odd backslash}; +% \node[state] (even_backslash) [below right=of odd_backslash] {even backslash}; +% \node[state] (comment) [below=of noop] {comment}; +% \node[state] (leading_spaces) [below=of even_backslash, align=center] {leading tabs\\and spaces}; +% \node[state] (blank_line) [below right=of comment] {blank line}; +% \path[->] +% (noop) edge [in=150, out=180, loop] node [align=center, yshift=-0.75cm] {match [$^\wedge$\textbackslash\%]\\capture \textbackslash$\!^{2k}$\meta{match}\\reset $k$} () +% edge [bend right=10] node [below right=-0.2cm] {match \textbackslash} (odd_backslash) +% edge [bend left=30] node [left, align=center] {match \%\\capture \textbackslash$\!^k$\\reset $k$} (comment) +% (comment) edge [in=305, out=325, loop] node [xshift=-1.2cm] {match [$^\wedge$$\drsh$]} () +% edge [bend left=10] node {match $\drsh$} (leading_spaces) +% (leading_spaces) edge [loop below] node {match [\textvisiblespace$\rightleftarrows$]} () +% edge [bend right=90] node [right] {match \textbackslash} (odd_backslash) +% edge [bend left=10] node {match \%} (comment) +% edge [bend right=10] node {$\epsilon$} (blank_line) +% edge [bend left=10] node [align=center, right=0.3cm] {match [$^\wedge$\textvisiblespace$\rightleftarrows$$\drsh$\textbackslash\%]\\capture \meta{match}} (noop) +% (blank_line) edge [loop below] node {match [\textvisiblespace$\rightleftarrows$]} () +% edge [bend left=90] node [align=center, below=1.2cm] {match $\drsh$\\ capture $\drsh\drsh$} (noop) +% (odd_backslash) edge [bend right=10] node [align=center, xshift=-0.3cm, yshift=0.2cm] {match \textbackslash\\increment $k$} (even_backslash) +% edge [bend right=10] node [align=center, above left=-0.3cm, xshift=0.1cm] {match [$^\wedge$\textbackslash]\\for \%, capture \textbackslash$\!^k$\%\\for [$^\wedge$\%], capture \textbackslash$\!^{2k+1}$\meta{match}\\reset $k$} (noop) +% (even_backslash) edge [bend left=10] node {$\epsilon$} (noop); +% \end{tikzpicture} +% \caption{A pushdown automaton that recognizes \TeX{} comments} +% \label{fig:commented_line} +% \end{minipage} +% \end{figure} +% \begin{markdown} +% +% The \luamdef{parsers.commented_line}`^1` parser recognizes the regular +% language of \TeX{} comments, see an equivalent finite automaton in Figure +% \vref{fig:commented_line}. +% +% \end{markdown} +% \begin{macrocode} parsers.commented_line_letter = parsers.linechar + parsers.newline - parsers.backslash @@ -15442,7 +16694,9 @@ parsers.commented_line = Cg(Cc(""), "backslashes") + parsers.percent -- comment * parsers.line * parsers.optionalspace) -- leading tabs and spaces - + C(parsers.newline)) + + #(parsers.newline) + * Cb("backslashes") + * C(parsers.newline)) parsers.chunk = parsers.line * (parsers.optionallyindentedline - parsers.blankline)^0 @@ -15490,6 +16744,16 @@ parsers.bullet = ( parsers.bulletchar * #parsers.spacing + parsers.space * parsers.space * parsers.space * parsers.bulletchar * #parsers.spacing ) + +local function tickbox(interior) + return parsers.optionalspace * parsers.lbracket + * interior * parsers.rbracket * parsers.spacechar^1 +end + +parsers.ticked_box = tickbox(S("xX")) * Cc(1.0) +parsers.halfticked_box = tickbox(S("./")) * Cc(0.5) +parsers.unticked_box = tickbox(parsers.spacechar^1) * Cc(0.0) + % \end{macrocode} % \par % \begin{markdown} @@ -16052,6 +17316,11 @@ parsers.BacktickFencedCode * Cs(parsers.fencedline(parsers.backtick)^0) * parsers.fencetail(parsers.backtick) +parsers.JekyllFencedCode + = parsers.fencehead(parsers.dash) + * Cs(parsers.fencedline(parsers.dash)^0) + * parsers.fencetail(parsers.dash) + parsers.lineof = function(c) return (parsers.leader * (P(c) * parsers.optionalspace)^3 * (parsers.newline * parsers.blankline^1 @@ -16114,24 +17383,24 @@ end % %### Markdown Reader % \label{sec:markdownreader} -% This section documents the \luam{reader} object, which implements the +% This section documents the \luamref{reader} object, which implements the % routines for parsing the markdown input. The object corresponds to the % markdown reader object that was located in the % `lunamark/reader/markdown.lua` file in the Lunamark Lua module. % % Although not specified in the Lua interface (see Section -% \ref{sec:luainterface}), the \luam{reader} object is exported, so that the +% \vref{sec:luainterface}), the \luamref{reader} object is exported, so that the % curious user could easily tinker with the methods of the objects produced by -% the \luam{reader.new} method described below. The user should be aware, +% the \luamref{reader.new} method described below. The user should be aware, % however, that the implementation may change in a future revision. % % The \luamdef{reader.new} method creates and returns a new \TeX{} reader % object associated with the Lua interface options (see Section -% \ref{sec:luaoptions}) `options` and with a writer object `writer`. When +% \vref{sec:luaoptions}) `options` and with a writer object `writer`. When % `options` are unspecified, it is assumed that an empty table was passed to % the method. % -% The objects produced by the \luam{reader.new} method expose instance methods +% The objects produced by the \luamref{reader.new} method expose instance methods % and variables of their own. As a convention, I will refer to these % \meta{member}s as `reader->`\meta{member}. % @@ -16145,7 +17414,7 @@ function M.reader.new(writer, options) % \par % \begin{markdown} % -% Make the `options` table inherit from the \luam{defaultOptions} table. +% Make the `options` table inherit from the \luamref{defaultOptions} table. % % \end{markdown} % \begin{macrocode} @@ -16206,9 +17475,9 @@ function M.reader.new(writer, options) % \par % \begin{markdown} % -% The \luamdef{larsers} (as in ``local \luam{parsers}'') hash table stores +% The \luamdef{larsers} (as in ``local \luamref{parsers}'') hash table stores % \acro{peg} patterns that depend on the received `options`, which impedes -% their reuse between different \luam{reader} objects. +% their reuse between different \luamref{reader} objects. % % \end{markdown} % \begin{macrocode} @@ -16274,7 +17543,7 @@ function M.reader.new(writer, options) end end end - + local parse_blocks = create_parser("parse_blocks", function() @@ -16728,6 +17997,19 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline expandtabs(code)) end + larsers.JekyllData = P("---") + * parsers.blankline / 0 + * #(-parsers.blankline) -- if followed by blank, it's an hrule + * C((parsers.line - P("---") - P("..."))^0) + * (P("---") + P("...")) + / function(text) + local tinyyaml = require("markdown-tinyyaml") + data = tinyyaml.parse(text) + return writer.jekyllData(data, function(s) + return parse_blocks(s) + end, nil) + end + larsers.Blockquote = Cs(larsers.blockquote_body^1) / parse_blocks_toplevel / writer.blockquote @@ -16769,6 +18051,15 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline % \begin{macrocode} larsers.starter = parsers.bullet + larsers.enumerator + if options.taskLists then + larsers.tickbox = ( parsers.ticked_box + + parsers.halfticked_box + + parsers.unticked_box + ) / writer.tickbox + else + larsers.tickbox = parsers.fail + end + -- we use \001 as a separator between a tight list item and a -- nested list under it. larsers.NestedList = Cs((parsers.optionallyindentedline @@ -16786,14 +18077,14 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline larsers.TightListItem = function(starter) return -larsers.HorizontalRule - * (Cs(starter / "" * larsers.ListBlock * larsers.NestedList^-1) + * (Cs(starter / "" * larsers.tickbox^-1 * larsers.ListBlock * larsers.NestedList^-1) / parse_blocks) * -(parsers.blanklines * parsers.indent) end larsers.LooseListItem = function(starter) return -larsers.HorizontalRule - * Cs( starter / "" * larsers.ListBlock * Cc("\n") + * Cs( starter / "" * larsers.tickbox^-1 * larsers.ListBlock * Cc("\n") * (larsers.NestedList + larsers.ListContinuationBlock^0) * (parsers.blanklines / "\n\n") ) / parse_blocks @@ -16944,7 +18235,10 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline Blank = larsers.Blank, + JekyllData = larsers.JekyllData, + Block = V("ContentBlock") + + V("JekyllData") + V("Blockquote") + V("PipeTable") + V("Verbatim") @@ -17068,8 +18362,8 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline syntax.InlineNote = parsers.fail end - if not options.smartEllipses then - syntax.Smart = parsers.fail + if not options.jekyllData then + syntax.JekyllData = parsers.fail end if options.preserveTabs then @@ -17080,6 +18374,10 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline syntax.PipeTable = parsers.fail end + if not options.smartEllipses then + syntax.Smart = parsers.fail + end + local blocks_toplevel_t = util.table_copy(syntax) blocks_toplevel_t.Paragraph = larsers.ToplevelParagraph larsers.blocks_toplevel = Ct(blocks_toplevel_t) @@ -17126,7 +18424,7 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline % \begin{markdown} % When determining the name of the cache file, create salt for the hashing % function out of the package version and the passed options recognized by the -% Lua interface (see Section \ref{sec:luaoptions}). The \Opt{cacheDir} option +% Lua interface (see Section \vref{sec:luaoptions}). The \Opt{cacheDir} option % is disregarded. % \end{markdown} % \begin{macrocode} @@ -17142,7 +18440,7 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline % \end{macrocode} % \begin{markdown} % Produce the cache file and transform its filename to plain \TeX{} output -% via the \luam{writer->pack} method. +% via the \luamref{writer->pack} method. % \end{markdown} % \begin{macrocode} local name = util.cache(options.cacheDir, input, salt, function(input) @@ -17180,9 +18478,9 @@ end % \begin{markdown} % %### Conversion from Markdown to Plain \TeX{} -% The \luam{new} method returns the \luam{reader->convert} function of a reader +% The \luamref{new} method returns the \luamref{reader->convert} function of a reader % object associated with the Lua interface options (see Section -% \ref{sec:luaoptions}) `options` and with a writer object associated with +% \vref{sec:luaoptions}) `options` and with a writer object associated with % `options`. % % \end{markdown} @@ -17205,7 +18503,7 @@ return M %### Command-Line Implementation % \label{sec:lua-cli-implementation} % The command-line implementation provides the actual conversion routine for -% the command-line interface described in Section~\ref{sec:lua-cli-interface}. +% the command-line interface described in Section~\vref{sec:lua-cli-interface}. % % \end{markdown} % \begin{macrocode} @@ -17276,7 +18574,7 @@ end % The plain \TeX{} implementation provides macros for the interfacing between % \TeX{} and Lua and for the buffering of input text. These macros are then % used to implement the macros for the conversion from markdown to plain \TeX{} -% exposed by the plain \TeX{} interface (see Section \ref{sec:texinterface}). +% exposed by the plain \TeX{} interface (see Section \vref{sec:texinterface}). % %### Logging Facilities % \label{sec:texinterfacelogging} @@ -17302,12 +18600,12 @@ end % %### Finalizing and Freezing the Cache % -% When the \m{markdownOptionFinalizeCache} option is enabled, then the +% When the \mref{markdownOptionFinalizeCache} option is enabled, then the % \mdef{markdownFrozenCacheCounter} counter is used to enumerate the markdown % documents using the Lua interface \Opt{frozenCacheCounter} option. % -% When the \m{markdownOptionFrozenCache} option is enabled, then the -% \m{markdownFrozenCacheCounter} counter is used to render markdown documents +% When the \mref{markdownOptionFrozenCache} option is enabled, then the +% \mref{markdownFrozenCacheCounter} counter is used to render markdown documents % from the frozen cache without invoking Lua. % % \end{markdown} @@ -17386,14 +18684,17 @@ end \def\markdownRendererFootnotePrototype#1{#1}% \def\markdownRendererCitePrototype#1{}% \def\markdownRendererTextCitePrototype#1{}% +\def\markdownRendererTickedBoxPrototype{[X]}% +\def\markdownRendererHalfTickedBoxPrototype{[/]}% +\def\markdownRendererUntickedBoxPrototype{[ ]}% % \end{macrocode} % \par % \begin{markdown} % %### Lua Snippets % The \mdef{markdownLuaOptions} macro expands to a Lua table that -% contains the plain \TeX{} options (see Section \ref{sec:texoptions}) in a -% format recognized by Lua (see Section \ref{sec:luaoptions}). +% contains the plain \TeX{} options (see Section \vref{sec:texoptions}) in a +% format recognized by Lua (see Section \vref{sec:luaoptions}). % % \end{markdown} % \begin{macrocode} @@ -17456,6 +18757,9 @@ end \ifx\markdownOptionInlineFootnotes\undefined\else inlineFootnotes = \markdownOptionInlineFootnotes, \fi +\ifx\markdownOptionJekyllData\undefined\else + jekyllData = \markdownOptionJekyllData, +\fi \ifx\markdownOptionPipeTables\undefined\else pipeTables = \markdownOptionPipeTables, \fi @@ -17480,6 +18784,9 @@ end \ifx\markdownOptionTableCaptions\undefined\else tableCaptions = \markdownOptionTableCaptions, \fi +\ifx\markdownOptionTaskLists\undefined\else + taskLists = \markdownOptionTaskLists, +\fi \ifx\markdownOptionTeXComments\undefined\else texComments = \markdownOptionTeXComments, \fi @@ -17496,14 +18803,14 @@ end % % The \mdef{markdownPrepare} macro contains the Lua code that is executed prior % to any conversion from markdown to plain \TeX{}. It exposes the -% \luam{convert} function for the use by any further Lua code. +% \luamref{convert} function for the use by any further Lua code. % % \end{markdown} % \begin{macrocode} \def\markdownPrepare{% % \end{macrocode} % \begin{markdown} -% First, ensure that the \m{markdownOptionCacheDir} directory exists. +% First, ensure that the \mref{markdownOptionCacheDir} directory exists. % \end{markdown} % \begin{macrocode} local lfs = require("lfs") @@ -17515,7 +18822,7 @@ end % \begin{markdown} % Next, load the `markdown` module and create a converter function using % the plain \TeX{} options, which were serialized to a Lua table via the -% \m{markdownLuaOptions} macro. +% \mref{markdownLuaOptions} macro. % \end{markdown} % \begin{macrocode} local md = require("markdown") @@ -17569,8 +18876,8 @@ end % \par % \begin{markdown} % -% The \m{markdownReadAndConvert} macro is largely a rewrite of the -% \Hologo{LaTeX2e} \m{filecontents} macro to plain \TeX{}. +% The \mref{markdownReadAndConvert} macro is largely a rewrite of the +% \Hologo{LaTeX2e} \mref{filecontents} macro to plain \TeX{}. % % \end{markdown} % \begin{macrocode} @@ -17582,7 +18889,7 @@ end % backslash as an ordinary character inside the macro definition. Likewise, % swap the character codes of the percent sign (`%`) and the ampersand (`@`), % so that we can remove percent signs from the beginning of lines when -% \m{markdownOptionStripPercentSigns} is enabled. +% \mref{markdownOptionStripPercentSigns} is enabled. % \end{markdown} % \begin{macrocode} \catcode`\^^M=13% @@ -17596,7 +18903,7 @@ end % \end{macrocode} % \begin{markdown} % If we are not reading markdown documents from the frozen cache, -% open the \m{markdownOptionInputTempFileName} file for writing. +% open the \mref{markdownOptionInputTempFileName} file for writing. % \end{markdown} % \begin{macrocode} |markdownIfOption{FrozenCache}{}{@ @@ -17621,7 +18928,7 @@ end % \begin{markdown} % The \mdef{markdownReadAndConvertStripPercentSigns} macro will process the % individual lines of output, stipping away leading percent signs (`%`) when -% \m{markdownOptionStripPercentSigns} is enabled. +% \mref{markdownOptionStripPercentSigns} is enabled. % Notice the use of the comments (`@`) to ensure that the entire macro is at % a single line and therefore no (active) newline symbols % (`^^M`) are produced. @@ -17657,7 +18964,7 @@ end % \begin{markdown} % If we are not reading markdown documents from the frozen cache and the ending % token sequence does not appear in the line, store the line in the -% \m{markdownOptionInputTempFileName} file. +% \mref{markdownOptionInputTempFileName} file. % If we are reading markdown documents from the frozen cache and the % ending token sequence does not appear in the line, gobble the line. % \end{markdown} @@ -17670,10 +18977,10 @@ end % \end{macrocode} % \begin{markdown} % When the ending token sequence appears in the line, make the next newline -% character close the \m{markdownOptionInputTempFileName} file, return the +% character close the \mref{markdownOptionInputTempFileName} file, return the % character categories back to the former state, convert the -% \m{markdownOptionInputTempFileName} file from markdown to plain \TeX{}, -% \m{input} the result of the conversion, and expand the ending control +% \mref{markdownOptionInputTempFileName} file from markdown to plain \TeX{}, +% \mref{input} the result of the conversion, and expand the ending control % sequence. % \end{markdown} % \begin{macrocode} @@ -17707,7 +19014,7 @@ end % \begin{markdown} % Make the newline character active at expansion time and make it consume the % rest of the line on expansion. Throw away the rest of the first line and -% pass the second line to the \m{markdownReadAndConvertProcessLine} macro. +% pass the second line to the \mref{markdownReadAndConvertProcessLine} macro. % \end{markdown} % \begin{macrocode} |catcode`|^^M=13@ @@ -17730,10 +19037,10 @@ end % \label{sec:luabridge} % The following \TeX{} code is intended for \TeX{} engines that do not provide % direct access to Lua, but expose the shell of the operating system. This -% corresponds to the \m{markdownMode} values of `0` and `1`. +% corresponds to the \mref{markdownMode} values of `0` and `1`. % -% The \m{markdownLuaExecute} macro defined here and in Section -% \ref{sec:directlua} are meant to be indistinguishable to the remaining code. +% The \mref{markdownLuaExecute} macro defined here and in Section +% \vref{sec:directlua} are meant to be indistinguishable to the remaining code. % % The package assumes that although the user is not using the Lua\TeX{} engine, % their \TeX{} distribution contains it, and uses shell access to produce and @@ -17756,10 +19063,10 @@ end % whether the shell access is enabled (`1`), disabled (`0`), or restricted % (`2`). % -% Inherit the value of the the \m{pdfshellescape} (Lua\TeX{}, \Hologo{pdfTeX}) -% or the \m{shellescape} (\Hologo{XeTeX}) commands. If neither of these +% Inherit the value of the the \mref{pdfshellescape} (Lua\TeX{}, \Hologo{pdfTeX}) +% or the \mref{shellescape} (\Hologo{XeTeX}) commands. If neither of these % commands is defined and Lua is available, attempt to access the -% \luam{status.shell_escape} configuration item. +% \luamref{status.shell_escape} configuration item. % % If you cannot detect, whether the shell access is enabled, act as if it were. % @@ -17785,7 +19092,7 @@ end % % The \mdef{markdownExecuteDirect} macro executes the code it has received as % its first argument by writing it to the output file stream 18, if Lua is -% unavailable, or by using the Lua \luam{os.execute} method otherwise. +% unavailable, or by using the Lua \luamref{os.execute} method otherwise. % % \end{markdown} % \begin{macrocode} @@ -17800,8 +19107,8 @@ end % \begin{markdown} % % The \mdef{markdownExecute} macro is a wrapper on top of -% \m{markdownExecuteDirect} that checks the value of -% \m{markdownExecuteShellEscape} and prints an error message if the shell is +% \mref{markdownExecuteDirect} that checks the value of +% \mref{markdownExecuteShellEscape} and prints an error message if the shell is % inaccessible. % % \end{markdown} @@ -17820,8 +19127,8 @@ end % % The \mdef{markdownLuaExecute} macro executes the Lua code it has received as % its first argument. The Lua code may not directly interact with the \TeX{} -% engine, but it can use the \luam{print} function in the same manner it -% would use the \luam{tex.print} method. +% engine, but it can use the \luamref{print} function in the same manner it +% would use the \luamref{tex.print} method. % % \end{markdown} % \begin{macrocode} @@ -17837,7 +19144,7 @@ end |gdef|markdownLuaExecute#1{% % \end{macrocode} % \begin{markdown} -% Create the file \m{markdownOptionHelperScriptFileName} and fill it with the +% Create the file \mref{markdownOptionHelperScriptFileName} and fill it with the % input Lua code prepended with \pkg{kpathsea} initialization, so that Lua % modules from the \TeX{} distribution are available. % \end{markdown} @@ -17854,7 +19161,7 @@ end end) % \end{macrocode} % \begin{markdown} -% If there was an error, use the file \m{markdownOptionErrorTempFileName} to +% If there was an error, use the file \mref{markdownOptionErrorTempFileName} to % store the error message. % \end{markdown} % \begin{macrocode} @@ -17874,9 +19181,9 @@ end |immediate|closeout|markdownOutputFileStream % \end{macrocode} % \begin{markdown} -% Execute the generated \m{markdownOptionHelperScriptFileName} Lua script using +% Execute the generated \mref{markdownOptionHelperScriptFileName} Lua script using % the \TeX{}Lua binary and store the output in the -% \m{markdownOptionOutputTempFileName} file. +% \mref{markdownOptionOutputTempFileName} file. % \end{markdown} % \begin{macrocode} |markdownInfo{Executing a helper Lua script from the file @@ -17888,7 +19195,7 @@ end /|markdownOptionOutputTempFileName"}% % \end{macrocode} % \begin{markdown} -% \m{input} the generated \m{markdownOptionOutputTempFileName} file. +% \mref{input} the generated \mref{markdownOptionOutputTempFileName} file. % \end{markdown} % \begin{macrocode} |input|markdownOptionOutputTempFileName|relax}% @@ -17900,9 +19207,9 @@ end %### Direct Lua Access % \label{sec:directlua} % The following \TeX{} code is intended for \TeX{} engines that provide -% direct access to Lua (Lua\TeX{}). The macro \m{markdownLuaExecute} defined -% here and in Section \ref{sec:luabridge} are meant to be indistinguishable to -% the remaining code. This corresponds to the \m{markdownMode} value of `2`. +% direct access to Lua (Lua\TeX{}). The macro \mref{markdownLuaExecute} defined +% here and in Section \vref{sec:luabridge} are meant to be indistinguishable to +% the remaining code. This corresponds to the \mref{markdownMode} value of `2`. % % \end{markdown} % \begin{macrocode} @@ -17912,10 +19219,10 @@ end % \par % \begin{markdown} % -% The direct Lua access version of the \m{markdownLuaExecute} macro is defined -% in terms of the \m{directlua} primitive. The \luam{print} function is set as -% an alias to the \m{tex.print} method in order to mimic the behaviour of the -% \m{markdownLuaExecute} definition from Section \ref{sec:luabridge}, +% The direct Lua access version of the \mref{markdownLuaExecute} macro is defined +% in terms of the \mref{directlua} primitive. The \luamref{print} function is set as +% an alias to the \mref{tex.print} method in order to mimic the behaviour of the +% \mref{markdownLuaExecute} definition from Section \vref{sec:luabridge}, % % \end{markdown} % \begin{macrocode} @@ -17927,8 +19234,8 @@ end % %### Typesetting Markdown % -% The \m{markdownInput} macro uses an implementation of the -% \m{markdownLuaExecute} macro to convert the contents of the file whose +% The \mref{markdownInput} macro uses an implementation of the +% \mref{markdownLuaExecute} macro to convert the contents of the file whose % filename it has received as its single argument from markdown to plain % \TeX{}. % @@ -17957,7 +19264,7 @@ end % \begin{markdown} % If we are reading from the frozen cache, input it, expand the corresponding % `\markdownFrozenCache`\meta{number} macro, and increment -% \m{markdownFrozenCacheCounter}. +% \mref{markdownFrozenCacheCounter}. % \end{markdown} % \begin{macrocode} |markdownIfOption{FrozenCache}{% @@ -17998,7 +19305,7 @@ end % \end{macrocode} % \begin{markdown} % If we are finalizing the frozen cache, increment -% \m{markdownFrozenCacheCounter}. +% \mref{markdownFrozenCacheCounter}. % \end{markdown} % \begin{macrocode} |markdownIfOption{FinalizeCache}{% @@ -18025,8 +19332,8 @@ end % existing plain \TeX{} implementation. % % The \LaTeX{} implementation redefines the plain \TeX{} logging macros (see -% Section \ref{sec:texinterfacelogging}) to use the \LaTeX{} \m{PackageInfo}, -% \m{PackageWarning}, and \m{PackageError} macros. +% Section \vref{sec:texinterfacelogging}) to use the \LaTeX{} \mref{PackageInfo}, +% \mref{PackageWarning}, and \mref{PackageError} macros. % % \end{markdown} % \begin{macrocode} @@ -18043,8 +19350,8 @@ end % %### Logging Facilities % The \LaTeX{} implementation redefines the plain \TeX{} logging macros (see -% Section \ref{sec:texinterfacelogging}) to use the \LaTeX{} \m{PackageInfo}, -% \m{PackageWarning}, and \m{PackageError} macros. +% Section \vref{sec:texinterfacelogging}) to use the \LaTeX{} \mref{PackageInfo}, +% \mref{PackageWarning}, and \mref{PackageError} macros. % % \end{markdown} % \begin{macrocode} @@ -18054,9 +19361,9 @@ end % %### Typesetting Markdown % The \mdef{markdownInputPlainTeX} macro is used to store the original plain -% \TeX{} implementation of the \m{markdownInput} macro. The \m{markdownInput} +% \TeX{} implementation of the \mref{markdownInput} macro. The \mref{markdownInput} % is then redefined to accept an optional argument with options recognized by -% the \LaTeX{} interface (see Section \ref{sec:latexoptions}). +% the \LaTeX{} interface (see Section \vref{sec:latexoptions}). % % \end{markdown} % \begin{macrocode} @@ -18070,8 +19377,8 @@ end % \par % \begin{markdown} % -% The \envm{markdown}, and \envm{markdown*} \LaTeX{} environments are -% implemented using the \m{markdownReadAndConvert} macro. +% The \envmref{markdown}, and \envmref{markdown*} \LaTeX{} environments are +% implemented using the \mref{markdownReadAndConvert} macro. % % \end{markdown} % \begin{macrocode} @@ -18103,7 +19410,7 @@ end % \begin{markdown} % %### Options -% The supplied package options are processed using the \m{markdownSetup} macro. +% The supplied package options are processed using the \mref{markdownSetup} macro. % % \end{markdown} % \begin{macrocode} @@ -18144,6 +19451,15 @@ end % \end{macrocode} % \begin{markdown} % +% We load the \pkg{ifthen} and \pkg{grffile} packages, see also +% Section~\ref{sec:latexprerequisites}: +% +% \end{markdown} +% \begin{macrocode} +\RequirePackage{ifthen,grffile} +% \end{macrocode} +% \begin{markdown} +% % We store the previous definition of the fenced code token renderer prototype: % % \end{markdown} @@ -18155,12 +19471,11 @@ end % % If the infostring starts with `dot …`, we redefine the fenced code block % token renderer prototype, so that it typesets the code block via Graphviz -% tools if and only if the \m{markdownOptionFrozenCache} plain \TeX{} option is +% tools if and only if the \mref{markdownOptionFrozenCache} plain \TeX{} option is % disabled and the code block has not been previously typeset: % % \end{markdown} % \begin{macrocode} -\RequirePackage{ifthen} \renewcommand\markdownRendererInputFencedCode[2]{% \def\next##1 ##2\relax{% \ifthenelse{\equal{##1}{dot}}{% @@ -18210,8 +19525,17 @@ end % \end{macrocode} % \begin{markdown} % -% We define the \m{markdown@witiko@graphicx@http@counter} counter to enumerate -% the images for caching and the \m{markdown@witiko@graphicx@http@filename} +% We load the \pkg{catchfile} and \pkg{grffile} packages, see also +% Section~\ref{sec:latexprerequisites}: +% +% \end{markdown} +% \begin{macrocode} +\RequirePackage{catchfile,grffile} +% \end{macrocode} +% \begin{markdown} +% +% We define the \mref{markdown@witiko@graphicx@http@counter} counter to enumerate +% the images for caching and the \mref{markdown@witiko@graphicx@http@filename} % command, which will store the pathname of the file containing the pathname % of the downloaded image file. % @@ -18225,7 +19549,7 @@ end % \end{macrocode} % \begin{markdown} % -% We define the \m{markdown@witiko@graphicx@http@download} command, which will +% We define the \mref{markdown@witiko@graphicx@http@download} command, which will % receive two arguments that correspond to the URL of the online image and to % the pathname, where the online image should be downloaded. The command will % produce a shell command that tries to downloads the online image to the @@ -18261,7 +19585,7 @@ end % \begin{markdown} % % The image will be downloaded only if the image URL has the http or https -% protocols and the \m{markdownOptionFrozenCache} plain \TeX{} option is disabled: +% protocols and the \mref{markdownOptionFrozenCache} plain \TeX{} option is disabled: % % \end{markdown} % \begin{macrocode} @@ -18272,7 +19596,7 @@ end % \end{macrocode} % \begin{markdown} % -% The image will be downloaded to the pathname \m{markdownOptionCacheDir}<!-- +% The image will be downloaded to the pathname \mref{markdownOptionCacheDir}<!-- % -->`/`\meta{the MD5 digest of the image URL}`.`\meta{the suffix of the % image URL}: % @@ -18313,7 +19637,7 @@ end % % \end{markdown} % \begin{macrocode} - \CatchFileDef{\filename}{\filename}{}^^A + \CatchFileDef{\filename}{\filename}{\endlinechar=-1}^^A \markdown@witiko@graphicx@http@oldRendererImagePrototype^^A {#1}{#2}{\filename}{#4}^^A \endgroup @@ -18342,32 +19666,33 @@ end % \begin{markdown} % %### Token Renderer Prototypes +% \label{sec:latexdefaultrendererprototypes} % The following configuration should be considered placeholder. If the `plain` -% package option has been enabled (see Section \ref{sec:latexplain}), none of +% package option has been enabled (see Section \vref{sec:latexplain}), none of % it will take effect. % \end{markdown} % \begin{macrocode} \ifmarkdownLaTeXPlain\else % \end{macrocode} % \par -% \begin{markdown} -% -% If the \m{markdownOptionTightLists} macro expands to `false`, do not load +% \begin{markdown}% +% If the \mref{markdownOptionTightLists} macro expands to `false`, do not load % the \pkg{paralist} package. This is necessary for \Hologo{LaTeX2e} document % classes that do not play nice with \pkg{paralist}, such as \pkg{beamer}. -% If the \m{markdownOptionTightLists} is undefined and the \pkg{beamer} +% If the \mref{markdownOptionTightLists} is undefined and the \pkg{beamer} % document class is in use, then do not load the \pkg{paralist} package either. % % \end{markdown} % \begin{macrocode} \RequirePackage{ifthen} -\@ifundefined{markdownOptionTightLists}{% + +\ifx\markdownOptionTightLists\undefined \@ifclassloaded{beamer}{}{% \RequirePackage{paralist}}% -}{% +\else \ifthenelse{\equal{\markdownOptionTightLists}{false}}{}{% \RequirePackage{paralist}}% -}% +\fi % \end{macrocode} % \par % \begin{markdown} @@ -18395,6 +19720,8 @@ end olEndTight = {\markdownRendererOlEnd}, dlBeginTight = {\markdownRendererDlBegin}, dlEndTight = {\markdownRendererDlEnd}}}} +\RequirePackage{amsmath} +\RequirePackage{amssymb} \RequirePackage{csvsimple} \RequirePackage{fancyvrb} \RequirePackage{graphicx} @@ -18431,7 +19758,6 @@ end \label{fig:#1}% \end{figure}}, ulBegin = {\begin{itemize}}, - ulItem = {\item{}}, ulEnd = {\end{itemize}}, olBegin = {\begin{enumerate}}, olItem = {\item{}}, @@ -18441,6 +19767,9 @@ end dlItem = {\item[#1]}, dlEnd = {\end{description}}, emphasis = {\emph{#1}}, + tickedBox = {$\boxtimes$}, + halfTickedBox = {$\boxdot$}, + untickedBox = {$\square$}, blockQuoteBegin = {\begin{quotation}}, blockQuoteEnd = {\end{quotation}}, inputVerbatim = {\VerbatimInput{#1}}, @@ -18517,9 +19846,46 @@ end % \par % \begin{markdown} % -% There is a basic implementation for citations that uses the \LaTeX{} \m{cite} -% macro. There are also implementations that use the \pkg{natbib} \m{citep}, -% and \m{citet} macros, and the Bib\LaTeX{} \m{autocites} and \m{textcites} +%#### Tickboxes +% If the \Opt{taskLists} option is enabled, we will hide bullets in unordered +% list items with tickboxes. +% +% \end{markdown} +% \begin{macrocode} +\markdownSetup{ + rendererPrototypes = { + ulItem = {% + \futurelet\markdownLaTeXCheckbox\markdownLaTeXUlItem + }, + }, +} +\def\markdownLaTeXUlItem{% + \ifx\markdownLaTeXCheckbox\markdownRendererTickedBox + \item[\markdownLaTeXCheckbox]% + \expandafter\@gobble + \else + \ifx\markdownLaTeXCheckbox\markdownRendererHalfTickedBox + \item[\markdownLaTeXCheckbox]% + \expandafter\expandafter\expandafter\@gobble + \else + \ifx\markdownLaTeXCheckbox\markdownRendererUntickedBox + \item[\markdownLaTeXCheckbox]% + \expandafter\expandafter\expandafter\expandafter + \expandafter\expandafter\expandafter\@gobble + \else + \item{}% + \fi + \fi + \fi +} +% \end{macrocode} +% \par +% \begin{markdown} +% +%#### Citations +% Here is a basic implementation for citations that uses the \LaTeX{} \mref{cite} +% macro. There are also implementations that use the \pkg{natbib} \mref{citep}, +% and \mref{citet} macros, and the Bib\LaTeX{} \mref{autocites} and \mref{textcites} % macros. These implementations will be used, when the respective packages are % loaded. % @@ -18748,6 +20114,7 @@ end % \par % \begin{markdown} % +%#### Links % Before consuming the parameters for the hyperlink renderer, we change the % category code of the hash sign (`#`) to other, so that it cannot be % mistaken for a parameter character. After the hyperlink has been typeset, @@ -18768,7 +20135,8 @@ end % \par % \begin{markdown} % -% There is a basic implementation of tables. If the \pkg{booktabs} package is +%#### Tables +% Here is a basic implementation of tables. If the \pkg{booktabs} package is % loaded, then it is used to produce horizontal lines. % % \end{markdown} @@ -18854,10 +20222,312 @@ end % \par % \begin{markdown} % +%#### YAML Metadata +% \label{sec:latexyamlmetadata} +% To parse the \acro{yaml} metadata we will use the expl3 language from the +% \LaTeX3 kernel. +% +% \end{markdown} +% \begin{macrocode} +\RequirePackage{expl3} +\ExplSyntaxOn +% \end{macrocode} +% \par +% \begin{markdown} +% +% To keep track of the current type of structure we inhabit when we are +% traversing a \acro{yaml} document, we will maintain the +% \mdef{g_\@\@_jekyll_data_datatypes_seq} stack. At every step of the traversal, +% the stack will contain one of the following constants at any position $p$: +% +% \mdef{c_\@\@_jekyll_data_sequence_tl} +% +%: The currently traversed branch of the \acro{yaml} document contains a sequence +% at depth $p$. +% +% \mdef{c_\@\@_jekyll_data_mapping_tl} +% +%: The currently traversed branch of the \acro{yaml} document contains a mapping +% at depth $p$. +% +% \mdef{c_\@\@_jekyll_data_scalar_tl} +% +%: The currently traversed branch of the \acro{yaml} document contains a scalar +% value at depth $p$. +% +% \end{markdown} +% \begin{macrocode} +\seq_new:N \g_@@_jekyll_data_datatypes_seq +\tl_const:Nn \c_@@_jekyll_data_sequence_tl { sequence } +\tl_const:Nn \c_@@_jekyll_data_mapping_tl { mapping } +\tl_const:Nn \c_@@_jekyll_data_scalar_tl { scalar } +% \end{macrocode} +% \par +% \begin{markdown} +% +% To keep track of our current place when we are traversing a \acro{yaml} +% document, we will maintain the +% \mdef{g_\@\@_jekyll_data_wildcard_absolute_address_seq} stack of keys using +% the \mdef{markdown_jekyll_data_push_address_segment:n} macro. +% +% \end{markdown} +% \begin{macrocode} +\seq_new:N \g_@@_jekyll_data_wildcard_absolute_address_seq +\cs_new:Nn \markdown_jekyll_data_push_address_segment:n + { + \seq_if_empty:NF + \g_@@_jekyll_data_datatypes_seq + { + \seq_get_right:NN + \g_@@_jekyll_data_datatypes_seq + \l_tmpa_tl +% \end{macrocode} +% \begin{markdown} +% +% If we are currently in a sequence, we will put an asterisk (`*`) instead of +% a key into \mref{g_\@\@_jekyll_data_wildcard_absolute_address_seq} to make +% it represent a *wildcard*. Keeping a wildcard instead of a precise address +% makes it easy for the users to react to *any* item of a sequence regardless +% of how many there are, which can often be useful. +% +% \end{markdown} +% \begin{macrocode} + \tl_if_eq:NNTF + \l_tmpa_tl + \c_@@_jekyll_data_sequence_tl + { + \seq_put_right:Nn + \g_@@_jekyll_data_wildcard_absolute_address_seq + { * } + } + { + \seq_put_right:Nn + \g_@@_jekyll_data_wildcard_absolute_address_seq + { #1 } + } + } + } +% \end{macrocode} +% \par +% \begin{markdown} +% +% Out of \mref{g_\@\@_jekyll_data_wildcard_absolute_address_seq}, we will +% construct the following two token lists: +% +% \mdef{g_\@\@_jekyll_data_wildcard_absolute_address_tl} +% +%: An *absolute wildcard*: The wildcard from the root of the document +% prefixed with a slash (`/`) with individual keys and asterisks also +% delimited by slashes. Allows the users to react to complex +% context-sensitive structures with ease. +% +%: For example, the `name` key in the following \acro{yaml} document +% would correspond to the `/*/person/name` absolute wildcard: +% ``` yaml +% [{person: {name: Elon, surname: Musk}}] +% ``` +% +% \mdef{g_\@\@_jekyll_data_wildcard_relative_address_tl} +% +%: A *relative wildcard*: The rightmost segment of the wildcard. Allows the +% users to react to simple context-free structures. +% +%: For example, the `name` key in the following \acro{yaml} document +% would correspond to the `name` relative wildcard: +% ``` yaml +% [{person: {name: Elon, surname: Musk}}] +% ``` +% +% We will construct \mref{g_\@\@_jekyll_data_wildcard_absolute_address_tl} +% using the \mdef{markdown_jekyll_data_concatenate_address:NN} macro and +% we will construct both token lists using the +% \mdef{markdown_jekyll_data_update_address_tls:} macro. +% +% \end{markdown} +% \begin{macrocode} +\tl_new:N \g_@@_jekyll_data_wildcard_absolute_address_tl +\tl_new:N \g_@@_jekyll_data_wildcard_relative_address_tl +\cs_new:Nn \markdown_jekyll_data_concatenate_address:NN + { + \seq_pop_left:NN #1 \l_tmpa_tl + \tl_set:Nx #2 { / \seq_use:Nn #1 { / } } + \seq_put_left:NV #1 \l_tmpa_tl + } +\cs_new:Nn \markdown_jekyll_data_update_address_tls: + { + \markdown_jekyll_data_concatenate_address:NN + \g_@@_jekyll_data_wildcard_absolute_address_seq + \g_@@_jekyll_data_wildcard_absolute_address_tl + \seq_get_right:NN + \g_@@_jekyll_data_wildcard_absolute_address_seq + \g_@@_jekyll_data_wildcard_relative_address_tl + } +% \end{macrocode} +% \par +% \begin{markdown} +% +% To make sure that the stacks and token lists stay in sync, we will use the +% \mdef{markdown_jekyll_data_push:nN} and \mdef{markdown_jekyll_data_pop:} +% macros. +% +% \end{markdown} +% \begin{macrocode} +\cs_new:Nn \markdown_jekyll_data_push:nN + { + \markdown_jekyll_data_push_address_segment:n + { #1 } + \seq_put_right:NV + \g_@@_jekyll_data_datatypes_seq + #2 + \markdown_jekyll_data_update_address_tls: + } +\cs_new:Nn \markdown_jekyll_data_pop: + { + \seq_pop_right:NN + \g_@@_jekyll_data_wildcard_absolute_address_seq + \l_tmpa_tl + \seq_pop_right:NN + \g_@@_jekyll_data_datatypes_seq + \l_tmpa_tl + \markdown_jekyll_data_update_address_tls: + } +% \end{macrocode} +% \par +% \begin{markdown} +% +% To interface with the user, we use `markdown/jekyllData` key--values from the +% l3keys module of the \LaTeX3 kernel. The default setup will invoke the +% \mref{title}, \mref{author}, and \mref{date} macros when scalar values for +% keys that correspond to the `title`, `author`, and `date` relative wildcards +% are encountered, respectively. +% +% \end{markdown} +% \begin{macrocode} +\keys_define:nn + { markdown/jekyllData } + { + author .code:n = { \author{#1} }, + date .code:n = { \date{#1} }, + title .code:n = { \title{#1} }, + } +% \end{macrocode} +% \begin{markdown} +% +% To set a single key--value, we will use the +% \mdef{markdown_jekyll_data_set_keyval:Nn} macro, ignoring unknown keys. +% To set key--values for both absolute and relative wildcards, we will use the +% \mdef{markdown_jekyll_data_set_keyvals:nn} macro. +% +% \end{markdown} +% \begin{macrocode} +\cs_new:Nn \markdown_jekyll_data_set_keyval:nn + { + \keys_set_known:nn + { markdown/jekyllData } + { { #1 } = { #2 } } + } +\cs_generate_variant:Nn + \markdown_jekyll_data_set_keyval:nn + { Vn } +\cs_new:Nn \markdown_jekyll_data_set_keyvals:nn + { + \markdown_jekyll_data_push:nN + { #1 } + \c_@@_jekyll_data_scalar_tl + \markdown_jekyll_data_set_keyval:Vn + \g_@@_jekyll_data_wildcard_absolute_address_tl + { #2 } + \markdown_jekyll_data_set_keyval:Vn + \g_@@_jekyll_data_wildcard_relative_address_tl + { #2 } + \markdown_jekyll_data_pop: + } +% \end{macrocode} +% \par +% \begin{markdown} +% +% Finally, we will register our macros as token renderer prototypes +% to be able to react to the traversal of a \acro{yaml} document. +% +% \end{markdown} +% \begin{macrocode} +\markdownSetup{ + rendererPrototypes = { + jekyllDataSequenceBegin = { + \markdown_jekyll_data_push:nN + { #1 } + \c_@@_jekyll_data_sequence_tl + }, + jekyllDataMappingBegin = { + \markdown_jekyll_data_push:nN + { #1 } + \c_@@_jekyll_data_mapping_tl + }, + jekyllDataSequenceEnd = { + \markdown_jekyll_data_pop: + }, + jekyllDataMappingEnd = { + \markdown_jekyll_data_pop: + }, + jekyllDataBoolean = { + \markdown_jekyll_data_set_keyvals:nn + { #1 } + { #2 } + }, + jekyllDataEmpty = { }, + jekyllDataNumber = { + \markdown_jekyll_data_set_keyvals:nn + { #1 } + { #2 } + }, + jekyllDataString = { + \markdown_jekyll_data_set_keyvals:nn + { #1 } + { #2 } + }, +% \end{macrocode} +% \begin{markdown} +% +% To complement the default setup of our key--values, we will use +% the \mref{maketitle} macro to typeset the title page of a document +% at the end of \acro{yaml} metadata. If we are in the preamble, we will wait +% macro until after the beginning of the document. Otherwise, we will use +% the \mref{maketitle} macro straight away. +% +% \end{markdown} +% \begin{macrocode} + }, +} +\providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion} +\markdownSetup{ + rendererPrototypes = { + jekyllDataEnd = { + \IfFormatAtLeastTF + { 2020-10-01 } + { \AddToHook{begindocument/end}{\maketitle} } + { + \ifx\@onlypreamble\@notprerr + % We are in the document + \maketitle + \else + % We are in the preamble + \RequirePackage{etoolbox} + \AfterEndPreamble{\maketitle} + \fi + } + }, + }, +} + +\ExplSyntaxOff +% \end{macrocode} +% \par +% \begin{markdown} +% %### Miscellanea % When buffering user input, we should disable the bytes with the high bit set, % since these are made active by the \pkg{inputenc} package. We will do this by -% redefining the \m{markdownMakeOther} macro accordingly. The code is courtesy +% redefining the \mref{markdownMakeOther} macro accordingly. The code is courtesy % of Scott Pakin, the creator of the \pkg{filecontents} package. % % \end{markdown} @@ -18887,8 +20557,8 @@ end % after supplying the missing plain \TeX{} macros. % % The \Hologo{ConTeXt} implementation redefines the plain \TeX{} logging macros -% (see Section \ref{sec:texinterfacelogging}) to use the \Hologo{ConTeXt} -% \m{writestatus} macro. +% (see Section \vref{sec:texinterfacelogging}) to use the \Hologo{ConTeXt} +% \mref{writestatus} macro. % % \end{markdown} % \begin{macrocode} @@ -18902,8 +20572,8 @@ end % \begin{markdown} % % When buffering user input, we should disable the bytes with the high bit set, -% since these are made active by the \m{enableregime} macro. We will do this -% by redefining the \m{markdownMakeOther} macro accordingly. The code is +% since these are made active by the \mref{enableregime} macro. We will do this +% by redefining the \mref{markdownMakeOther} macro accordingly. The code is % courtesy of Scott Pakin, the creator of the \pkg{filecontents} \LaTeX{} % package. % @@ -18930,8 +20600,8 @@ end % \begin{markdown} % %### Typesetting Markdown -% The \m{startmarkdown} and \m{stopmarkdown} macros are implemented using the -% \m{markdownReadAndConvert} macro. +% The \mref{startmarkdown} and \mref{stopmarkdown} macros are implemented using the +% \mref{markdownReadAndConvert} macro. % % \end{markdown} % \begin{macrocode} @@ -19041,7 +20711,7 @@ end % \begin{markdown} % % The code fence infostring is used as a name from the \Hologo{ConTeXt} -% \m{definetyping} macro. This allows the user to set up code highlighting +% \mref{definetyping} macro. This allows the user to set up code highlighting % mapping as follows: % ````` tex % % Map the `TEX` syntax highlighter to the `latex` infostring. @@ -19147,6 +20817,9 @@ end \ifnum\markdownConTeXtColumnCounter<\markdownConTeXtColumnTotal\relax\else \expandafter\gobbleoneargument \fi\markdownConTeXtRenderTableCell} +\def\markdownRendererTickedBox{$\boxtimes$} +\def\markdownRendererHalfTickedBox{$\boxdot$} +\def\markdownRendererUntickedBox{$\square$} % \end{macrocode} % \iffalse %</context> |