3.14.0

Enhancements

This version of the Markdown package has made the following new enhancements:

• Support the new prepending (^=) and appending ($=) operators for renderers and renderer prototypes. (#232, #617)

• Support the prepending and appending operators (^=, +=, and $=) for comma-list options like extensions. (#232, #621)

• In theme witiko/diagrams, add parameter command for Mermaid diagrams. (#616, #622)

  For example, you can use different icon packs as follows:

  \documentclass{article}
  \usepackage[import=witiko/diagrams@v2]{markdown}
  \begin{document}
  \begin{markdown}
  
  ``` mermaid {command = "mmdc --iconPacks '@iconify-json/logos'"}
  architecture-beta
      group api(logos:aws-lambda)[API]
  
      service db(logos:aws-aurora)[Database] in api
      service disk1(logos:aws-glacier)[Storage] in api
      service disk2(logos:aws-s3)[Storage] in api
      service server(logos:aws-ec2)[Server] in api
  
      db:L -- R:server
      disk1:T -- B:server
      disk2:T -- B:db
  ```
  
  \end{markdown}
  \end{document}

  

• Recognize acronyms, initialisms, and other all-caps sequences. (suggested by @Witiko, @michal-h21, and @TeXhackse in #615 and at matrix.org, implemented in #623 and e274753..3e14fa1)

  For example, you can automatically format acronyms in your LaTeX documents as follows:

  \documentclass{article}
  \usepackage[plain]{markdown}
  \markdownSetup {
    % Format the following words as acronyms.
    acronyms = {HTML, YAML},  % We can also easily fill this list from e.g. YAML and other external sources.
    renderers = {
      % Format acronyms as small caps.
      acronym = \textsc{\MakeLowercase{#1}},
    },
  }
  \begin{document}
  \begin{markdown}
  
  HTML and YAML are two staples of modern tooling that often get mentioned
  in the same breath, even though they live in very different layers of the stack.
  
  \end{markdown}
  \end{document}

  

  The default definitions for LaTeX also provide support for explicit markup for acronyms, as well as an integration with the glossaries package:

  \documentclass{article}
  \usepackage{microtype, hyperref}
  \usepackage[acronym]{glossaries}
  \makeglossaries
  \newacronym{html}{HTML}{hypertext markup language}
  \newacronym{yaml}{YAML}{yet another markup language}
  \usepackage[bracketed_spans]{markdown}
  \begin{document}
  \begin{markdown}
  
  HTML and YAML are two staples of modern tooling that often get mentioned
  in the same breath, even though they live in very different layers of the stack.
  
  You may also use explicit markup: [HTML]{.acronym}. This works even if the
  acronym hasn't been registered with the glossaries package: [JSON]{.acronym}.
  
  \end{markdown}
  \printacronyms
  \end{document}

  Compile the above example document ⟨filename⟩.tex with the following commands:

  lualatex ⟨filename⟩.tex
  makeglossaries ⟨filename⟩
  lualatex ⟨filename⟩.tex
  

  This produces the following result:

  

  If you are not using the default definitions for LaTeX (for example, when loading the package with the plain or noDefaults options), you can import the glossaries acronyms manually as follows:

  \markdownSetup {
     import = witiko/glossaries@v1,
    snippet = witiko/glossaries/import-acronyms,
  }

• Allow absolute snippet names in \markdownSetupSnippet { ... } and \markdownSetup { snippet = ... }. (#623)

  Absolute snippet names are prefixed with a slash (/). The leading slash is stripped, and the remaining name is used as-is. In contrast, relative snippet names are prefixed with the name of the currently processed theme, if any.

  For consistency, a leading slash may also be used in \markdownSetup { theme = ... } and { import = ... }. Theme names, however, are currently always absolute, so the slash is only a syntactic normalization and has no semantic effect.

  For example, the following code also imports the glossaries acronyms:

  \markdownSetup {
    import  = /witiko/glossaries@v1,
    snippet = /witiko/glossaries/import-acronyms,
  }

  The slash before witiko/glossaries/import-acronyms ensures that the correct snippet is loaded even when used from within another theme. Without the leading slash, the snippet name would instead be resolved as ⟨current theme name⟩/witiko/glossaries/import-acronyms.

  By contrast, the slash before witiko/glossaries@v1 is optional and provided only for consistency. Therefore, the following code would have the same effect:

  \markdownSetup {
    import  =  witiko/glossaries@v1,
    snippet = /witiko/glossaries/import-acronyms,
  }

3.13.0

Fixes:

• Support Unicode in attributes. (reported by @andreiborisov in #605, fixed by @Witiko in #608)

Development:

• Add \mmdcCommand macro for configuring the command used to render Mermaid diagrams. (suggested by @TheManchineel in #613, added by @Witiko in #614)

  For example, you can use different icon packs as follows:

  \documentclass{article}
  \def\mmdcCommand{mmdc --iconPacks '@iconify-json/logos'}
  \usepackage[import=witiko/diagrams@v2]{markdown}
  \begin{document}
  \begin{markdown}
  
  ``` mermaid
  architecture-beta
      group api(logos:aws-lambda)[API]
  
      service db(logos:aws-aurora)[Database] in api
      service disk1(logos:aws-glacier)[Storage] in api
      service disk2(logos:aws-s3)[Storage] in api
      service server(logos:aws-ec2)[Server] in api
  
      db:L -- R:server
      disk1:T -- B:server
      disk2:T -- B:db
  ```
  
  \end{markdown}
  \end{document}

  

• Add a new Lua option htmlOverLinks that causes HTML tags to be recognized as tags rather than hyperlinks when the Lua option relativeReferences has been enabled. (discussed with @u-fischer in #597, added by @Witiko and @lostenderman in #607)

  The option htmlOverLinks is an experimental option: Whenever the option experimental is enabled and htmlOverLinks is unspecified, it will also be enabled. Like other experimental options, htmlOverLinks will be enabled by default in the next major release of the Markdown package and soft-deprecated.

• Add a new Lua option blankBeforeHtmlBlock that causes the parser to require a blank line between a paragraph and the following CommonMark HTML block. (discussed with @u-fischer in #598, added by @Witiko and @lostenderman in #608)

  Enabling this option breaks CommonMark compliance but makes it easier to write raw HTML such as inline HTML comments without producing HTML blocks by accident.

• In theme witiko/diagrams, add parameter format for GraphViz diagrams. (reported by @Witiko in #611, fixed by @Witiko in #612)

  Here is an example LaTeX document using the new parameter:

  \documentclass{article}
  \usepackage[import=witiko/diagrams@v2, relativeReferences]{markdown}
  \begin{document}
  \begin{markdown}
  ``` dot {caption="An example directed graph" format=svg width=12cm #dot}
  digraph tree {
    margin = 0;
    rankdir = "LR";
  
    latex -> pmml;
    latex -> cmml;
    pmml -> slt;
    cmml -> opt;
    cmml -> prefix;
    cmml -> infix;
    pmml -> mterms [style=dashed];
    cmml -> mterms;
  
    latex [label = "LaTeX"];
    pmml [label = "Presentation MathML"];
    cmml [label = "Content MathML"];
    slt [label = "Symbol Layout Tree"];
    opt [label = "Operator Tree"];
    prefix [label = "Prefix"];
    infix [label = "Infix"];
    mterms [label = "M-Terms"];
  }
  ```
  
  See the diagram in Figure <#dot>.
  \end{markdown}
  \end{document}

  This can be used to circumvent missing support for PDF output in some distributions of GraphViz, notably Debian Forky, which the texlive/texlive Docker images are currently based on.

Defaults:

• In LaTeX, fix header attribute {-} for chapters and parts. (reported by @MacLotsen in #602, fixed by @Witiko in e588d20)
• In LaTeX, reset category codes before using \maketitle. (reported by @MacLotsen in #603, fixed by @Witiko in 00068c8)

Continuous integration:

• Bump actions/checkout from 5 to 6. (added by @dependabot in #604)

3.12.1

Tests:

• Persistently store the raw batch output for failed batches. (#592, #600, 7f489b7..f6f32af)

• Only execute the snippet witiko/markdown/test/snippet once every batch to improve speed and reduce memory footprint. (#601, a420c4c)

  This speeds up the regression tests on the free GitHub-hosted runners up to 3× from ca 133 minutes to just ca 47 minutes.

Continuous integration:

• Upload failed batches and batch bisection logs as artifacts. (#592, #600, 7f489b7..1550016)

3.12.0

Development:

• Upgrade from Unicode 16 to Unicode 17. (#585)

• Produce warning renderers for undefined and multiply defined references to notes, full links, and collapsed links. (requested by @Witiko in #518, added by @Witiko and @lostenderman in #587)

  Here is how you might make the warnings part of the output in LaTeX by redefining the warning renderer:

  \documentclass{article}
  \usepackage[notes]{markdown}
  \usepackage[english]{babel}
  \usepackage[autostyle,english=american]{csquotes}
  \MakeOuterQuote{"}
  \usepackage{todonotes}
  \markdownSetup
    {
      renderers = {
        warning = \todo{#1},
      },
    }
  \begin{document}
  \begin{markdown}
  
  Here is an undefined note.[^note]
  
   [foo]: https://example.bar/
   [foo]: https://example.baz/
  
  \end{markdown}
  \end{document}

  

  By default, warnings are logged using the \msg_warning: class of expl3 functions.

Docker:

• Start building Docker images witiko/markdown:latest-context. (#402, #586)

3.11.6

Tests:

• Improve the speed of our tests more by than 3×. (added by @zauguin, @muzimuzhi, @gucci-on-fleek, and @josephwright in latex3/latex3#1791, discussed in #557 and #584)

• Enable LuaMetaTeX in ConTeXt tests. (added by @Witiko in #557 with major contributions from @josephwright and @gucci-on-fleek in #557, latex3/latex3#1791, latex3/latex3#1797, and elsewhere)

Documentation:

• Add installation instructions for ConTeXt Standalone to the user manual. (reported by @andreiborisov in #402, added by @Witiko and @gucci-on-fleek in #557)

Continuous integration:

• Do not use self-hosted runners in pull requests either. (07af69a)

• Remove TeX Live 2023 and 2024 from the continuous integration. (5cb5980)

  This is because we can't typeset the ConTeXt LMTX example document with earlier TeX Live versions. TeX Live 2023 and 2024 are still supported.

Examples:

• Add example file examples/context-lmtx.tex for ConTeXt LMTX. (added by @Witiko in #557 with major contributions from @josephwright and @gucci-on-fleek in #557 and elsewhere)

Housekeeping:

• Remove needless ignored issues. (fixed by @Witiko in #583)

3.11.5

Fixes:

• Correctly regenerate ConTeXT databases in Dockerfile. (reported by @Witiko in gucci-on-fleek/context-packaging#2 and #575, fixed by @Witiko and @gucci-on-fleek in gucci-on-fleek/context-packaging@0459634, gucci-on-fleek/context-packaging@f8ee60e, d4c0054, 6fbd4dc, ccf580b, 850bef8, and 53a3335)

• Only quote \jobname-based token lists when the engine would. (reported by @andreiborisov in #557, fixed by @Witiko in #582)

  This change improves support for LuaMetaTeX.

Dependencies:

• Remove dependency on library lua-uni-algos. (added by @Witiko in #569)

Defaults:

• In LaTeX, load enumitem instead of paralist when the user has expressed an intent to use new tag-friendly code by writing \DocumentMetadata. (reported by @Witiko in #578, fixed by @Witiko and @u-fischer in #579)

Continuous integration:

• Rename GitHub Action teatimeguest/setup-texlive-action@v3 to TeX-Live/.... (reported by @pablogonz in #576, fixed by @Witiko in 28ba10b)
• Use current pkgcheck. (reported by @manfredlotz via email and by @Witiko in #580, fixed in #581)

3.11.4

Documentation:

• Document the current limitations of the MikTeX distribution and TeX engines other than LuaTeX. (reported by @obskyr in #566 and by @viocha in #573, escalated upstream by @Witiko in miktex/miktex#1630, documented by @Witiko in #574 and witiko/lt3luabridge#32)

  These are the current limitations:

  1. The filenames of your .tex files may not contain spaces, see also #573.
  2. If -output-directory is provided, it may not contain spaces and it won't be
     automatically detected by MikTeX, see also miktex/miktex#1630.

Housekeeping:

• Mark uses of the deprecated conditional functions \regex_match:* for removal after we have dropped support for TeX Live 2024 and earlier. (8cd8bb5)

Deprecation:

• Undeprecate \markdownOptionOutputDir. (#566, miktex/miktex#1630, #574)

  Due to the lack of support for the automatic detection of -output-directory in MikTeX with TeX engines other than LuaTeX (see miktex/miktex#1630), there are still genuine uses of this option. Therefore, it doesn't make sense to deprecate it.

3.11.3

Fixes:

• Support .tex files with spaces in the filename. (reported by @obskyr in #568, fixed by @Witiko in #571)
• Use status.output_directory to determine option outputDir on MikTeX. (reported by @obskyr in #566, fixed by @gucci-on-fleek, @cfr42, and @Witiko on TeX StackExchange and in #571)

Continuous integration:

• Switch to the GitHub Action softprops/action-gh-release for automatic pre-releases. (contributed by @muzimuzhi in expltools#82, 58698ad)

3.11.2

Fixes:

• Fix style issues identified by explcheck's semantic analysis. (expltools#75, #562, #564)
• Make \markdownInput handle file names with spaces correctly. (reported by @u-fischer in #563, fixed by @Witiko in #565)

3.11.1

Development:

• In theme witiko/diagrams, add parameter format for PlantUML diagrams. (reported by @mrkissinger in #555, fixed by @Witiko in 7d58f3d and 64c78f1)

  Here is an example LaTeX document using the new parameter:

  \documentclass{article}
  \usepackage[import=witiko/diagrams@v2, relativeReferences]{markdown}
  \begin{document}
  \begin{markdown}
  ``` plantuml {caption="An example UML sequence diagram" format=eps width=7cm #plantuml}
  @startmindmap
  + SIR
  ++ 指標引擎
  @endmindmap
  ```
  
  See the diagram in Figure <#plantuml>.
  \end{markdown}
  \end{document}

Documentation:

• Add preprint and artwork for an upcoming TUGboat article titled "Piping YAML files into LaTeX3 key–values". (c684ce2, 2214706, 52ccb7a, 85e9680)

Docker:

• Start building Docker images witiko/markdown:TL2024-historic. (bcae00a)
• Switch Docker images witiko/markdown:latest from TeX Live 2024 to 2025. (bcae00a)