Possibility to include the content of a specific markdown section?

[mara004]

Context

I'd like to include a specific section of a Readme file in my sphinx documentation. With {include} ../../README.md I can include the whole file, but is it also possible to include a just the content of a specific section, without the heading?

In the Readme, the first heading is the project name, while in the Sphinx documentation I would like it to be "Readme".

This is somewhat related to #516, with the difference that I'd like to rename the first heading instead of putting another heading above.

Proposal

Something like :section: section_name (below the {include} line) to include only the content of the given section.

Tasks and updates

No response

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[mara004]

Ah, after some browsing I found the relevant code passage

MyST-Parser/myst_parser/mocking.py

Line 319 in 28725fc

class MockIncludeDirective:

There I realised this is already implemented with the :start-after: option.
However, I can't find this being documented anywhere. It would be really helpful if there were some page specifying the directive's options.

[chrisjsewell]

pr's welcome to https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#common-roles-and-directives @mara004 😄

[mara004]

Thanks, I can take a look, though usually it's best if the people who write the code also write the API documentation, to avoid mistakes or missing details. However, I also understand that developers may be busy enough with the code itself, and writing documentation can sometimes be a bit of a liability.