$\LaTeX{}$之minted使用

发表于 更新于 分类于 ， 阅读次数： 本文字数： 2.9k 阅读时长 ≈ 14 分钟

本文介绍了如何在\(\LaTeX{}\)中使用minted宏包实现代码高亮效果。

介绍

minted 使用 Pygments 库提供语法高亮功能。它还提供自定义高亮源代码输出的选项，包括用 Python 实现的功能，例如使用正则表达式选择代码片段。

由于 minted 使用了 Pygments 和其他 Python 软件，因此它能够提供比纯粹用 LATEX 实现的语法高亮包（例如 listings）更丰富的高亮功能。过去，这种对外部软件的依赖带来了一些缺点，例如需要单独安装 Pygments。从 minted 版本 3 开始，所有 Python 软件（包括 Pygments）在使用 TEX 包管理器安装 minted时都会与 LATEX 包捆绑在一起，无需单独安装任何依赖项。

安装

1
2
tlmgr install minted # TeX Live
mpm --admin --install=minted  # MiKTeX

安装 minted 软件包后，它将包含 latexminted Python 可执行文件以及所有必需的 Python 库（包括 Pygments）。为了使这些库正常运行，必须安装 Python 3.8+ 并将其添加到 系统环境变量 PATH 中（v3.7.0还不支持Python3.14版本，可安装3.8-3.13中任意版本使用）。

基本用法

最小示例

默认缓存目录名称现在为 _minted。目录中的所有文件现在共享同一个缓存，而不是每个文档都拥有单独的缓存。

1
2
3
4
5
6
7
8
9
10
11
\documentclass{article}
\usepackage{minted}
\usepackage[svgnames]{xcolor}
\begin{document}
\begin{minted}[bgcolor=Beige, bgcolorpadding=0.5em]{c}
int main() {
printf("hello, world");
return 0;
}
\end{minted}
\end{document}

minted-minimal

格式化源代码

minted环境

minted 环境的基本使用如下：

1
2
3
4
\begin{minted}{python}
def boring(args = None):
pass
\end{minted}

要使用 Pygments 不支持的语言来使用 minted，或者只是禁用突出显示，请将语言设置为文本：\begin{minted}{text}。

\mint单行源代码

对于单行源代码，可以使用 \mint 作为 minted 的简写：

image-20250530153051999

这使用命令而不是环境来排版一行代码，因此可以节省一些输入，但其输出与 minted 环境的输出相同。代码由一对相同的字符分隔，类似于 \verb 的工作方式。

完整的语法为：

1
\mint[<options>]{<language>}<delim><code><delim>

其中代码分隔符可以是几乎任何标点符号。<code> 也可以使用成对的花括号 {} 分隔，只要 <code> 本身不包含未成对的花括号即可。 请注意，\mint 命令不适用于行内使用。相反，当只有一行代码时，它是 minted 的快捷方式。

\mintinline 命令适用于行内使用。

\mintinline行内源代码

语法为 :

1
\mintinline[<options>]{<language>}<delim><code><delim>

image-20250530153840449

分隔符可以是单个重复字符，就像 \verb 一样。它们也可以是一对花括号 {}。当 \mintinline 用于可移动参数（例如 \section）时，需要使用花括号。

\inputminted插入外部文件

\inputminted 命令用于输入外部文件。其语法为：

1
\inputminted[<options>]{<language>}{<filename>}

使用不同的style

除了使用默认的高亮style，您还可以选择 Pygments 提供的其他样式。有两种等效的方法可以做到这一点：

1
2
\usemintedstyle{name}
\setminted{style=name}

\usemintedstyle 只能修改代码style，\setminted 方法的优势在于它也能接受其他 minted 选项，比如字号、行号、行距、背景色、自动换行等，语义上是把 style 当作一个普通选项。

完整语法为：

1
2
\usemintedstyle[<language>]{<style>}
\setminted[<language>]{<key=value>}

style可以设置为整个文档（不指定语言），也可以仅为特定语言设置。请注意，style也可以通过每个命令和环境的可选参数来设置。

pygments.org/styles 提供了样式高亮示例。可以使用 pygments.org/demo 上的在线演示预览不同样式下的代码。也可以通过运行命令 pygmentize -L style 列出可用的样式。

支持语言

Pygments 支持数百种不同的编程语言、模板语言和其他标记语言。当前支持的语言列表。也可以运行 pygmentize -L lexers 命令。

浮动 listings

minted 提供了一个 listing 环境，可用于包裹代码块。这会将代码放置在类似于图形或表格的浮动框中，默认位置为 tbp。 还可以提供 \caption 和 \label：

image-20250530161050482

默认列表位置可以轻松修改。当包选项 newfloat=false（默认）时，float 包用于创建列表环境。可以通过重新定义 \fps@listing 来修改位置。例如，

1
2
3
\makeatletter
\renewcommand{\fps@listing}{htp}
\makeatother

当 newfloat=true 时，将使用功能更强大的 newfloat 包来创建列表环境。在这种情况下，可以使用 newfloat 命令来自定义列表：

\SetupFloatingEnvironment{listing}{placement=htp}

\listoflistings 宏将插入文档中所有（浮动）listings的列表：

image-20250530162056012

个性化 listing 环境

默认情况下，列表环境使用 float 包创建。在这种情况下，可以使用下文描述的 \listingscaption 和 \listoflistingscaption 宏来自定义caption and list of listings.。如果 minted 加载了 newfloat 选项，则列表环境将使用功能更强大的 newfloat 包创建。newfloat 是 caption 的一部分，caption 提供了许多自定义标题的选项。

使用 newfloat 创建列表环境时，应使用 newfloat 的 \SetupFloatingEnvironment 命令进行自定义。例如，可以使用以下命令将标题中的字符串“Listing”更改为“Program code”：

\SetupFloatingEnvironment{listing}{name=Program code}

并且“List of Listings”可以更改为“List of Program Code”，

\SetupFloatingEnvironment{listing}{listname=List of Program Code}

请参阅 newfloat 和 caption 文档以获取更多信息。

默认情况下，包选项 newfloat=false时，自定义列表 \listingscaption 标题中的字符串“Listing”。此功能仅在包选项 newfloat=false 时有效。例如：

\renewcommand{\listingscaption}{Program code}

自定义列表标题“List of Listings”。此功能仅在包选项 newfloat=false 时有效。例如：

\renewcommand{\listoflistingscaption}{List of Program Code}

选项

宏包选项

\usepackage[options]{minted}

常用的 options 如下：

  • chapter 控制Listing的章节序号，也可选为 section 。
  • cache=true 缓存源代码选项。默认情况下处于启用状态。cache 选项会在文档根目录中创建一个 _minted 目录（可以使用 cachedir 选项自定义）。高亮代码的文件存储在此目录中，以便以后无需再次高亮代码。不再使用的缓存文件会被自动删除。在大多数情况下，缓存可以显著加快文档的编译速度。
  • cachedir=_minted 缓存文件的存储目录。默认值：_minted，路径应使用正斜杠，即使在 Windows 下也是如此。
  • newfolat=false 默认情况下，列表环境使用 float 包创建。newfloat 选项会改为使用 newfloat 创建列表环境。这可以更好地与 caption 包集成。

其他options包括debug=false、frozencache=false、highlightmode=fastfirst、inputlexerlinenos=false、lexerlinenos=false、placeholder=false、verbatim=false，具体含义参考说明文档texdoc minted。

设置命令和环境的选项

通过设置\setminted[<lexer>]{key=value,...} 和\setmintedinline[<lexer>]{key=value,...}来为整个文档或特定语言设置选项，这个设置的选项覆盖文档整体层面的选项。单命令选项会覆盖这里的选项。

且用\setmintedinline指定的设置都会覆盖用\setminted设置的设置。也就是说，内联设置总是比常规设置具有更高的优先级。

命令和环境选项

以下是常用的key列表：

  • autogobble=false 自动删除所有常见的前导空格，当autogobble和gobble一起使用时，效果是累积的。首先autogobble删除所有常见的缩进，然后应用gobble。

  • bgcolor=none 命令和环境的背景颜色。

  • breaklines=false 长行自动换行。

  • encoding=UTF-8 \inputminted及其派生命令读取文件时使用的文件编码。

  • escapeinside=none 在指定的两个字符之间切换到LATEX模式。这两个字符之间的所有代码都将被解读为LATEX并相应地排版。这允许进行额外的格式化。转义字符不必相同。

    1
    2
    3
    4
    5
    6
    \setminted{escapeinside=||}
    \begin{minted}{py}
    def f(x):
    y = x|\colorbox{green}{**}|2
    return y
    \end{minted}

  • firstline=1 要显示的第一行。该行之前的所有行都将被忽略，不会出现在输出中。

  • firstnumber=1 第一行的行号。

  • fontsize 代码字体大小。

  • frame=none 用于源代码列表周围的边框类型。可选项：(none | leftline | topline | bottomline | lines | single)。

  • framerule=0.4pt 框架的线宽。

  • framesep=\fboxsep 框架与内容之间的距离。

  • gobble=0 从每一行输入中删除前n个字符。

  • highlightcolor=LightCyan 高亮的代码行背景颜色。

  • highlightlines=none 这会根据行号高亮显示单行或一系列行。例如，highlightlines={1, 3-4}。

  • label 在代码周围的框架顶部、底部或两者都添加一个标签。

  • labelposition 标签的位置。可选项：(none | topline | bottomline | all)。

    1
    2
    3
    4
    5
    6
    7
    8
    \begin{minted}[frame=single,labelposition=all,label=test]{c}
    #include <stdio.h>

    int main() {
    	printf("hello, world");
    	return 0;
    }
    \end{minted}
    latex-minted-label

  • linenos=false 启用行号。

  • mathescape=false 在注释中启用LATEX数学模式。

  • numberblanklines=true 启用或禁用空行编号。

  • numberfirstline=false 无论stepnumber怎么样，都要给第一行编号。

  • numbers 本质上与 linenos 相同，不同之处在于可以指定数字出现的一侧。可选项：(left | right | both | none)。

  • numbersep=12pt 数字与行首之间的间距。

  • obeytabs=false 将制表符视为制表符，而不是将它们转换为空格。

  • rulecolor=black 框架的颜色。

  • showspaces=false 启用可见空格。

  • showtabs=false 启用可见的制表符，仅在与obeytabs结合使用时有效。

  • stepnumber=1 行号出现的间隔。

  • style=default 设置 Pygments 所使用的样式表。

  • texcl=false 允许在注释中使用LATEX代码。

更多key值参考说明文档texdoc minted。

定义快捷方式

包含多个列表的大型文档可能对于大多数列表使用相同的语言和相同的选项集。因此，minted 定义了一组命令，允许定义命令和环境的快捷方式。每个快捷方式都特定于一种语言。

  • \newminted \newminted为 minted 环境定义了一个新别名：

    1
    2
    3
    4
    5
    6
    7
    \newminted{cpp}{gobble=2,linenos}
    \begin{cppcode}
    template <typename T>
    T id(T value) {
    return value;
    }
    \end{cppcode}

    如果你想动态提供额外的选项，或者覆盖现有的默认选项，你也可以这样做：

    1
    2
    3
    4
    5
    \newminted{cpp}{gobble=2,linenos}
    \begin{cppcode}[linenos=false,
    frame=single]
    int const answer = 42;
    \end{cppcode}

    环境的默认名称是<lexer>code。如果此名称与另一个环境，或者如果你想选择一个不同的名称，你可以使用可选的参数：\newminted[environment name]{lexer}{options}。

  • \newmint 为\mint 定义的快捷方式语法是：\newmint[<macro name>]{lexer}{options}，参数和用法与\newminted相同。如果macro name未指定，则使用lexer。

    minted-newmint

  • \newmintinline 这创建了个性化版本的mintinline。语法和\newmint语法相同。如果macro name未指定，则使用<lexer>inline。

    minted-newmintinline

  • newmintedfile 这创建了个性化版本的inputminted。语法是\newmintedfile[<macro name>]{lexer}{options}，如果macro name未指定，则使用<lexer>file。

导言区常用设置

导言区常用设置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
\usepackage{float}
\usepackage{minted}

\renewcommand{\listingscaption}{源代码}				% 默认为"Listing"
\renewcommand{\listoflistingscaption}{源代码列表}	  % 默认为"List of Listings"

\setminted{
  encoding=utf8,            % 源码编码
  autogobble,               % 自动去除公共缩进
  fontsize=\small,          % 代码字体大小
  breaklines,               % 自动换行
  linenos,                  % 显示行号 left | right | both | none 
  numbers=left,		    	% 行号位置
  frame=single              % single | lines | leftline | none | topline | bottomline
}

\makeatletter
\renewcommand{\fps@listing}{htp} % 设置listing环境默认浮动位置
\makeatother

参考文章

  1. The minted package: Highlighted source code in LATEX