关于

Quarkdown 是一个基于现代 Markdown 的排版系统，其核心理念是 多功能性 —— 你可以轻松地将一个项目编译成可打印的书籍或交互式演示文稿。

这一切得益于对 Markdown 的强大扩展，它是图灵完备的，能够让你的想法自动转化为纸面内容。

Quarkdown 起源于对 CommonMark 和 GFM 的扩展，其自定义语法（Quarkdown Flavor）为 Markdown 带来了函数功能，以及许多其他语法扩展。

例如，这是一个函数调用：
.somefunction {arg1} {arg2}
     Body argument

由于不断扩展的标准库，你可以使用布局构建器、I/O、数学、条件语句和循环等功能，实现无限可能。

还不够？ 你还可以在 Markdown 中定义自己的函数和变量，甚至创建面向所有人的共享库。

例如：

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

输出结果：Hello, world from iamgio!

这种内建的脚本支持让你可以实现原始 Markdown 所无法企及的复杂动态内容。

再结合实时预览和 \:zap: 超快的编译速度，Quarkdown 让你高效完成工作。

Live preview

详细了解语言和功能，请访问 wiki。

简单如你所想…

Paper code demo

灵感来源：来自超大质量黑洞的 X 射线闪光神秘加速

…复杂如你所需。

Chart code demo

支持的输出目标

HTML
- ✅ 普通输出（默认）
- ✅ 幻灯片 ^{基于 reveal.js}
- ✅ 分页文档（书籍、文章）^{基于 paged.js} 分页文档需在浏览器中通过本地服务器渲染，详见下文 -p 参数。
PDF
- ✅ 所有 HTML 支持的文档类型和功能，在导出为 PDF 时同样可用。
- 请参阅 Wiki 中的 PDF 导出指南。

你可以通过在源文件中调用 .doctype 函数来设置目标文档类型：

.doctype {slides}
.doctype {paged}

对比表

	Quarkdown	Markdown	LaTeX	Typst	AsciiDoc	MDX
简洁易读	✅	✅	❌	✅	✅	✅
完整文档控制	✅	❌	✅	✅	❌	❌
脚本功能	✅	❌	部分支持	✅	❌	✅
支持书籍/文章导出	✅	❌	✅	✅	✅	第三方实现
支持演示文稿导出	✅	❌	✅	✅	✅	第三方实现
学习曲线	🟢	🟢	🔴	🟠	🟢	🟢
输出目标	HTML, PDF	HTML	PDF, PostScript	PDF	HTML, PDF, ePub	HTML

示例对比

LaTeX Quarkdown

latex \tableofcontents \section{Section} \subsection{Subsection} \begin{enumerate} \item \textbf{First} item \item \textbf{Second} item \end{itemize} \begin{center} This text is \textit{centered}. \end{center} \begin{figure}[!h] \centering \begin{subfigure}[b] \includegraphics[width=0.3\linewidth]{img1.png} \end{subfigure} \begin{subfigure}[b] \includegraphics[width=0.3\linewidth]{img2.png} \end{subfigure} \begin{subfigure}[b] \includegraphics[width=0.3\linewidth]{img3.png} \end{subfigure} \end{figure} markdown .tableofcontents # Section ## Subsection 1. **First** item 2. **Second** item .center This text is _centered_. .row alignment:{spacebetween} ![Image 1](img1.png) ![Image 2](img2.png) ![Image 3](img3.png)

LaTeX	Quarkdown
latex \tableofcontents \section{Section} \subsection{Subsection} \begin{enumerate} \item \textbf{First} item \item \textbf{Second} item \end{itemize} \begin{center} This text is \textit{centered}. \end{center} \begin{figure}[!h] \centering \begin{subfigure}[b] \includegraphics[width=0.3\linewidth]{img1.png} \end{subfigure} \begin{subfigure}[b] \includegraphics[width=0.3\linewidth]{img2.png} \end{subfigure} \begin{subfigure}[b] \includegraphics[width=0.3\linewidth]{img3.png} \end{subfigure} \end{figure}	`markdown .tableofcontents # Section ## Subsection 1. First item 2. Second item .center This text is _centered_. .row alignment:{spacebetween} ![Image 1](img1.png) ![Image 2](img2.png) ![Image 3](img3.png)`

入门指南

安装

从最新稳定版下载 quarkdown.zip，或使用 gradlew distZip 自行构建并解压。

bin 目录包含可执行脚本。你可以将其添加到系统 PATH，便于使用。
lib/qmd 目录包含可导入项目的 .qmd 库。

需要安装 Java 17 或更高版本，支持所有主流操作系统。

创建项目

运行 quarkdown create [directory] 命令将启动交互式项目向导，快速搭建包含元数据和初始内容的 Quarkdown 项目。

查看项目创建器 wiki 页面获取更多信息。

当然你也可以手动创建 .qmd 源文件从零开始。

编译

运行 quarkdown c file.qmd 将编译指定文件并输出结果。

如果项目包含多个源文件，请使用包含其他文件的主文件作为编译目标。
👉 如何包含其他文件？

你也可以通过 quarkdown repl 启动交互模式熟悉语法。

可用参数选项

-p 或 --preview：启用编译后自动预览。如未运行 webserver，将自动启动并打开浏览器。
（分页文档需启用预览模式）
-w 或 --watch：源文件变动时自动重新编译。

💡 建议使用 -p -w 搭配实现实时预览！

--pdf：导出 PDF。详见 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>：自定义本地 webserver 端口，默认是 8089。
--pretty：输出更美观的 HTML 代码，适合调试，但建议生产环境关闭。
--clean：编译前清空输出目录（危险操作）。
--strict：出错时强制退出程序。默认会将错误显示为文档内的错误框。
--no-media-storage：禁用媒体存储系统。(?)
-Dloglevel=<level>（JVM 参数）：设置日志等级，如设置为 warning 或更高则不显示输出内容。

Mock 示例文档

Mock document demo

Mock 是一个用 Quarkdown 编写的示例文档，展示了该语言的各种视觉元素，非常适合边玩边学，探索其核心特性，生成幻灯片或页面等真实成果。

源码位于 mock 目录，可通过 quarkdown c mock/main.qmd -p 编译。
所有主题组合的 PDF 输出可在 generated 分支查看。

概念设计

Quarkdown 的 logo 灵感来自原始 Markdown 图标，象征着 Quarkdown 的完整性、多功能性和高度可定制性 —— 这点通过围绕球体旋转的箭头得到体现。

看上去像是行星的这个图标，其实象征的是一种基本粒子 —— 夸克，更具体地说是 down 夸克（down quark），它是构成物质的基本单位之一，轻巧却强大。

而这正是 Quarkdown 的理念核心。