如何在Quarto中使用Mermaid代码块？解决‘mermaid: command not found’报错

1. 确认mermaid-cli的正确安装方式 #

局部安装（仅当前项目）可能导致Quarto无法定位可执行文件，建议全局安装mermaid-cli：

npm install -g @mermaid-js/mermaid-cli

全局安装后，mmdc（注意是mmdc而非mermaid）会被加入系统全局PATH，Quarto默认调用的是mmdc命令，这是容易混淆的关键点。

2. 验证mmdc是否在系统PATH中 #

在终端执行以下命令，检查可执行文件路径是否存在：

which mmdc

若返回具体路径（如/usr/local/bin/mmdc或~/.npm-global/bin/mmdc），说明路径配置正常；若无输出，需手动将npm全局安装目录添加到PATH：

MacOS环境 #

编辑~/.zshrc（使用bash则编辑~/.bash_profile），添加以下内容：

export PATH="$HOME/.npm-global/bin:$PATH"

执行source ~/.zshrc使配置生效。

Ubuntu环境 #

编辑~/.bashrc，添加以下内容：

export PATH="$HOME/.npm-global/bin:$PATH"

执行source ~/.bashrc使配置生效。

3. 手动指定mmdc路径（可选） #

若全局安装后仍报错，可在Quarto文档的YAML头部直接指定mmdc的绝对路径：

---
title: "你的文档标题"
format: html
execute:
  mermaid:
    path: "/usr/local/bin/mmdc" # 替换为你的mmdc实际路径
---

4. 测试Mermaid代码块 #

用以下示例代码验证渲染是否正常：

flowchart LR
    A[开始] --> B{判断}
    B -->|是| C[执行操作]
    C --> D[结束]
    B -->|否| E[跳过]
    E --> D

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