JupyterLab LaTeX

一个用于实时编辑LaTeX文档的JupyterLab扩展。

用法

编译

要编译和预览一个LaTeX文档

1. 在JupyterLab中打开一个 .tex 文档。
2. 使用以下方法之一编译和预览文档
   • 右键单击文档，从上下文菜单中选择 显示LaTeX预览。
   • 单击文档顶部工具栏中的 预览 按钮。

两种方法都会编译 .tex 文件并打开渲染的PDF文档。文件的后续保存将自动更新PDF。如果PDF无法编译（可能是由于语法错误），将打开一个错误面板，详细说明LaTeX错误。

写作工具

文档顶部的工具栏菜单提供对常用LaTeX编辑任务的快捷方式

文本格式化

• 下标：突出显示您想要设置为下标的文本，然后点击 Xᵧ 按钮。如果没有文本被突出显示，将出现一个输入对话框，让您输入下标。
• 上标：突出显示您想要设置为上标的文本，然后点击 Xⁿ 按钮。如果没有文本被突出显示，将出现一个输入对话框，让您输入上标。
• 粗体：突出显示您想要设置为粗体的文本，然后点击 B 按钮。
• 斜体：突出显示您想要设置为斜体的文本，然后点击 I 按钮。
• 下划线：突出显示您想要添加下划线的文本，然后点击 U 按钮。

文本布局

• 左对齐：突出显示您想要左对齐的文本，然后点击左对齐按钮。
• 居中对齐：突出显示您想要居中对齐的文本，然后点击居中对齐按钮。
• 右对齐：突出显示您想要右对齐的文本，然后点击右对齐按钮。

列表

• 项目符号列表：点击项目符号列表按钮以插入项目符号列表。
• 编号列表：点击编号列表按钮以插入编号列表。

表格和图形

• 表格创建GUI：点击表格按钮以打开对话框，创建具有指定行数和列数的表格。
• 添加图形：点击图形按钮以选择图形类型并将其插入到您的文档中。可用的图形类型包括
  • 简单函数图形
  • 从文件绘制图形
  • 散点图
  • 条形图
  • 等高线图
  • 参数图

错误处理

• 错误日志过滤选项：增强错误日志过滤选项，帮助您快速识别和解决问题。

主菜单助手

• 常量菜单：快速插入常用数学常数。
• 符号菜单：轻松插入各种数学符号。

有关更高级的用法文档，请参阅此处。

要求

• JupyterLab >= 4.0
  • 旧版本在PyPI和npm上提供的先前版本中受支持，请参阅发布
• Python >= 3.8
• 一个可以将 .tex 文件编译为 PDF 的应用程序（例如，pdflatex、xelatex；在 Windows 上使用 MiKTeX 的 pdflatex.exe）。此应用程序必须在笔记本服务器相同的环境中作为命令可用。
• 一个可以处理 .bib 文件以生成参考文献的应用程序。与 LaTeX 命令一样，这也必须在笔记本服务器相同的环境中可用。

安装

此扩展包括笔记本服务器扩展（与 LaTeX 编译器接口）和实验室扩展（提供 LaTeX 预览的 UI）。名为 jupyterlab-latex 的 Python 包提供这两个作为预构建扩展。

要安装扩展，请在您的终端中运行以下命令

• 对于 pip

  pip install jupyterlab-latex
  

• 对于 conda

  conda install conda-forge::jupyterlab-latex
  

检查安装

为确保扩展正确安装，您可以检查服务器和实验室扩展

jupyter server extension list

并在输出中看到如下块

jupyterlab_latex enabled
    - Validating jupyterlab_latex...
Package jupyterlab_latex took 0.0010s to import
      jupyterlab_latex 4.1.3 OK

然后

jupyter labextension list

并在输出中看到如下块

@jupyterlab/latex v4.1.3 enabled OK (python, jupyterlab-latex)

自定义

默认情况下，扩展在服务器上运行 xelatex 引擎。您可以通过自定义 jupyter_notebook_config.py 文件来自定义此命令（例如，使用 pdflatex 代替）

c.LatexConfig.latex_command = 'pdflatex'

上述配置将使用常见的预定义标志和选项（如 -interaction、-halt-on-error、-file-line-error、-synctex）编译 LaTeX 文档。要更精确地控制命令序列，请检查手动命令参数配置。

扩展默认使用 bibtex 运行来生成参考文献，如果找到 .bib 文件。您也可以通过设置来配置参考文献命令

c.LatexConfig.bib_command = '<custom_bib_command>'

4.2.0 新增：如果满足以下条件之一，将跳过 BibTeX 编译

• c.LatexConfig.disable_bibtex 在 jupyter_notebook_config.py 文件中明确设置为 True
• 文件夹中没有找到 .bib 文件

要渲染引用（例如 \ref{...}），如方程式或章节编号，您需要通过设置进行多遍编译

c.LatexConfig.run_times = 2

4.2.0 新增：手动编译命令。对于更高级的定制，您可以使用 jupyter_notebook_config.py 文件中的 manual_cmd_args 配置来指定完整的命令序列。这允许定义扩展最终将执行的精确命令和选项

c.LatexConfig.manual_cmd_args = [
    'lualatex',  # Specify the LaTeX engine (e.g., lualatex, pdflatex)
    '-interaction=nonstopmode',  # Continue compilation without stopping for errors
    '-halt-on-error',  # Stop compilation at the first error
    '-file-line-error',  # Print file and line number for errors
    '-shell-escape',  # Enable shell escape
    '-synctex=1',  # Enable SyncTeX for editor synchronization
    '{filename}.tex'  # Placeholder for the input file name
]

手动编译命令中只支持 {filename} 这个占位符。在编译过程中，它将被 LaTeX 文件的名称替换。

也可以添加其他标签和选项来编辑配置值。

4.2.0 新增：支持 Tectonic 引擎。扩展现在也支持 Tectonic 引擎来编译 LaTeX 文件。要将 Tectonic 作为默认的 LaTeX 引擎，请自定义 jupyter_notebook_config.py 文件

c.LatexConfig.latex_command = 'tectonic'

Tectonic 的默认命令序列生成输出文件为 pdf 格式，并使用可用的 SyncTeX 标志。

要获得对 Tectonic 的更高级控制，请在 manual_cmd_args 设置中指定选项

c.LatexConfig.manual_cmd_args = [
    'tectonic',
    '--outfmt=pdf',  # Output format as PDF
    '--synctex=1',  # Enable SyncTeX for editor synchronization
    '--outdir',  # The directory in which to place output files
    '--keep-logs',  # Keep the log files generated during processing
    '{filename}.tex'  # Input .tex file
]

安全和自定义 shell 跳出

LaTeX 文件具有通过触发外部 shell 命令来运行任意代码的能力。这是一个安全风险，因此大多数 LaTeX 发行版都限制了您可以在 shell 中运行的命令。

您可以通过设置 LatexConfig.shell_escape 值来自定义行为。它可以取三个值："restricted"（默认）允许执行被认为是安全的命令，"allow" 允许所有命令，"disallow" 禁止所有命令。例如，要强制您的 LaTeX 发行版运行任何命令，请使用

c.LatexConfig.shell_escape = "allow"

贡献

如果您想为项目做出贡献，请阅读我们的 贡献者文档。

JupyterLab 遵循官方 Jupyter 行为准则。

开发安装

注意：您需要 NodeJS 来构建扩展包。

jlpm 命令是 JupyterLab 随附的 yarn 版本，与 JupyterLab 一起安装。您可以使用 yarn 或 npm 代替下面的 jlpm。

为了简化开发设置，您可以使用以下 Conda 环境

conda create -n jupyterlab-latex-env -c conda-forge python=3.10 jupyterlab=4.0.0 hatchling=1.17.0 nodejs=18
conda activate jupyterlab-latex-env

# Clone the repo to your local environment
git clone https://github.com/jupyterlab/jupyterlab-latex.git
# Change directory to the jupyterlab-latex directory
cd jupyterlab-latex
# Install package in development mode
pip install -e .

# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite
# Server extension must be manually installed in develop mode
jupyter server extension enable jupyterlab_latex
# Rebuild extension Typescript source after making changes
jlpm run build

您可以在不同的终端中同时监视源目录并运行 JupyterLab，以监视扩展源中的更改，并自动重新构建扩展。

# Watch the source directory in one terminal, automatically rebuilding when needed
jlpm run watch
# Run JupyterLab in another terminal
jupyter lab

在运行监视命令的情况下，每次保存的更改都将立即在本地构建并提供给运行的 JupyterLab。刷新 JupyterLab 以在浏览器中加载更改（您可能需要等待几秒钟以重新构建扩展）。

更改

有关 jupyterlab-latex 库不同版本的更改信息，请参阅我们的 变更日志。