我的第一篇Quarkdown文档

欢迎使用Quarkdown 🚀

这是一个Quarkdown文档，支持：

• 标准Markdown格式
• 函数调用: {{ sum(1, 2, 3) }}
• 高级排版功能

## 核心功能详解与实践

### 编译与预览
```shell
# 基本编译
quarkdown compile src/main.qd

# 实时预览
quarkdown compile src/main.qd --preview --watch

核心编译选项：

• -o <目录>：指定输出目录（默认：./output）
• --pdf：生成PDF文件
• --server-port <端口>：自定义预览服务器端口
• --strict：严格模式，遇到错误立即停止

高级排版功能

Quarkdown提供了丰富的排版功能，如：

1. 自定义页面设置

{{ page(
  size="A4",
  margin="2cm",
  orientation="portrait"
) }}

2. 表格与数据处理

{{ table(
  data=readCsv("data/people.csv"),
  headers=["姓名", "年龄", "职业"],
  striped=true
) }}

3. 图表生成

使用Mermaid语法创建流程图：

{{ mermaid("
graph TD
    A[开始] --> B[处理]
    B --> C{判断}
    C -->|是| D[结果A]
    C -->|否| E[结果B]
") }}

实用场景案例

学术论文排版

通过Quarkdown的 bibliography功能管理参考文献：

{{ bibliography(
  file="references.bib",
  style="apa"
) }}

引用示例：{{ cite("smith2023quarkdown") }}

技术文档创作

利用代码块和语法高亮展示代码示例：

// 代码示例
public class Point {
    private int x, y;
    
    public Point(int x, int y) {
        this.x = x;
        this.y = y;
    }
    
    public int getX() { return x; }
    public int getY() { return y; }
}

演示文稿制作

使用slide函数创建演示文稿：

{{ slide(
  theme="beamer",
  transition="fade"
) }}

# 第一页幻灯片
这是一张幻灯片内容

{{ slide() }}

# 第二页幻灯片
这是另一张幻灯片

常见问题解决

编译错误排查

1. Java版本问题

   # 检查Java版本
   java -version
   # 确保输出为17.0.0或更高版本
   

2. 依赖缺失

   # 安装Node.js依赖
   cd quarkdown-html
   npm install
   

性能优化建议

• 对于大型文档，使用--incremental选项启用增量编译
• 禁用不必要的预览功能：--no-preview
• 生产环境构建时使用--minify选项压缩输出

常见错误及解决方法

错误信息	原因	解决方案
"Java not found"	Java环境未配置	安装Java 17+并配置环境变量
"PDF generation failed"	Puppeteer未正确安装	运行npm install puppeteer
"Function not found"	函数名称错误	检查函数拼写或导入相应模块

高级配置与自定义

配置文件详解

项目根目录下的quarkdown.config文件示例：

# 全局设置
document:
  title: "我的文档"
  author: "作者姓名"
  language: "zh-CN"

# 输出设置
output:
  format: "html"
  pdf: true
  directory: "./docs"

# 自定义样式
style:
  theme: "paperwhite"
  font:
    family: "Noto Sans"
    size: 12pt

自定义渲染器

# 使用自定义HTML渲染器
quarkdown compile main.qd --renderer ./custom-renderer

扩展与插件

通过插件扩展Quarkdown功能：

# 安装官方插件
quarkdown plugin install @quarkdown/chart