Lazy loaded image
技术分享
QuarkDown
字数 2139阅读时长≈ 6 分钟
2025-6-4
2025-6-4
type
status
date
slug
summary
tags
category
comment
icon
password
GitHub - iamgio/quarkdown: 🪐 Markdown with superpowers — from ideas to presentations, articles and books.
🪐 Markdown with superpowers — from ideas to presentations, articles and books. - iamgio/quarkdown
GitHub - iamgio/quarkdown: 🪐 Markdown with superpowers — from ideas to presentations, articles and books.
https://github.com/iamgio/quarkdown
GitHub - iamgio/quarkdown: 🪐 Markdown with superpowers — from ideas to presentations, articles and books.
今天给大家介绍改变你们文档编写和排版方式的工具——Quarkdown。如果你厌倦了在 Markdown 的简洁性和复杂排版需求之间反复横跳，那么 Quarkdown 绝对值得你花时间了解一下。

📝 Quarkdown：重新定义你的 Markdown 工作流

Quarkdown 是一个基于 Markdown 的现代化排版系统。它的核心设计理念就是通用性 (versatility)。你只需要编写一次内容，就能无缝地将它编译成一本适合打印的精美书籍，或者一个交互式的演示文稿。这一切都通过一个极其强大的、图灵完备的 Markdown 扩展来实现，确保你的思想能够自动流畅地呈现在纸张或屏幕上。
核心链接速览：
  • 代码格式: Ktlint 驱动
  • 代码质量: CodeFactor 认证
下载通道：

目录 (Table of contents)

  1. 关于 Quarkdown
  1. 演示：眼见为实
  1. 输出目标：多样化的文档格式
  1. 横向对比：Quarkdown 的独特优势
  1. 快速上手指南
    1. 安装步骤
    2. 创建你的第一个项目
    3. 编译项目
  1. 示例工程 (Mock Document)
  1. 如何贡献
  1. 致谢赞助者
  1. 设计理念

Quarkdown：到底是什么？

Quarkdown 的诞生，源于对 CommonMark 和 GFM (GitHub Flavored Markdown) 的扩展。它为 Markdown 带来了函数 (functions) 的概念，以及许多其他的语法增强。
看看这个例子，一个简单的函数调用：
是不是感觉 Markdown 的能力瞬间被放大了？
更酷的是，Quarkdown 提供了一个不断扩展的标准库 (standard library)，里面包含了布局构建器、I/O 操作、数学计算、条件语句和循环等强大功能。这意味着，你的可能性是无限的！
还不够？没关系！你完全可以在 Markdown 文件中定义自己的函数和变量，甚至可以创建自己的库，分享给社区使用。
来看一个自定义函数的例子：
编译结果将会是：Hello, world from iamgio!
这种开箱即用的脚本支持，为创建复杂和动态的内容打开了大门，这在纯粹的 Markdown 中是难以想象的。再结合其实时预览和闪电般⚡的编译速度，Quarkdown 能让你事半功倍。
notion image
想要更深入地了解 Quarkdown 的语言特性？务必查看项目的 Wiki。
看看这个用 Quarkdown 制作的演示文稿！
没错，这个演示文稿本身就是用 Quarkdown 构建的。 href="https://github.com/iamgio/quarkdown/blob/main/demo/demo.qmd"

演示：眼见为实，如你所愿的简洁。

Quarkdown 保留了 Markdown 的简洁易读性。你可以像写普通 Markdown 一样快速上手。
 
notion image

...亦能满足你所需的复杂。

当需要更复杂的布局和动态内容时，Quarkdown 的扩展功能又能轻松应对。
notion image

输出目标：多样化的文档格式

Quarkdown 的强大之处在于其多样化的输出能力：
  • HTML
    • ✅ 普通输出 (默认)
    • ✅ 幻灯片 <sup>通过 reveal.js 实现</sup>
    • ✅ 分页文档 (书籍、文章) <sup>通过 paged.js 实现</sup>
      • 注意：分页文档在浏览器中渲染需要一个 Web 服务器。请参考下文的 p 选项。
  • PDF
    • ✅ 所有 HTML 支持的文档类型和特性，在导出为 PDF 时同样支持。
    • 想了解更多？请查阅 Wiki 中的 PDF 导出 页面。
你可以在源文件中通过调用 .doctype 函数 来设定期望的文档类型：
  • .doctype {slides} (用于幻灯片)
  • .doctype {paged} (用于分页文档，如书籍)

📊 横向对比：Quarkdown 的独特优势

为了让大家更直观地理解 Quarkdown 的定位，这里有一个简单的对比表格：
特性
Quarkdown
Markdown (原生)
LaTeX
Typst
AsciiDoc
MDX
简洁易读
:white_check_mark:
:white_check_mark:
:x:
:white_check_mark:
:white_check_mark:
:white_check_mark:
完全文档控制
:white_check_mark:
:x:
:white_check_mark:
:white_check_mark:
:x:
:x:
脚本能力
:white_check_mark:
:x:
部分支持
:white_check_mark:
:x:
:white_check_mark:
书籍/文章导出
:white_check_mark:
:x:
:white_check_mark:
:white_check_mark:
:white_check_mark:
第三方
演示文稿导出
:white_check_mark:
:x:
:white_check_mark:
:white_check_mark:
:white_check_mark:
第三方
学习曲线
:green_circle:
:green_circle:
:red_circle:
:orange_circle:
:green_circle:
:green_circle:
输出目标
HTML, PDF
HTML
PDF, PostScript
PDF
HTML, PDF, ePub
HTML
🟢 = 简单, 🟠 = 中等, 🔴 = 困难
从上面的对比可以看出，Quarkdown 在保持 Markdown 简洁性的同时，提供了类似 LaTeX 的强大排版能力，但语法却友好得多。

快速上手指南

安装步骤

  1. 从 最新稳定版 下载 quarkdown.zip，或者通过 gradlew distZip 命令自行构建。
  1. 解压缩下载的文件。
      • bin 目录包含了可执行脚本。建议将其添加到你的系统 PATH 环境变量中，方便全局调用。
      • lib/qmd 目录包含了可以导入到项目中的 .qmd 库文件。
  1. 确保你的系统安装了 Java 17 或更高版本。Quarkdown 支持所有主流操作系统。

创建你的第一个项目

运行命令 quarkdown create [directory] (例如 quarkdown create my-awesome-book)。这将启动一个基于命令行的项目向导，帮助你快速设置一个新的 Quarkdown 项目，并自动生成包含元数据和初始内容的框架。
更多关于项目创建器的信息，请查看其 Wiki 页面。
当然，你也可以手动创建一个 .qmd 源文件开始你的创作。

编译项目

运行命令 quarkdown c file.qmd (例如 quarkdown c main.qmd) 将会编译给定的文件，并将输出结果保存到指定目录。
如果你的项目由多个源文件组成，那么编译的目标文件必须是根文件，即包含了其他文件的那个文件。 (如何包含其他文件？)
如果你想先熟悉一下 Quarkdown 的语法和功能，可以运行 quarkdown repl 进入交互式的 REPL 模式进行尝试。

编译选项

Quarkdown 提供了一系列命令行选项来控制编译过程：
  • p 或 -preview: 编译后自动重新加载内容。 如果 Web 服务器尚未运行，它会自动启动并在默认浏览器中打开文档。 这对于在浏览器中渲染分页文档是必需的。
  • w 或 -watch: 监视源目录中的文件变化，并在文件更改时自动重新编译。
      • 💡 专业提示: 组合使用 -p -w 可以实现实时预览 (live preview)！
  • -pdf: 生成 PDF 文件。更多详情请参阅 Wiki 的 PDF 导出 页面。
  • o <dir> 或 -output <dir>: 设置输出文件的目录。默认为 ./output。
  • l <dir> 或 -libs <dir>: 设置外部库的加载目录。默认为 <install dir>/lib/qmd。 (这是什么？)
  • r <renderer> 或 -render <renderer>: 设置目标渲染器。默认为 html。可接受的值：
    • html
    • html-pdf (等同于 r html --pdf)
  • -server-port <port>: 可选，自定义本地 Web 服务器的端口。默认为 8089。
  • -pretty: 生成格式化（美化）的输出代码。这对于调试或更容易阅读输出代码很有用，但在生产环境中应禁用，因为结果可能会受到视觉影响。
  • -clean: 在生成新文件之前删除输出目录的内容。这是一个破坏性操作，请谨慎使用。
  • -strict: 如果发生错误，则强制程序退出。在非严格模式下，错误将作为文档中的提示框显示。
  • Dloglevel=<level> (JVM 属性): 设置日志级别。如果设置为 warning 或更高，则不会打印输出内容。

示例工程 (Mock Document)

Mock 是一个用 Quarkdown 编写的综合示例集合，展示了该语言提供的各种视觉元素和关键特性。它是探索和理解 Quarkdown 功能的理想方式——你可以亲自动手实验，并以页面或幻灯片的形式看到具体成果。
  • 该文档的源文件位于 mock 目录中，可以通过 quarkdown c mock/main.qmd -p 命令进行编译和预览。
  • 针对所有可能的主题组合生成的 PDF 文件可在 generated 分支中查看。
上一篇
KINGFALL aistudio 反代
下一篇
Cap：现代极速开源工作量证明CAPTCHA
评论
Loading...
目录