Skip to content

Question: {include} rST files in md? #204

@rossbar

Description

@rossbar

Is your feature request related to a problem? Please describe.

It would be nice if it were possible to include the parsed output from an .rst formatted file in a MyST markdown file via the {include} (or perhaps some other, new) directive.

Describe the solution you'd like

For example, let's say you have two files: hello.rst and world.md like so:

hello.rst:

.. note::
   Hello

world.md:

```{include} hello.rst
```
```{note}
World!
```

The desired output after running sphinx would be an html file containing two note boxes. Given that this feature crosses the boundary between parsing MyST files and building with sphinx, I'm not sure that this is the appropriate place to raise the issue... please LMK if there is a better place for it!

Describe alternatives you've considered

The simplest solution would be to convert the file (e.g. hello.rst in the example above) to myst syntax. There are some cases where this isn't feasible. For example, consider a contributing page in the documentation. One may want to have this included in, say, the sphinx documentation for a project as well as in the top level of the github repo. Since GitHub only supports parsing rst or gfm, you may have a situation where you want to {include} CONTRIBUTING.rst in the docs.

Of course, you can leave the file which includes the external file in .rst format, but then you have a mix of rst and md files in the documentation which may be confusing for new contributors.

Additional context

This question/feature request arose from the discussion in scikit-image/scikit-image#4863

Also possibly related to #163/#164

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions