Sphinx - MySTParser - markdown : How to let some content appear on several pages?

Question

We are writing a Sphinx doc with my team from markdown pages using myst-parser (https://myst-parser.readthedocs.io/en/latest/index.html), which is working quite well.

To avoid reduplication and improve maintenance, we would like to share content between several sections of our documentation, in 2 ways :

1. List the same unique page under in 2 different sections
2. Make some content of a page appear in another page

Here are some more details:

1. When I reference a same page in the index of 2 different sections:

    └── open_pages
        ├── common
        │   └── common_page.md
        ├── section_1
        |   └── index.rst
        └── section_2
            └── index.rst

where both indexes include something like:

Subsection
-----------------

.. toctree::

  /open_pages/common/common_page.md

The page correctly appears twice in the menu on the left side:

SECTION 1
    Common page
SECTION 2
    Common page

But if I click on the "Common page" link under "SECTION 1" of this menu, it finds the correct page but actually brings me to the "Common page" link under "SECTION 2" of the menu, which is a bit disturbing for navigation.

Any idea why this happens or how to do that differently?

2. I have no clue of how to do that but here is a description of what I would like:

Let's say I have page1.md where I have this section and table

## Interesting section
| Interesting | Table | 
|------|------|
| ... | ... |

How can I include in page2.md the content of this section without copying it?

Thanks in advance for your advice!

Config:

extensions = [
    'sphinx.ext.autosectionlabel',
    'myst_parser',
    'sphinx_markdown_tables'
]
autosectionlabel_prefix_document = True

• Sphinx Version: 3.1.2
• myst-parser Version: 0.15.2

Answer 1

Use the include directive.

Create a stub file common_page.md in each section. This should correctly resolve the navigation issue.

Also change the common directory and its file to be content to be included.

    └── open_pages
        ├── includes
        │   └── common_snippet.md
        ├── section_1
        │   ├── common_page.md
        |   └── index.rst
        └── section_2
            ├── common_page.md
            └── index.rst

And in each common_page.md, include the content wherever you want it to appear:

Subsection
----------

.. include::

    /open_pages/common/common_snippet.md

And finally in each index.rst, where the reference page is relative to the index.rst:

.. toctree::

    common_page