如何用RST+Sphinx的include指令生成单条<dl>定义列表？

方案1：拆分条目为独立片段文件（无模板引擎循环） #

• 主容器文件（比如dl-main.html）先写好外层的<dl>标签，再逐个引入条目片段：

<dl>
  <!-- 引入每个条目的片段文件 -->
  {% include "item-page1.html" %}
  {% include "item-page2.html" %}
  {% include "item-page3.html" %}
</dl>

• 每个条目片段文件（比如item-page1.html）仅包含对应条目的<dt>和<dd>，不要加<dl>标签：

<dt><a href="/page1.html">页面1标题</a></dt>
<dd>页面1的详细描述内容</dd>

所有引入的片段内容会被包裹在同一个<dl>中，不会生成多个独立列表。

方案2：数据文件+模板循环（维护效率更高） #

如果使用支持数据文件的模板引擎（如Jekyll、Eleventy、Twig），可以把页面链接和描述统一存在数据文件里，比如_data/pages.yml：

- title: 页面1标题
  url: /page1.html
  desc: 页面1的详细描述内容
- title: 页面2标题
  url: /page2.html
  desc: 页面2的详细描述内容

然后在模板中循环渲染整个列表：

<dl>
  {% for page in site.data.pages %}
    <dt><a href="{{ page.url }}">{{ page.title }}</a></dt>
    <dd>{{ page.desc }}</dd>
  {% endfor %}
</dl>

这种方式无需维护多个零散片段，直接修改数据文件就能更新列表，维护成本更低。

方案3：原生HTML+服务器端脚本（以PHP为例） #

如果用PHP实现，可先定义页面数据数组，再循环输出：

<?php
$pages = [
  ['title' => '页面1标题', 'url' => '/page1.html', 'desc' => '页面1的详细描述内容'],
  ['title' => '页面2标题', 'url' => '/page2.html', 'desc' => '页面2的详细描述内容']
];
?>
<dl>
  <?php foreach($pages as $page): ?>
    <dt><a href="<?= $page['url'] ?>"><?= $page['title'] ?></a></dt>
    <dd><?= $page['desc'] ?></dd>
  <?php endforeach; ?>
</dl>

若一定要分文件存储<dt>和<dd>，可按条目命名文件（比如dt-page1.html、dd-page1.html），再通过循环配对引入：

<?php
$pageSlugs = ['page1', 'page2'];
?>
<dl>
  <?php foreach($pageSlugs as $slug): ?>
    <?php include "dt-$slug.html"; ?>
    <?php include "dd-$slug.html"; ?>
  <?php endforeach; ?>
</dl>

这样能保证<dt>与<dd>正确配对，且全部处于同一个<dl>容器内。

内容的提问来源于stack exchange，提问作者Nik