The processing of YAML documents can often be the primary function of the Markdown package, see my TUG 2024 preprint Markdown themes in practice that discusses just this aspect of the Markdown package. Despite this, our support for YAML documents has a number of weak points:
Invalid YAML documents are processed as markdown text.
The commands \markdownSetup, \setupmarkdown, and \markdownInput and the environments \markdownBegin ... \markdownEnd, \begin{markdown} ... \end{markdown}, and \startmarkdown ... \stopmarkdown are used to process YAML files, which is a confusion name choice.
For these workflows, it would make sense to
Provide an option that would cause us to produce an error when an invalid YAML document has been provided.
Provide better-named aliases for the package files, commands, and environments for the processing of YAML files.
Tasks
[x] Add option ensureJekyllData that will cause an error if a document is not (only) a YAML document.
[x] Add command \yamlSetup and \setupyaml that will alias the commands \markdownSetup and \setupmarkdown.
[x] Add command \yamlInput[...]{...} that will be equivalent to \markdownInput[jekyllData, expectJekyllData, ensureJekyllData, ...]{...}.
[x] Add enviroments \yamlBegin and \yamlEnd, \begin{yaml}[...] ... \end{yaml}, and \startyaml[...] ... \stopyaml that will be an equivalent of \begingroup \yamlSetup{jekyllData, expectJekyllData, ensureJekyllData} \markdownBegin ... \markdownEnd, \begin{markdown}[jekyllData, expectJekyllData, ensureJekyllData, ...] ... \end{markdown}, and \startmarkdown[jekyll_data, expect_jekyll_data, ensure_jekyll_data, ...] ... \stopmarkdown.
[x] Use this new feature in markdown.dtx and in the example documents.
The processing of YAML documents can often be the primary function of the Markdown package, see my TUG 2024 preprint Markdown themes in practice that discusses just this aspect of the Markdown package. Despite this, our support for YAML documents has a number of weak points:
\markdownSetup,\setupmarkdown, and\markdownInputand the environments\markdownBegin ... \markdownEnd,\begin{markdown} ... \end{markdown}, and\startmarkdown ... \stopmarkdownare used to process YAML files, which is a confusion name choice.For these workflows, it would make sense to
Tasks
ensureJekyllDatathat will cause an error if a document is not (only) a YAML document.\yamlSetupand\setupyamlthat will alias the commands\markdownSetupand\setupmarkdown.\yamlInput[...]{...}that will be equivalent to\markdownInput[jekyllData, expectJekyllData, ensureJekyllData, ...]{...}.\yamlBeginand\yamlEnd,\begin{yaml}[...] ... \end{yaml}, and\startyaml[...] ... \stopyamlthat will be an equivalent of\begingroup \yamlSetup{jekyllData, expectJekyllData, ensureJekyllData} \markdownBegin ... \markdownEnd,\begin{markdown}[jekyllData, expectJekyllData, ensureJekyllData, ...] ... \end{markdown}, and\startmarkdown[jekyll_data, expect_jekyll_data, ensure_jekyll_data, ...] ... \stopmarkdown.markdown.dtxand in the example documents.CHANGES.md.