3.9.1

Development

• Add version v1 of the new built-in theme witiko/diagrams. (#514, #531, #538)

  This version is an alias for an earlier theme named witiko/dot. Future versions of the theme may have backwards-incompatible syntax and behavior, see the discussion in #514 and #531. Therefore, you are encouraged to always specify the version v1 to keep your documents from suddenly breaking. The Markdown package will warn you if you don't.

Fixes

• Make option eagerCache safe to use with plain LuaTeX. (#530, Witiko/lt3luabridge#29)
• In LaTeX, fix bad interaction between heading identifiers and the class name {.unnumbered} (also written as {-}). (#511, 3d2e81d, reported by @jurf)

Documentation

• Add artwork by https://fiverr.com/quickcartoon to directory artwork/. (#533)

  You are welcome to use these artworks in your promotional materials, provided you comply with the license terms specified for each piece. Typically, proper attribution to the artist is required.

Deprecation

• Soft-deprecate the name of the built-in theme witiko/dot in favor of the new theme witiko/diagrams@v1. (#514, #531, #538)

Distribution

• Make markdown-cli executable and symlink it to system directories. (#534, #537, tex-live@tug.org)
• Install the current package lt3luabridge in Dockerfile. (#530)

Tests

• Reenable eagerCache in tests for plain LuaTeX. (#530, Witiko/lt3luabridge#29)
• Use explcheck to check expl3 code in the continuous integration. (#535, #536, b4e3bfc)

The latest version

Commits

• 72fd37c: Update CHANGES.md (Vít Starý Novotný)

3.9.0

Development:

• Convert built-in LaTeX themes witiko/dot and witiko/graphicx/http into plain TeX themes. (#514, #522, #529)

  This allows these themes to be used in formats such as plain TeX and ConTeXt as well.

Refactoring:

• Remove dependencies on ifthen, gobble, and catchfile. (#514, #522, #529)

• Store small built-in LaTeX themes witiko/dot, witiko/graphicx/http, and witiko/tilde in expl3 props in files markdown.tex and markdown.sty. (#514, #522, #529)

  This simplifies the distribution and installation of these themes, which were previously located in individual .tex and .sty files.

  The built-in plain TeX, LaTeX, and ConTeXt themes witiko/markdown/defaults are still distributed in individual files. This is because inlining these themes in files markdown.tex, markdown.sty, and t-markdown.tex would make it more difficult for users to copy and modify these themes without delaying updates to the Markdown package itself. Furthermore, these themes are large and storing/executing them from an expl3 prop would make it more difficult to determine the line numbers when errors occur.

Fixes:

• Protect renderers and renderer prototypes. (#465, #506)

  After this change, default renderers and renderer prototypes as well as renderers and renderers and prototypes defined using the keys renderers and rendererPrototypes of the command \markdownSetup are protected, which is usually preferable for typesetting.

  New keys unprotectedRenderers and unprotectedRendererPrototypes were also added to the command \markdownSetup. These keys define unprotected renderers and renderer prototypes, respectively, which are easier to expand and may be preferable for programming.

Defaults:

• Define default LaTeX renderer prototypes for table identifiers. (#525, suggested by @machitgarha, #528)

  This establishes a reliable method for authors to reference tables within Markdown:

  \documentclass{article}
  \usepackage[
    pipe_tables,
    table_attributes,
    table_captions,
    relative_references,
  ]{markdown}
  \begin{document}
  \begin{markdown}
  
  | Right | *Left* |   Default   | Center |
  |------:|:-------|-------------|:------:|
  |   12  |   12   |      12     |    12  |
  |  123  |   123  |   **123**   |   123  |
  |    1  |     1  |       1     |     1  |
  
    : Demonstration of *pipe table* syntax with the caption spreading over
      multiple lines. {#identifier .class-name key=value}
  
  Demonstration of a *relative reference*: See Table <#identifier>.
  
  \end{markdown}
  \end{document}

• Define default LaTeX renderer prototypes for bracketed spans. (discussed with @MacLotsen at TUG 2024 and with @TeXhackse at matrix.org, #528)

  This establishes a reliable method for authors to reference the last LaTeX counter that has been incremented in e.g. ordered lists.

  \documentclass{article}
  \usepackage[
    bracketed_spans,
    relative_references,
    start_number = false,
  ]{markdown}
  \begin{document}
  \begin{markdown}
  
  Demonstration of *bracketed spans* syntax:
  
   1. First item
   2. [Second item]{#second-item}
   3. Third item
  
  Demonstration of a *relative reference*: See item <#second-item>.
  
  \end{markdown}
  \end{document}

• Use package LuaXML in default LaTeX renderer prototypes for content blocks, raw blocks, and inline raw spans. (#469, #532, co-authored by @michal-h21)

  This allows authors to render HTML fragments in their LaTeX documents:

  \documentclass{article}
  \usepackage[content_blocks, raw_attribute]{markdown}
  \begin{filecontents}[overwrite, nosearch, noheader]{example_input.html}
  <b>foo</b> <i>bar</i>
  \end{filecontents}
  \begin{document}
  \begin{markdown}
  
  Raw text span: `<b>foo</b> <i>bar</i>`{=html}
  
  Raw code block:
  
  ``` {=html}
  <b>foo</b> <i>bar</i>
  ```
  
  Content block:
  
   /example_input.html
  
  \end{markdown}
  \end{document}

Deprecation:

• Remove support for TeX Live 2022. (da85e01, 8f2d25c)

  This change also removes the Lua module markdown-tinyyaml, which has been scheduled for removal ever since the Lua module tinyyaml was uploaded to CTAN in TeX Live 2023.

3.8.1

Fixes:

• Fix backslashes at the ends of hybrid documents. (#502, #503, contributed by @lostenderman)
• Fix hard line breaks in fancy list items. (#508, #509, contributed by @lostenderman)

3.8.0

Development:

• Add support for versioned themes and add new Lua option experimental. (#466, #512, #514, matrix.org reviewed by @TeXhackse, #521)

  The option experimental enables experimental features that are planned to be the new default in the next major release of the Markdown package.

  At the moment, this just means that the version experimental of the theme witiko/markdown/defaults will be loaded and warnings for hard-deprecated features will become errors. However, the effects may extend to other areas in the future as well.

• Add first-class support for YAML documents. (#452, #473, #524)
  • Add plain TeX macros \yamlSetup, \yamlInput, \yamlBegin, and \yamlEnd.
  • Add LaTeX environment yaml and redefine command \yamlInput for LaTeX.
  • Add ConTeXt commands \setupyaml, \inputyaml, \startyaml, and \stopyaml.

Documentation:

• Document LaTeX hooks. (#464, #507)

Defaults:

• Improve the compatibility of the default LaTeX packages with PDF tagging: (#466, #512, #514, #521, reported and consulted by @u-fischer)

  • In TeX engines other than LuaTeX, use the package soul instead of the package soulutf8 in TeX Live ≥ 2023.

  • In LuaLaTeX, use the package lua-ul for strike-through/mark renderer prototypes instead of the package soul.

  • Use the package enumitem for tight and fancy lists instead of the package paralist.

    This is a breaking change that is marked as experimental. To enable it, either use the package option experimental or specify any test phase in the document metadata:

    1. \usepackage[experimental]{markdown}
    2. \DocumentMetadata{testphase=phase-III}

• Define LaTeX renderers for image identifiers. (#520, suggested by @jurf, 6f3dcd0, 478530f, matrix.org)

  This establishes a reliable method for authors to reference figures within Markdown:

  \documentclass{article}
  \usepackage[link_attributes, relative_references]{markdown}
  \begin{document}
  \begin{markdown}
  
  ![example image](example-image "An example image"){#example-image-id}
  
  See Figure <#example-image-id>.
  
  \end{markdown}
  \end{document}

• Set correct category codes for version 3 of the package minted. (3998093)

Continuous Integration:

• Only use self-hosted runners for the quick CI in pull requests. For full CI outside pull requests, use GitHub-hosted runners. (c269742, matrix.org)

3.7.1

Development:

• Remove dependency on UnicodeData.txt. (#400, #458 #486, #492, #499)

  This change improves the speed of parsing markdown input by up to 25% for a cold conversion run and makes life easier for users of TeX distributions other than TeX Live, such as MikTeX and ConTeXt Standalone, where UnicodeData.txt may not be as easily available. This change also adds a new file markdown-unicode-data.lua, which must be properly installed with the rest of the Markdown package.

• Add renderers warning and error that represent warnings and errors produced by the markdown parser. (#452, #473, #496)

Fixes:

• Properly load LaTeX themes when theme or import is used in \usepackage[...]{markdown}. (#471, #498)
• Prevent endless loop when setting deprecated jekyllDataString renderer (prototype). (#500)
• Correctly handle backslashes in \markdownOptionOutputDir on Windows. (#492, #500, reported by @l0th3r)
• Fix hard line breaks in blockquotes. (#494, #495, reported by @l0th3r, #496, contributed by @lostenderman)

Deprecation:

• Soft-deprecate the hybrid option. (#470, #504, 546faa8)

  Instead of using the hybrid option, consider one of the following better alternatives for mixing TeX and markdown:

  • With the contentBlocks option, authors can move large blocks of TeX code to separate files and include them in their markdown documents as external resources.
  • With the rawAttribute option, authors can denote raw text spans and code blocks that will be interpreted as TeX code.
  • With options texMathDollars, texMathSingleBackslash, and texMathDoubleBackslash, authors can freely type TeX math between dollar signs or backslash-escaped brackets.

  Soft-deprecated features will never be removed but using them prints a warning and is discouraged.

3.7.0

Development:

• Add renderer jekyllDataProgrammaticString for processing YAML string scalars that do not contain markdown markup and are not intended for typesetting. (istqborg/istqb_product_base#46, #440, #451, sponsored by @istqborg)
• Add option ensureJekyllData for processing standalone YAML files. (#452, #473, sponsored by @istqborg)
• Support user-defined LaTeX environments with LaTeX markup. (#20, #477, suggested by @cdupont)

Fixes:

• Produce more meaningful error message when KPathSea fails to locate a file. (#458, #472, 33e6eef, reported by @Yggdrasil128)
• Fix soft line breaks in citation prenotes and postnotes. (#483, #484, contributed by @lostenderman)

Speed improvements:

• Precompile snippets to improve the speed of setting them. (#467, #479, inspired by the TUG 2024 talk by @josephwright)
• Use an optimized parser to determine Unicode punctuation. (#458, #474, #482, 4c1a7de, co-authored by @Yggdrasil128, sponsored by @istqborg)
  This improves the speed of parsing markdown input by up to 500%.
• Enable option eagerCache by default. (#468, #490, sponsored by @istqborg)
  This improves the speed by up to 25% for large documents with many markdown fragments that require multiple compilation runs.
• Prevent loading the full Markdown package when converting cached markdown fragments. (#487, #491, 40f0803, 6609d43, sponsored by @istqborg)
  This significantly improves the speed for large documents with many markdown fragments that require multiple compilation runs in pdfTeX.

Deprecation:

• Deprecate jekyllDataString renderer and renderer prototype. (istqborg/istqb_product_base#46, #440, #451, sponsored by @istqborg)
  Users should use jekyllDataTypographicString instead.

Continuous Integration:

• Ensure that all code lines are shorter than 72 characters. (#478, e7160d6, 3ac95ef)

Experiments:

• Measure the speed of the Markdown package across recent versions. (249552e, 55ede82, efeaecb, #474, 7b2b243, fcf0064)

3.6.2

Fixes:

• Fix the interplay between inline notes and square brackets. (#453, #456, reported by @nopria, contributed by @lostenderman)
• Fix the interplay between lists and citations. (Witiko/expltools#3, #460, #461, contributed by @lostenderman)
• Do not override the outputDir option if if has been defined before loading the package and pass it to lt3luabridge library. (#457, #459)

Documentation:

• Fix various typos. (#454, contributed by @mbertucci47)
• Add file DEPENDS.txt. (#462, #463, 93bb7e1)

Continuous Integration:

• Only test latest TeX Live in pull requests. (81927ca)

Unit Tests:

• Test the outputDir plain TeX option. (#457, #459)

Libraries:

• Update tinyyaml to v0.4.4-1-g197632c. (1e83ac9)

3.6.1

Fixes:

• Fix the interplay between (strong) emphasis and (inline) notes. (#447, #450, lostenderman#159, reported by @nopria, contributed by @lostenderman)
• Produce soft line break renderers in inline notes. (#450, lostenderman#159, contributed by @lostenderman)

Documentation:

• Improve the documentation of portable installation. (#444, 9afac05, contributed by @l0th3r)
• Document that the Markdown package can be installed from GitHub releases. (#449, #450, reported by @nopria)

Continuous Integration:

• Remove warnings from Pandoc and GitHub Actions. (2b3f346..71f174b)

Defaults:

• Fix default definitions for fancy tight ordered lists. (#446, f978e81, reported by @l0th3r)

3.6.0

Development:

• Add Lua options unicodeNormalization and unicodeNormalizationForm for normalizing markdown text using Unicode normalization. (#434, #442, sponsored by @istqborg)

Fixes:

• Make \markdownInput search in \l_file_search_path_seq. (#443, reported by @robertjlee)

Documentation:

• Add a link to a work-in-progress article for TUGboat 45:2 to README.md. (7a1a7ea)

Fixes:

• Correctly sort YAML map keys with mixed types. (#433, #441)