Sphinx - MyST Parser - markdown : 如何让一些内容出现在几个页面上？

Question

我们正在与我的团队使用 myst-parser (https://myst-parser.readthedocs.io/en/latest/index.html) 从 markdown 页面编写 Sphinx 文档，效果很好。

为避免重复和改进维护，我们希望通过 2 种方式在文档的多个部分之间共享内容：

1. 在 2 个不同的部分中列出相同的唯一页面
2. 使页面的某些内容出现在另一个页面中

这里有更多细节：

1. 当我在 2 个不同部分的索引中引用同一页面时：

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

其中两个索引都包含以下内容：

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

.. toctree::

  /open_pages/common/common_page.md

页面在左侧菜单中正确出现两次：

SECTION 1
    Common page
SECTION 2
    Common page

但如果我点击此菜单“SECTION 1”下的“Common page”链接，它会找到正确的页面，但实际上会将我带到菜单“SECTION 2”下的“Common page”链接，即导航有点麻烦。

知道为什么会发生这种情况或如何以不同的方式做到这一点吗？

1. 我不知道该怎么做，但这里是我想要的描述：

假设我有 page1.md 我有这个部分和表格

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

如何在 page2.md 中包含此部分的内容而不复制它？

提前感谢您的建议！

配置：

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

• 狮身人面像版本：3.1.2
• myst-parser 版本：0.15.2

Answer 1

使用include directive。

在每个部分中创建一个存根文件common_page.md。这应该可以正确解决导航问题。

还将common 目录及其文件更改为要包含的内容。

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

在每个common_page.md 中，将内容包含在您希望它出现的任何位置：

Subsection
----------

.. include::

    /open_pages/common/common_snippet.md

最后在每个index.rst 中，参考页面相对于index.rst：

.. toctree::

    common_page