Routing YAML metadata to expl3 key–values [MEP]

[Witiko]

Rationale

The option jekyllData enables YAML streams to generate YAML metadata renderers, which can be redefined for event-driven processing of complex YAML documents. For simpler YAML documents, the \markdownSetup key jekyllDataRenderers offers an alternative with less control but simpler syntax; see sections 2.2.6.1 and 3.2.3.2 of the technical documentation.

In cases of medium-complexity YAML documents, jekyllDataRenderers may not provide enough processing control, often necessitating manual redefinitions of YAML metadata renderers. A recent article, Markdown Themes in Practice from TUGboat 45:2, illustrated that redefining YAML metadata renderers to route processing to expl3 key–values can be beneficial, an idea aligned with @TeXhackse's suggestion at #77 (comment), which we ultimately didn't implement in #77. Adding standardized support for routing jekyll data to key–values could simplify the handling of medium-complexity YAML documents.

While key–values are typeless, YAML values have types, which are accessible through YAML metadata renderers. Furthermore, whereas key–values only accept a single value for a key, the Markdown package provides two representations of string values:

1. The typographic string, where markdown and special TeX characters have been replaced with TeX macros.
2. The programmatic string, which retains the raw value.

Our routing should also preserve type information and provide access to both representations of strings.

Proposal

Add a new \markdownSetup key jekyllDataKeyValue that specifies the key–value ⟨module⟩ to which all jekyll data is routed.

For every YAML key path.to.⟨key⟩ with a value of type ⟨non-string type⟩, set the key ⟨non-string type⟩ of the key–value ⟨module⟩/path/to/⟨key⟩ if it is known and the key ⟨key⟩ of the key–value ⟨module⟩/path/to otherwise. ⟨Non-string type⟩ is one of boolean, number, and empty. For the ⟨non-string type⟩ of empty, no value is passed to the key–value. Therefore, a default value should always be defined for nullable keys using the key property .default:n.

For every YAML key path.to.⟨key⟩ with a value of type string, set the keys typographicString and programmaticString of the key–value ⟨module⟩/path/to/⟨key⟩ if they are known with the typographic and programmatic strings of the value, respectively. Furthermore, set the key ⟨key⟩ of the key–value ⟨module⟩/path/to with the typographic string of the value unless the key typographicString is known. If the key programmaticString is known, only set the key ⟨key⟩ if it is known. In contrast, if neither typographicString nor programmaticString are known, set ⟨key⟩ normally, i.e. regardless of whether it is known or unknown.

Examples

Processing YAML metadata in LaTeX:

\documentclass{article}
\usepackage{markdown}
\ExplSyntaxOn
\str_new:N \g_markdown_example_title_str
\seq_new:N \g_markdown_example_author_seq
\keys_define:nn
  { markdown / some / example / module }
  {  % Define a key-value that processes YAML metadata.
    title / programmaticString .str_gset:N = \g_markdown_example_title_str,  % Store the raw title in a variable.
    title .code:n = { \title { #1 } },  % Set the title. This is the same as writing `title / typographicString`.
    author / unknown .code = {  % Store a variable-length list of authors in an array variable.
      \seq_put_right:Nn
        \g_markdown_example_author_seq
        { #1 }
    },
  }
\markdownSetupSnippet
  { metadata }
  {  % Define a snippet that routes YAML metadata to the above key key–value.
    jekyllData, expectJekyllData, ensureJekyllData,
    jekyllDataKeyValue = markdown / some / example / module,
    renderers = {
      jekyllDataEnd = {  % At the end of the YAML metadata, ...
        \clist_set_from_seq:NN  % ... set the list of authors and
          \l_tmpa_clist
          \g_markdown_example_author_seq
        \exp_args:Nx
          \author
          { \clist_use:Nn \l_tmpa_clist { ,~ } }
        \AtBeginDocument { \maketitle }  % ... typeset the title page.
      },
    }
  }
\ExplSyntaxOff
% Process the YAML metadata.
\begin{markdown}[snippet=metadata]
title: Some title that includes _markup_
authors: [Jane Doe, John Moe]
\end{markdown}
\begin{document}
The raw title of the document is:
\ExplSyntaxOn
\str_use:N \g_markdown_example_title_str
\ExplSyntaxOff
\end{document}

[Witiko]

After this MEP has been implemented, jekyllDataRenderers in markdown.dtx and in the example documents should be replaced with jekyllDataKeyValue.