Skip to content

[ENH/FIX] Support headings in nested parse#1102

Open
minijackson wants to merge 2 commits intoexecutablebooks:masterfrom
minijackson:object-headings
Open

[ENH/FIX] Support headings in nested parse#1102
minijackson wants to merge 2 commits intoexecutablebooks:masterfrom
minijackson:object-headings

Conversation

@minijackson
Copy link

@minijackson minijackson commented Feb 4, 2026

This fixes using Markdown headings in Sphinx objects, like the object, describe, py:data directives, etc.; which fixes #1050.

In summary, this should now work:

# Title

```{object} foo
bar
# Title in object
wunderbar
## Sub-title in object
wunderbar
```

This works by adding the heading to the temp root parent instead of at the end of the previous section from the main document.

I've also added a change to the "heading to rubric" conversion in nested headings, whose levels now will be offset by the current heading level. So this:

# Title
## Sub-title
> Quote:
> # Title in quote
> Content.

will generate an h3 rubric inside the blockquote (offset by the "Sub-title" heading).
This makes it consistent with the way it works with Markdown headings inside objects (which is consistent with RST's headings inside objects).
Tell me if you think this change is appropriate, if not I can always remove the commit.

I've also used the heading-level option from Sphinx' rubric directive, so that Sphinx generate appropriately leveled headers from those rubrics.

Edit: for the offsetting of nested headers, I had to change a part of the documentation, because an example generated a level 4 headers, whose id wasn't generated due to a myst_heading_anchors value too low.

This fixes using Markdown headings in Sphinx objects,
like the `object`, `describe`, `py:data` directives, etc.

This works by adding the heading to the temp root parent
instead of at the end of the previous section from the main document.

Fixes executablebooks#1050
This makes it so nested headings (in blockquotes, admonitions, etc.)
generates rubrics that are offset by the current heading level,
meaning that:

```markdown
# Title
## Sub-title
> Quote:
> # Title in quote
> Content.
```

will generate a rubric level 3 (level 1 + offset by 2 by the "Sub-title")
inside the blockquote.

This also makes those rubrics support the Sphinx option `heading-level`,
for properly generating `<h1>`, `<h2>`, etc.

A fix in the documentation was necessary, as an example generated a
level-4 heading, whose id wasn't generated
due to a myst_heading_anchors value too low.
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.

Heading escape "API" object documentation

1 participant