Home Original page

👌 Improve generation of meta nodes by AA-Turner · Pull Request #1080 · executablebooks/MyST-Parser

This PR updates how HTML meta nodes are generated in MyST-Parser to ensure compatibility with Sphinx v9.

Changes Made

myst_parser/mdit_to_docutils/base.py

  1. Removed import: from docutils.transforms.components import Filter
  2. Changed return type of html_meta_to_nodes():
    • Before: list[nodes.pending | nodes.system_message]
    • After: list[nodes.meta | nodes.system_message]
  3. Simplified node generation: Instead of wrapping meta nodes in nodes.pending with a Filter transform, meta nodes are now directly returned

Test Fixtures Updated

  • tests/test_renderers/fixtures/docutil_syntax_elements.md
  • tests/test_renderers/fixtures/sphinx_syntax_elements.md

Expected output changed from <pending> nodes with internal transform details to direct <meta> nodes.

Assessment: ✅ Correct and Necessary

Why This Change is Needed

  1. Modern docutils/Sphinx behavior: In docutils 0.18+ (2021), nodes.meta became a standard node type that writers handle directly
  2. Sphinx v9 compatibility: The old approach using Filter transform with pending nodes is deprecated/removed in newer Sphinx versions
  3. Alignment with standards: This matches how Sphinx's own meta directive works in modern versions

Why It Works

  • Writers that support HTML output process nodes.meta directly and render them as <meta> tags in the HTML <head> section
  • The change removes an unnecessary layer of indirection (pending nodes)
  • Uses the standard docutils nodes.meta approach

Test Coverage

Test Type File Coverage
Docutils renderer tests/test_renderers/fixtures/docutil_syntax_elements.md "Front Matter HTML Meta" case
Sphinx renderer tests/test_renderers/fixtures/sphinx_syntax_elements.md Same test case
CLI/config tests/test_renderers/fixtures/myst-config.txt --myst-html-meta option
Sphinx HTML build tests/test_sphinx/test_sphinx_builds.py::test_extended_syntaxes Meta nodes in HTML builds
Sphinx text build tests/test_sphinx/test_sphinx_builds.py::test_extended_syntaxes_text Meta nodes with non-HTML builder

Non-HTML Builder Coverage

The added test_extended_syntaxes_text test uses the text builder with the extended_syntaxes source directory, which has myst_html_meta configured.
This ensures that meta nodes don't cause issues for non-HTML builders—they simply don't render meta tags (as expected, since <meta> is an HTML-specific concept).