3步掌握Quarkdown：面向内容创作者的排版工具

一、价值呈现：Quarkdown解决的三大核心场景

1.1 学术论文排版自动化

对于科研人员和学生而言，格式化参考文献、公式编号和章节引用是学术写作中最耗时的工作之一。Quarkdown通过内置的文献管理系统和自动编号功能，将原本需要手动调整的格式工作自动化，让作者可以专注于内容创作而非排版细节。

1.2 交互式演示文稿制作

内容创作者经常需要将文档转换为演示文稿。Quarkdown允许在同一源文件中无缝切换文档模式和幻灯片模式，无需重新排版即可生成专业的演示文稿，大大提高了内容复用率和工作效率。

1.3 多格式文档统一管理

技术文档通常需要以多种格式发布，如网页版、PDF版和电子书版。Quarkdown的单一源文件多输出格式特性，确保所有版本内容同步更新，避免了多版本维护的麻烦。

二、场景实践：从环境准备到文档发布的完整流程

2.1 环境准备：确保系统满足运行要求

2.1.1 环境检测

在开始安装前，需要确认系统是否已安装必要的依赖：

# 检查Java版本（需Java 17或更高）
java -version

# 检查Node.js和npm（PDF导出功能需要）
node -v && npm -v

[!TIP] 如果Java版本低于17，请先安装或升级Java。Linux用户可使用sudo apt install openjdk-17-jdk，macOS用户可使用brew install openjdk@17。

2.1.2 基础安装

选择以下一种安装方式：

安装方法	适用系统	优点	缺点
包管理器	Linux/macOS	安装简单，自动更新	可能不是最新版本
一键脚本	Linux/macOS	自动安装所有依赖	需要管理员权限
手动安装	所有系统	版本可控	需手动配置环境变量

使用包管理器安装（推荐）：

# Linux/macOS使用Homebrew
brew tap quarkdown-labs/quarkdown
brew install quarkdown-labs/quarkdown/quarkdown

使用一键安装脚本：

curl -fsSL https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.sh | sudo env "PATH=$PATH" bash

2.1.3 验证测试

安装完成后，验证Quarkdown是否正确安装：

# 检查版本
quarkdown --version

# 创建测试项目
quarkdown create test-project
cd test-project

# 编译测试文档
quarkdown c main.qd

如果一切正常，会在output目录下生成HTML文件。

2.2 功能探索：从基础到高级的功能体验

2.2.1 核心功能：Markdown增强版

Quarkdown完全兼容标准Markdown，并增加了强大的扩展功能：

代码块增强：

```java {.line-numbers caption="带行号和标题的代码块"}
public class HelloQuarkdown {
    public static void main(String[] args) {
        System.out.println("Hello, Quarkdown!");
    }
}

**数学公式：**

$$E = mc^2$$

[![Quarkdown演示](https://raw.gitcode.com/GitHub_Trending/qu/quarkdown/raw/4e787f744fba9b55ebd78ce4428573fed0dd9cf3/demo/img/banner.png?utm_source=gitcode_repo_files)](https://gitcode.com/GitHub_Trending/qu/quarkdown?utm_source=gitcode_repo_files)
*Quarkdown界面展示了其丰富的排版功能*

#### 2.2.2 扩展功能：超越基础的排版能力
**多列布局：**

::: columns :::: column 左侧内容 :::: :::: column 右侧内容 :::: :::

[![双列布局示例](https://raw.gitcode.com/GitHub_Trending/qu/quarkdown/raw/4e787f744fba9b55ebd78ce4428573fed0dd9cf3/docs/multi-column-layout/two-columns.png?utm_source=gitcode_repo_files)](https://gitcode.com/GitHub_Trending/qu/quarkdown?utm_source=gitcode_repo_files)
*双列布局使内容组织更加灵活*

**交叉引用：**

{#fig:logo}

如@fig:logo所示，这是Quarkdown的图标。

[![交叉引用示例](https://raw.gitcode.com/GitHub_Trending/qu/quarkdown/raw/4e787f744fba9b55ebd78ce4428573fed0dd9cf3/docs/cross-references/figure-reference.png?utm_source=gitcode_repo_files)](https://gitcode.com/GitHub_Trending/qu/quarkdown?utm_source=gitcode_repo_files)
*自动编号和交叉引用功能*

#### 2.2.3 实战组合：创建演示文稿
使用Quarkdown创建幻灯片非常简单，只需在文档开头设置文档类型：

---

document-type: slides

这是幻灯片内容

---

更多内容

编译为幻灯片：
```shell
quarkdown c presentation.qd --pdf

使用Quarkdown生成的演示文稿

2.3 配置优化：提升文档质量的高级设置

2.3.1 基础配置

通过文档头部的元数据设置基本属性：

---
title: "我的Quarkdown文档"
author: "作者姓名"
date: "2023-10-01"
format:
  html:
    theme: minimal
---

2.3.2 场景配置

针对不同文档类型的专用配置：

学术论文配置：

---
document-type: paper
bibliography: references.bib
citation-style: apa
---

书籍配置：

---
document-type: book
chapters:
  - intro.qd
  - chapter1.qd
  - conclusion.qd
---

2.3.3 优化配置

提升输出质量的高级设置：

---
pdf:
  margin: 1in
  font:
    family: "Noto Sans"
    size: 12pt
  page-size: A4
---

[!TIP] 默认值：margin=0.5in，font.size=11pt，page-size=Letter。对于学术论文，推荐设置margin=1in，page-size=A4。

三、进阶探索：深入Quarkdown生态系统

3.1 自定义主题开发

Quarkdown支持通过CSS自定义文档样式。创建custom-theme.scss文件，然后在文档中引用：

---
format:
  html:
    css: custom-theme.scss
---

3.2 函数与脚本扩展

利用Quarkdown的函数编程能力自动化复杂任务：

= sum(read_csv("data.csv").column("values"))

3.3 社区与资源

• 官方文档：docs/main.qd
• 示例项目：demo/demo.qd
• 社区插件：quarkdown-libs/

四、常见问题解决

4.1 PDF导出失败

问题现象：编译PDF时提示"Puppeteer not found"
原因分析：PDF导出依赖Puppeteer但未安装
解决步骤：

# 安装Puppeteer
npm install -g puppeteer

4.2 中文显示乱码

问题现象：生成的文档中中文显示为方框
原因分析：系统缺少中文字体
解决步骤：

1. 安装中文字体（如Noto Sans SC）
2. 在配置中指定字体：

---
pdf:
  font:
    family: "Noto Sans SC"
---

4.3 实时预览不更新

问题现象：修改文件后预览未自动更新
原因分析：文件监视功能未正常工作
解决步骤：

# 使用--watch选项重新启动预览
quarkdown c document.qd -p -w

通过以上步骤，你已经掌握了Quarkdown的核心功能和使用方法。无论是学术写作、技术文档还是演示文稿，Quarkdown都能帮助你以更少的精力创建更专业的文档。开始你的Quarkdown之旅吧！