如何在使用Jinja2的RST文件中实现图文并排显示？

问题描述 #

我在带有Jinja2文本替换的RST文档中尝试实现图片与文本并排显示，使用了RST的替换定义语法，但渲染后图片并未显示，而是直接输出|myimage|文本。

我的RST代码示例：

|myimage| {{ name }}
{{ "-" * name|length }}

...

.. |myimage| image:: /_images/myimage.png
   :width: 40%

原因及解决办法 #

1. 替换定义位置错误 #

RST的替换定义（.. |myimage| ...）需要放在被引用的|myimage|之前，部分解析器对定义顺序有严格要求。调整位置后代码如下：

.. |myimage| image:: /_images/myimage.png
   :width: 40%

|myimage| {{ name }}
{{ "-" * name|length }}

...

2. 渲染流程顺序颠倒 #

确保渲染流程是先执行Jinja2模板替换，再解析RST。如果顺序颠倒（先解析RST再处理Jinja），RST解析器会把{{ name }}当成普通文本，Jinja也无法识别RST的替换定义，最终导致图片无法渲染。

3. 图片路径验证 #

检查/_images/myimage.png的路径是否符合渲染工具的规则：

• 若使用Sphinx等工具，路径需对应html_static_path配置的静态资源目录；
• 可先尝试用绝对URL测试，确认图片本身能正常加载。

4. 图文并排的正确实现 #

即使替换定义生效，默认图片是块级元素，无法和文本并排，可通过以下两种方式实现：

方法1：行内图片+CSS控制

给替换定义添加行内类，配合CSS实现并排：

.. |myimage| image:: /_images/myimage.png
   :width: 40%
   :class: inline

|myimage| {{ name }}

对应的CSS样式：

.inline {
    display: inline-block;
    vertical-align: middle;
}

方法2：表格布局

用RST表格实现严格的分栏并排：

.. table::
   :widths: 40 60

   * - .. image:: /_images/myimage.png
         :width: 100%
     - {{ name }}
       {{ "-" * name|length }}

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