Skip to content

👌 Improve generation of meta nodes #1080

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
chrisjsewell merged 3 commits into from
Jan 14, 2026
Merged

👌 Improve generation of meta nodes #1080

chrisjsewell merged 3 commits into from
Jan 14, 2026
+103 −74

Conversation

@AA-Turner
Copy link
Contributor

@AA-Turner AA-Turner commented Dec 27, 2025 •
edited by chrisjsewell
Loading

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).

@AA-Turner AA-Turner mentioned this pull request Dec 27, 2025
Merged
@chrisjsewell chrisjsewell changed the title Improve generation of meta nodes 👌 Improve generation of meta nodes Jan 14, 2026
@chrisjsewell
Copy link
Member

chrisjsewell commented Jan 14, 2026 •
edited
Loading

Thanks @AA-Turner, I added s PR description, with an assessment I had AI run, and also added an extra test for a non-html build, but yeh looks all good

@chrisjsewell chrisjsewell merged commit fcf78ca into executablebooks:master Jan 14, 2026
17 checks passed
@AA-Turner AA-Turner deleted the better-meta branch January 14, 2026 19:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@chrisjsewell chrisjsewell chrisjsewell approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@AA-Turner @chrisjsewell