Sphinx - MySTParser - markdown : 如何让一些内容出现在多个页面上？

Question

我们正在与我的团队使用 myst-parser (https://myst-parser.readthedocs.io/en/latest/index.html) 从降价页面编写一个 Sphinx 文档，它工作得很好。

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

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

以下是更多详细信息：

当我在 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

但是，如果我单击此菜单“第 1 部分”下的“通用页面”link，它会找到正确的页面，但实际上会将我带到“通用页面”link菜单的“SECTION 2”，有点不方便导航。

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

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

假设我有 page1.md 和 table

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

如何在不复制的情况下将此部分的内容包含在 page2.md 中？

提前感谢您的建议！

配置：

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

狮身人面像版本：3.1.2
myst-解析器版本：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

Sphinx - MySTParser - markdown : 如何让一些内容出现在多个页面上？

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

markdown

python-sphinx

myst