Versioned themes [MEP]

[Witiko]

Rationale

Since #512, the built-in Markdown theme witiko/markdown/defaults has been using the enumitem package instead of paralist for tight and fancy lists. This change is significant and while the Markdown package makes no guarantees about the default renderer prototype definitions, it would be beneficial to provide a controlled way for users to delay the update of these definitions without delaying the entire package update.

The witiko/dot theme currently renders fenced code blocks with the infostring dot Caption text as diagrams using the dot command from GraphViz. Extending this theme to support other diagram tools like Mermaid (see also #448), PlantUML, and TikZ would be useful. Additionally, it would be beneficial to support the newer syntax introduced by the fencedCodeAttributes and rawAttribute options, allowing users to specify captions consistently as {=dot caption="Caption text"} without affecting existing users of the witiko/dot theme.

(Note: The LaTeX themes witiko/markdown/defaults, witiko/dot, and witiko/graphicx/http would also benefit from a more comprehensive update to expl3 to eliminate dependencies on ifthen, gobble, catchfile, etoolbox, and LaTeX in general.)

Proposal

This Markdown Enhancement Proposal (MEP) proposes adding support for versioned themes. Users could specify a version when loading a theme, defaulting to latest if omitted. Attempting to load multiple versions of the same theme would result in an error.

Versioning allows users to revert to previous witiko/markdown/defaults behavior and experiment with updates labeled experimental that could later become latest based on user feedback before the next major release.

Versioning would also facilitate updating the witiko/dot theme to support the new fencedCodeAttributes and rawAttribute syntax and additional diagram types. A new built-in theme, perhaps named witiko/diagrams, would carry forward the current behavior as v1. Future versions (v2, latest) could then incorporate new syntax and diagram types.

Syntax

To specify a theme version, append @⟨version⟩ to the theme name. This version string is accessible within the theme via \markdownThemeVersion.

Examples

To load the experimental version of witiko/markdown/defaults in LaTeX:

\usepackage[no_defaults, theme = witiko/markdown/defaults@experimental]{markdown}  % or:
\usepackage[experimental]{markdown}

For further context, see also #31, which proposes adding a table of experimental options. Both the experimental version of witiko/markdown/defaults and the experimental options could be activated in LaTeX simply by writing \usepackage[experimental]{markdown}. However, this proposal is outside the scope of the current MEP.

To load the theme witiko/dot:

\markdownSetup{theme = witiko/dot}  % or:
\markdownSetup{theme = witiko/diagrams@v1}

To load witiko/diagrams with new syntax and additional diagram support:

\markdownSetup{theme = witiko/diagrams}  % or:
\markdownSetup{theme = witiko/diagrams@v2}  % or:
\markdownSetup{theme = witiko/diagrams@latest}

Attempting to load multiple versions of the same theme would result in an error:

\markdownSetup{
  theme = witiko/diagrams@v2,
  theme = witiko/diagrams,  % Error: Tries to load `witiko/diagrams@latest` but `@v2` has already been loaded.
  theme = witiko/dot,  % Error: Tries to load `witiko/diagrams@v1` but `@v2` has already been loaded.
}