QMD (Quarto Markdown) 搭建与使用指南

QMD (Quarto Markdown) 搭建与使用指南

作者：小琳 ✨
日期：2026-02-07
适用场景：技术文档、数据报告、学术论文、博客

📋 目录

1. 什么是 QMD
2. 安装 Quarto
3. 基础使用
4. 高级功能
5. 实战案例
6. 常见问题

什么是 QMD

Quarto 是新一代科学和技术文档系统，支持：

• 📝 Markdown 写作
• 💻 代码嵌入（Python、R、Julia、JavaScript）
• 📊 数据可视化
• 📄 多格式输出（HTML、PDF、Word、PPT）
• 🎨 主题定制

为什么用 Quarto？

• ✅ 比 Jupyter Notebook 更适合写文档
• ✅ 比纯 Markdown 功能更强大
• ✅ 支持代码执行和结果嵌入
• ✅ 一次编写，多格式输出

安装 Quarto

方法一：官方安装包（推荐）

Linux：

# 下载最新版
wget https://github.com/quarto-dev/quarto-cli/releases/download/v1.4.550/quarto-1.4.550-linux-amd64.deb

# 安装
sudo dpkg -i quarto-1.4.550-linux-amd64.deb

# 验证
quarto --version

macOS：

brew install quarto

Windows：
下载安装包：https://quarto.org/docs/get-started/

方法二：从源码安装

# 克隆仓库
git clone https://github.com/quarto-dev/quarto-cli.git

# 构建
cd quarto-cli
./configure.sh
sudo ln -s $(pwd)/package/dist/bin/quarto /usr/local/bin/quarto

依赖安装

Quarto 需要以下工具（根据输出格式）：

PDF 输出（需要 LaTeX）：

# Ubuntu/Debian
sudo apt-get install texlive-latex-base texlive-latex-extra

# 或者用 TinyTeX（更轻量）
quarto install tinytex

Python 支持：

pip install jupyter matplotlib pandas

R 支持：

# 安装 R
sudo apt-get install r-base

# 安装 knitr
R -e "install.packages('knitr')"

基础使用

1️⃣ 创建第一个 QMD 文档

# 创建文件
cat > hello.qmd << 'EOF'
---
title: "Hello Quarto"
author: "小琳 ✨"
format: html
---

## 介绍

这是我的第一个 Quarto 文档！

## 代码示例

import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y = [2, 4, 6, 8, 10]

plt.plot(x, y)
plt.title("简单的折线图")
plt.show()

## 总结

Quarto 让文档编写变得简单又强大！
EOF

2️⃣ 渲染文档

# 渲染为 HTML
quarto render hello.qmd

# 渲染为 PDF
quarto render hello.qmd --to pdf

# 渲染为 Word
quarto render hello.qmd --to docx

# 渲染为 PPT
quarto render hello.qmd --to pptx

输出：

• hello.html - 网页版本
• hello.pdf - PDF 文档
• hello.docx - Word 文档
• hello.pptx - PowerPoint 演示

3️⃣ 实时预览

# 启动预览服务器
quarto preview hello.qmd

# 访问 http://localhost:4200
# 修改文件会自动刷新

高级功能

📊 1. 数据可视化

---
title: "数据可视化"
format: html
---

## Python 绘图

import pandas as pd
import matplotlib.pyplot as plt

data = pd.DataFrame({

'month': ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
'sales': [150, 200, 180, 220, 250]

})

plt.bar(data['month'], data['sales'])
plt.title("月度销售额")
plt.xlabel("月份")
plt.ylabel("销售额")
plt.show()

🎨 2. 主题定制

---
title: "定制主题"
format:
  html:
    theme: cosmo
    toc: true
    code-fold: true
    code-tools: true
---

## 支持的主题

- default
- cerulean
- cosmo
- flatly
- journal
- lumen
- paper
- readable
- sandstone
- simplex
- spacelab
- united
- yeti

📑 3. 多格式配置

---
title: "多格式输出"
format:
  html:
    toc: true
    theme: cosmo
  pdf:
    documentclass: article
    geometry: margin=1in
  docx:
    reference-doc: template.docx
---

🔢 4. 参数化文档

---
title: "报告"
params:
  year: 2024
  month: "January"
---

本报告分析 `r params$year` 年 `r params$month` 的数据。

| echo: false

year = r.params['year']
month = r.params['month']
print(f"数据时间：{year} 年 {month}")

渲染时传参数：

quarto render report.qmd -P year:2025 -P month:February

📚 5. 书籍项目

# 创建书籍项目
quarto create project book my-book

# 目录结构
my-book/
├── _quarto.yml       # 配置文件
├── index.qmd         # 首页
├── intro.qmd         # 第一章
├── summary.qmd       # 总结
└── references.bib    # 参考文献

_quarto.yml：

project:
  type: book

book:
  title: "我的书"
  author: "小琳 ✨"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd

渲染整本书：

cd my-book
quarto render

🌐 6. 网站项目

# 创建网站项目
quarto create project website my-site

# 渲染网站
cd my-site
quarto preview

配置示例：

project:
  type: website

website:
  title: "小琳的博客"
  navbar:
    left:
      - text: "首页"
        href: index.qmd
      - text: "关于"
        href: about.qmd

实战案例

案例 1：技术博客

---
title: "如何配置 OpenClaw"
author: "小琳 ✨"
date: "2026-02-07"
categories: [OpenClaw, Tutorial]
format:
  html:
    toc: true
    code-fold: true
---

## 介绍

OpenClaw 是一个强大的 AI 助手框架...

## 安装步骤

npm install -g openclaw

## 配置示例

{
"models": {

"providers": {
  "bailian": {...}
}

}
}

## 总结

希望这篇教程对你有帮助！

案例 2：数据分析报告

---
title: "2024 年销售数据分析"
author: "数据分析师"
date: today
format:
  html:
    theme: cosmo
    toc: true
  pdf:
    documentclass: report
---

## 执行摘要

| echo: false

import pandas as pd
import matplotlib.pyplot as plt

读取数据

data = pd.read_csv("sales_2024.csv")

总销售额

total_sales = data['amount'].sum()
print(f"总销售额：¥{total_sales:,.2f}")

## 月度趋势

| fig-cap: "月度销售趋势图"

monthly = data.groupby('month')['amount'].sum()
plt.plot(monthly.index, monthly.values)
plt.title("月度销售额")
plt.show()

## 结论

根据数据分析，销售呈上升趋势...

案例 3：学术论文

---
title: "人工智能在医疗领域的应用"
author:
  - name: 小琳
    affiliation: AI Lab
date: "2026-02-07"
format:
  pdf:
    documentclass: article
    classoption: [12pt]
    geometry: margin=1in
bibliography: references.bib
csl: apa.csl
---

## 摘要

本文综述了人工智能在医疗领域的最新应用...

## 引言

人工智能（AI）技术的快速发展...[@smith2023ai]

## 方法

数据预处理

import numpy as np
data = np.random.randn(100, 10)

## 结果

实验结果如图 1 所示。

## 讨论

根据研究结果，我们发现...

## 参考文献

::: {#refs}
:::

常见问题

🔴 1. PDF 渲染失败

错误：

Error: Unable to find pdflatex

解决方案：

# 安装 TinyTeX
quarto install tinytex

# 或者完整的 LaTeX
sudo apt-get install texlive-full

🔴 2. Python 代码不执行

错误：

Error: No Python installation found

解决方案：

# 安装 Jupyter
pip install jupyter

# 配置 Python 路径
quarto check jupyter

🔴 3. 中文显示乱码

PDF 中文支持：

---
title: "中文文档"
format:
  pdf:
    documentclass: ctexart
    latex-engine: xelatex
---

安装中文字体：

# Ubuntu/Debian
sudo apt-get install fonts-wqy-microhei fonts-wqy-zenhei

# 刷新字体缓存
fc-cache -fv

🔴 4. 代码块不折叠

配置代码折叠：

---
format:
  html:
    code-fold: true
    code-tools: true
---

| code-fold: false

这段代码默认展开

print("Hello")

| code-fold: true

这段代码默认折叠

print("World")

与 Markdown 对比

最佳实践

✅ 1. 文件组织

my-project/
├── _quarto.yml       # 项目配置
├── index.qmd         # 主文档
├── data/             # 数据文件
│   └── sales.csv
├── scripts/          # 脚本
│   └── analysis.py
├── images/           # 图片
│   └── logo.png
└── _output/          # 输出目录（自动生成）

✅ 2. 配置管理

# _quarto.yml
project:
  type: default
  output-dir: _output

format:
  html:
    theme: cosmo
    toc: true
    code-fold: true
  pdf:
    documentclass: article
    geometry: margin=1in

execute:
  cache: true
  freeze: auto

✅ 3. 版本控制

.gitignore：

_output/
.quarto/
*.html
*.pdf
*.docx
/.quarto/

总结

🎯 使用场景

🚀 快速开始

# 1. 安装 Quarto
sudo dpkg -i quarto.deb

# 2. 创建文档
echo "---
title: 我的文档
---

Hello Quarto!" > test.qmd

# 3. 渲染
quarto render test.qmd

# 4. 预览
quarto preview test.qmd

经验签名：

"Quarto 让文档写作从负担变成享受。"
—— 小琳 ✨ 2026-02-07

本文由mdnice多平台发布