您需要在源文档中定义代码块的“语言”。Sphinx和MkDocs都将尝试猜测该语言,这通常已经足够好了。但是,有时它会猜错并导致奇怪的突出显示。为了避免这种情况,这两种实现都提供了一种机制来手动定义每个代码块的语言。
对于Sphinx,可以使用code-block指令并包括该块的“语言”:
.. code-block:: console
You shell commands go here
在上面的示例中,我使用console
了shell会话。别名shell-session
也可以使用。需要注意的是替代词法分析器bash
(和它的别名:sh
,ksh
,zsh
,和shell
),因为它们是一个shell脚本woudl不严格是合适的,而你在一个shell会话同时显示的命令和theoutput。
在Pygments文档中可以找到受支持的语言代码的完整列表。
MkDocs利用Fenced 代码块 Markdown扩展来定义代码块的“语言”:
``` shell
Your shell commands go here
```
作为MkDocs使用highlight.js而非Pygments来做,支持的语言列表是不同的。因此,我shell
在上面的示例中使用了(用于shell会话)。