Quarkdown：基于Markdown的动态排版工具

Quarkdown 是一个基于 Markdown 的现代化排版工具，扩展了 CommonMark 和 GitHub Flavored Markdown（GFM）的功能。它通过引入函数、变量和标准库，让用户能创建动态内容，轻松生成交互式演示文稿、网页或打印就绪的书籍。Quarkdown 支持快速编译和实时预览，适合开发者、写作者和设计师。用户可以用简单的 Markdown 语法实现复杂排版，同时支持 PDF 输出和自定义库。项目开源，文档齐全，社区活跃，适合需要高效创作复杂文档的用户。

功能列表

• 动态内容生成：支持函数和变量，创建交互式内容，如动态问候语或条件语句。
• 实时预览：通过 -p 和 -w 命令，自动刷新内容并在浏览器中实时查看。
• PDF 输出：使用 --pdf 命令将文档编译为打印就绪的 PDF 文件。
• 标准库支持：提供布局构建、数学运算、条件语句和循环等功能。
• 自定义函数：用户可定义自己的函数和变量，扩展 Markdown 功能。
• 多文件编译：支持多文件项目，指定根文件即可编译整个项目。
• 交互式 REPL 模式：通过 quarkdown repl 进入交互模式，快速测试代码。
• 外部库加载：通过 -l 或 --libs 加载外部库，增强功能。
• 多种渲染目标：支持 HTML 和其他渲染格式，灵活输出内容。

使用帮助

安装流程

Quarkdown 是一个命令行工具，安装过程简单。以下是详细步骤：

1. 确保环境：Quarkdown 需要安装 Node.js（推荐最新 LTS 版本）。在终端运行 node -v 检查是否已安装 Node.js。
2. 克隆仓库：访问 GitHub 仓库（https://github.com/iamgio/quarkdown），运行以下命令克隆项目：

   git clone https://github.com/iamgio/quarkdown.git
   

3. 安装依赖：进入项目目录，运行：

   cd quarkdown
   npm install
   

4. 全局安装：若希望在全局使用 Quarkdown 命令，运行：

   npm install -g .
   

5. 验证安装：运行 quarkdown --version 检查是否成功安装。

使用方法

Quarkdown 通过命令行操作，核心命令是 quarkdown c <file.qmd>，用于编译 Markdown 文件。以下是主要功能和操作流程：

1. 编译单个文件

要编译一个 Quarkdown 文件（如 example.qmd），运行：

quarkdown c example.qmd

输出文件默认保存在 ./output 目录。若需指定输出目录，使用 -o：

quarkdown c example.qmd -o ./my-output

2. 实时预览

Quarkdown 支持实时预览，适合快速调整内容。运行以下命令启动预览：

quarkdown c example.qmd -p -w

• -p：启动浏览器预览，自动打开默认浏览器。
• -w：监控文件变化，自动重新编译。
  结合 -p -w 可实现保存后即时刷新预览效果，适合动态调整演示文稿或网页。

3. 生成 PDF

要将文档导出为 PDF，添加 --pdf 参数：

quarkdown c example.qmd --pdf

生成的 PDF 文件保存在输出目录，适合打印书籍或分享文档。更多 PDF 设置参考官方文档（quarkdown.com/docs）。

4. 交互式 REPL 模式

想快速测试 Quarkdown 语法？使用 REPL 模式：

quarkdown repl

进入交互式环境后，可直接输入 Quarkdown 代码，如：

.function {greet} to from: **Hello, .to** from .from!
.greet {world} from:{iamgio}

输出结果为：Hello, world from iamgio!。此模式适合学习和调试。

5. 使用标准库和自定义函数

Quarkdown 提供丰富的标准库，支持布局、数学运算和条件语句。例如，创建一个动态列表：

.for {item} in {apple, banana, orange}:
- .item
.endfor

输出为：

• apple
• banana
• orange

用户还可定义自定义函数。例如：

.function {welcome} name: Welcome, .name, to Quarkdown!
.welcome {Alice}

输出：Welcome, Alice, to Quarkdown!。自定义函数可保存为库，供其他项目复用。

6. 多文件项目

对于复杂项目，Quarkdown 支持多文件编译。确保指定根文件（如 main.qmd），它会自动包含其他文件：

quarkdown c mock/main.qmd -p

示例项目 mock 包含多种视觉元素，适合学习 Quarkdown 的功能。

7. 加载外部库

若需使用外部库，指定库目录：

quarkdown c example.qmd -l ./my-libs

默认库路径为 <install dir>/lib/qmd。用户可创建并分享自己的库。

8. 渲染目标设置

Quarkdown 默认输出 HTML，但可通过 -r 指定其他渲染目标：

quarkdown c example.qmd -r html

更多渲染选项参考官方文档。

特色功能操作

• 动态内容：Quarkdown 的核心特色是支持函数和变量。用户可通过 .function 定义函数，结合标准库的循环和条件语句，生成动态内容。例如，条件语句用法：

  .if {condition} == true:
  Content displayed if true
  .else:
  Content displayed if false
  .endif
  

• Mock 示例：Quarkdown 提供 mock 示例项目，展示视觉元素和排版效果。运行 quarkdown c mock/main.qmd -p 查看完整演示。
• 社区贡献：用户可通过 GitHub 提交 issues 或 pull requests，参与功能开发。参考 CONTRIBUTING.md 获取指南。

更多功能和详细文档可在 quarkdown.com/docs 查看。

应用场景

1. 技术文档编写
   开发者可用 Quarkdown 编写动态技术文档。通过函数和变量，生成包含条件逻辑或循环的复杂文档。例如，自动生成 API 文档的表格或列表。
2. 交互式演示文稿
   教育工作者或讲师可使用 Quarkdown 创建交互式幻灯片。结合实时预览，快速调整内容，适合课堂或会议展示。
3. 书籍排版
   作者可将 Markdown 文件编译为打印就绪的 PDF 书籍，适合自出版或技术手册制作。PDF 输出支持多种主题。
4. 个人博客
   博客作者可利用 Quarkdown 的动态功能，创建包含交互元素的网页，如动态问候语或个性化内容。

QA

1. Quarkdown 支持哪些 Markdown 标准？
   Quarkdown 基于 CommonMark 和 GitHub Flavored Markdown（GFM），并扩展了函数、变量和标准库功能。标准 Markdown 语法完全兼容。
2. 如何调试 Quarkdown 代码？
   使用 quarkdown repl 进入交互模式，逐行测试代码。错误信息会显示在终端，方便定位问题。
3. 是否需要编程经验？
   不需要。Quarkdown 的语法简单，熟悉 Markdown 的用户可快速上手。标准库和文档提供足够支持。
4. 如何导出不同格式？
   默认输出 HTML，使用 --pdf 可生成 PDF。其他渲染格式通过 -r 指定，详见文档。
5. 如何参与社区？
   访问 GitHub 仓库，提交 issues 或 pull requests。查看 CONTRIBUTING.md 获取贡献指南。