Skip to content

🐛 FIX: Respect the parser option of the {include} directive - #1236

Open
Enesuygurs wants to merge 1 commit into
executablebooks:masterfrom
Enesuygurs:fix/include-parser-option
Open

Enesuygurs wants to merge 1 commit into
executablebooks:masterfrom
Enesuygurs:fix/include-parser-option

Conversation

@Enesuygurs

Copy link
Copy Markdown

Fixes #906

The MyST {include} directive accepts the parser option, since it reuses the option spec of the docutils include directive, but then ignores it. The file is always rendered as MyST Markdown. For example

```{include} part.rst
:parser: rst
```

renders .. note:: hi in part.rst as a plain paragraph rather than a note. A custom parser, like the one in the issue, is skipped the same way. An invalid parser name already produces a myst.directive_option warning, so only the valid case was broken.

The cause is MockIncludeDirective.run in myst_parser/mocking.py. It handles literal and code and otherwise always does a MyST nested render. Nothing reads self.options["parser"].

This PR adds a parser branch that does what docutils' Include.custom_parse does. The text goes into a new document, using the parser's default settings overlaid with the current document's settings. That document shares ids/nameids/nametypes with the parent, so targets and duplicate ids are handled across the boundary. The parser's transforms are applied, the parse and transform messages are passed up to the parent, and the resulting children are returned. The implementation is local because custom_parse only exists in newer docutils releases and we support >=0.20. I also listed the option in the include docs.

Testing: I added an "Include with parser" case to tests/test_renderers/fixtures/mock_include.md. It includes a small rST file with :parser: rst and expects a note node. It fails on master, where the note is a paragraph, and passes with the change. I also checked a Sphinx build by hand. An rST file with a label, a :ref: and a note, included via :parser: rst, renders correctly, and [](#rst-label) in the including Markdown file resolves to it. :parser: myst_parser.sphinx_ also works. The full test suite passes, and so do ruff check and ruff format --check.

The option was accepted but ignored, so the file was always parsed as MyST.
Parse it with the given parser into a new document, as the docutils include
directive does.

Fixes executablebooks#906

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Include directive does not consider parser option

1 participant