2026/9/14 7:50:04
FEATURED · 精选文章 
Quarkdown 深度指南用 Turing-complete 的 Markdown 排版系统一次编译出论文、演示、网站与知识库【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdownQuarkdown 是一个构建在 CommonMark/GFM 之上的现代 Markdown 排版系统通过引入函数调用function call、自定义函数、变量与标准库把 Markdown 扩展为图灵完备的脚本语言让同一份.qd源文件可以无缝编译为纸质书籍、学术论文、知识库或交互式演示文稿。本文以仓库 README.md 为主线结合quarkdown-cli、quarkdown-core、quarkdown-stdlib等模块源码与官方文档完整讲解其语言特性、输出目标、安装编译流程、CLI 选项与底层编译管线读完即可上手创建并编译自己的第一个 Quarkdown 文档。认识 QuarkdownMarkdown 之上的全能排版系统Quarkdown 的定位非常清晰一个面向通用性versatility的现代 Markdown 排版系统。它让单个项目能够编译为印刷级书籍print-ready book学术论文academic paper知识库knowledge base交互式演示interactive presentation这一切都建立在 README 所说的an incredibly powerful Turing-complete extension of Markdown之上保证你的思路自动流动到纸上ideas flow automatically into paper。从技术实现上看当前仓库是一个Kotlin 编写、Gradle 多模块管理的项目模块清单见 settings.gradle.kts其核心组件包括模块职责quarkdown-core编译器主体词法分析、解析、AST、上下文、流水线pipelinequarkdown-stdlib原生Kotlin 实现标准库布局、I/O、数学、条件语句、循环等quarkdown-htmlHTML 渲染引擎 TypeScript 前端 SCSS 主题quarkdown-html-pdf通过无头 Chromium 浏览器生成 PDFquarkdown-markdown/quarkdown-plaintextMarkdownGFM与纯文本渲染quarkdown-cli命令行工具编译、REPL、项目创建、Web 服务器、LSP、doctorquarkdown-lspLanguage Server提供编辑器语言支持quarkdown-server基于 Ktor 的 Web 服务器承载实时预览与 PDF 生成项目当前版本可在 version.txt 中查看。核心语言特性函数调用带来的无限可能Quarkdown 语言Quarkdown Flavor诞生于 CommonMark 与 GFM 的扩展其中最具标志性的语法扩展是函数functions。README 给出了一个最小示例——在 Markdown 中直接进行函数调用.somefunction {arg1} {arg2} Body argument函数调用分为两种形态详见 CLAUDE.md 与 syntax-of-a-function-call.qd内联函数inline出现在行内例如.myfunction {arg1} param:{arg2}块级函数block独占一段参数写在{...}中缩进的后续内容作为body 参数例如.myfunction {arg1} param:{arg2} arg3一个重要的实现细节是内联参数{...}内会被急切求值而body 参数缩进块会以原始DynamicValue字符串形式延迟求值由消费函数自行决定将其作为纯文本、按 Markdown 解析或两者兼用。这一设计在 CLAUDE.md 的 Inline vs body arguments 一节中有明确说明。标准库开箱即用的超能力函数能力的边界由不断扩充的标准库决定源码位于 quarkdown-stdlib/src/main/kotlin/com/quarkdown/stdlibREADME 明确列出其覆盖范围布局构建器layout buildersI/O数学math条件语句与循环conditional statements and loops从源码目录可以看到标准库按职责拆分为多个 Kotlin 模块Layout.kt布局与容器、Flow.kt流程控制、自定义函数、变量、Math.kt、Mermaid.kt、Document.kt、Collection.kt、Strings.kt、Process.kt、Slides.kt等每个模块通过QuarkdownModule声明暴露函数并统一在 Stdlib.kt 中注册。标准库中的函数还包含一类特殊的primitive functions原语函数它们是支撑 Markdown 原生语法元素的 stdlib 函数例如.heading支撑#、.paragraph支撑段落、.link支撑label、.figure支撑独立图片、.pagebreak支撑、.math支撑$...$。完整的原语列表记录在 docs/primitives.qd。由于 Markdown 语法与原语调用会产生相同的 AST 节点通过.extend {name}扩展某个原语时对应的 Markdown 语法也会同步生效——这为自定义 Markdown 语法行为提供了优雅的入口。自定义函数与变量在 Markdown 中编程还不够用——README 强调你可以完全在 Markdown 内部定义自己的函数和变量甚至可以创作库供所有人使用。README 给出的自定义函数示例.function {greet} to from: **Hello, .to** from .from! .greet {world} from:{iamgio}输出结果为Hello, worldfrom iamgio!从源码层面看用户自定义函数.function定义于Flow模块通过创建一个SimpleFunction并注册到前缀为__func__的Library中与原生函数系统打通.variable定义的变量则实现为带可选参数的函数同时扮演 getter 和 setter变量重赋值时会沿上下文层级向上查找所属上下文详见 CLAUDE.md 的 Custom functions and lambdas 小节。底层编译管线如果你关心原理Quarkdown 编译器被组织为顺序执行的流水线sequential pipeline各阶段以Pipeline-*文档记录于 docs 目录如 pipeline---lexing.qd、pipeline---parsing.qd、pipeline---tree-rewrite.qd、pipeline---rendering.qd 等。函数调用的处理链路大致为词法层FunctionCallWalker提取源文件中的函数调用形成WalkedFunctionCallFunctionCallRefiner将其精炼为FunctionCallNodeAST 节点链式调用.foo {x}::bar {y}会被转换为嵌套树bar(foo(x), y)FunctionCallNodeExpander在FunctionCallExpansionStage阶段驱动展开按名字解析函数 → 执行invoke(bindings, call)返回OutputValue→ 由NodeOutputValueVisitor将输出值映射回 AST 节点展开过程中Context是贯穿全程的关键接口负责携带库、函数、元数据与设置。上下文可以 fork 出子上下文按沙箱级别分为SharedContext双向共享、ScopeContext子上下文不向父上下文回写新声明用于.foreach等 lambda 块与SubdocumentContext仅继承、不回写用于子文档。输出目标与文档类型README 明确列出了 Quarkdown 支持的全部编译目标Targets目标说明HTML - Plain类似 Notion/Obsidian 的连续流式布局适合静态网站与知识管理HTML - Paged基于 paged.js 的分页排版适合论文、文章与书籍HTML - Slides基于 reveal.js 的交互式演示HTML - Docs带侧边栏与目录的文档站点适合 Wiki、技术文档与大型知识库PDFHTML 支持的所有文档类型与特性均可导出为 PDFMarkdown支持 GFM 导出Plain text纯文本导出文档类型无需命令行参数指定而是直接在源文件内调用.doctype函数 设置.doctype {plain}默认.doctype {paged}.doctype {slides}.doctype {docs}在 CLI 中渲染目标通过-r/--render选项指定默认html可接受值包括html、html-pdf等价于-r html --pdf、markdown/gfm、text纯文本完整清单见 docs/cli-options.qd。与 LaTeX / Typst / AsciiDoc / MDX 的对比README 用一个对比表直观呈现了 Quarkdown 在同类 Markdown/排版生态中的定位✓ 表示支持QuarkdownLaTeXTypstAsciiDocMDX简洁可读✓✗✓✓✓完整的文档控制✓✓✓✗✗脚本能力✓部分✓✗✓书籍/论文导出✓✓✓✓第三方演示导出✓✓✓✓第三方静态站点导出✓✗实验性✓✓文档/Wiki 导出✓✗✗✓✓学习曲线低高中低低输出目标HTML, PDF, MD, TXTPDF, PostScriptHTML, PDFHTML, PDF, ePubHTML注完整的文档控制指能够通过语言本身自定义文档及其输出产物的属性README.md 脚注 [^control]。README 还给出了一组LaTeX 与 Quarkdown 的源码对照最能直观说明排版能力等价、但语法更简洁的设计理念\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[width0.3\linewidth]{img1.png} \end{subfigure} \begin{subfigure}[b] \includegraphics[width0.3\linewidth]{img2.png} \end{subfigure} \begin{subfigure}[b] \includegraphics[width0.3\linewidth]{img3.png} \end{subfigure} \end{figure}而同样的内容在 Quarkdown 中写作.tableofcontents # Section ## Subsection 1. **First** item 2. **Second** item .center This text is _centered_. .row alignment:{spacebetween} Image 1 Image 2 Image 3可以看到章节标题直接复用 Markdown 的#语法列表、居中等通过标准库函数.center、.row完成图注与子图布局用函数参数alignment:{spacebetween}表达——这就是熟悉Familiar与优雅Elegant两个特性的来源。编辑器支持良好的编辑器体验是 Quarkdown 的卖点之一README 列出了两类扩展VS Code 官方扩展提供语法高亮、实时预览等能力IntelliJ IDEA 扩展由社区成员维护的非官方插件。配合编译器内置的 Language Serverquarkdown-lsp模块编辑器可以理解函数调用、变量与文档结构从而提供补全、诊断等语言服务。此外README 将Agent-friendly列为项目特性仓库中的 skills/quarkdown/SKILL.md 即为编码 Agent 设计的技能描述文件。快速上手安装、创建与编译安装方式README 为不同平台提供了多种安装路径Linux/macOS —— 官方安装脚本curl -fsSL https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.sh | sudo env PATH$PATH bash以 root 权限运行时脚本会把 Quarkdown 安装到/opt/quarkdown并把包装脚本放到/usr/local/bin/quarkdownPDF 导出所需的浏览器也会被自动安装。Linux/macOS —— Homebrewbrew install quarkdown-labs/quarkdown/quarkdownWindows —— 安装脚本irm https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.ps1 | iexWindows —— Scoopscoop bucket add quarkdown https://github.com/quarkdown-labs/scoop-quarkdown; scoop install quarkdownGitHub Actions可以使用 setup-quarkdown 动作将 Quarkdown 集成进 CI/CD 工作流README 提到 3 分钟内即可搭建好 CD 工作流。手动安装从最新稳定版发布页下载quarkdown.zip并解压或直接在仓库根目录执行./gradlew installDist自行构建构建说明见 CLAUDE.md注意项目规定使用installDist或distZip而非build。可选地把install_dir/bin加入PATH以方便调用。唯一硬性要求仅当需要PDF 导出时才需要安装 Chromium 系浏览器如chrome-headless-shell详见 docs/pdf-export.qd。创建项目quarkdown createquarkdown create [directory]会启动基于提示的项目向导project wizard以最快速度搭建新项目——元数据与初始内容都已就位详见 docs/cli-project-creator.qd。向导会交互式询问以下信息也可以通过命令行选项直接指定避免交互数据附加说明对应选项生成的 Quarkdown 函数项目名称--name.docname作者逗号分隔--authors.docauthors文档类型paged/slides/plain--type.doctype文档语言合法的语言标签或全名--lang.doclang配色主题不提示--color-theme.theme布局主题不提示--layout-theme.theme附加选项还有--empty不生成示例初始内容与--main-file name设置主.qd文件名默认取所在目录名。从模板源码 quarkdown-template/src/main/jte/creator/main.qd.jte 可以看到生成的main.qd会根据上述参数自动填充.docname、.docdescription、.doctype、.doclang、.theme、.dockeywords、.docauthors等元数据声明——这也是理解项目元数据机制的最佳参考。编译与 REPLquarkdown c file.qd编译给定文件并把输出保存到文件中c是compile的别名见 QuarkdownCli.kt 中的aliases()定义。重要约定如果项目由多个源文件组成传入的文件必须是根文件root file——即 include 其他文件的那一个。多文件组织方式见 docs/including-other-quarkdown-files.qd。想快速熟悉语法可以运行quarkdown repl进入交互式 REPL 模式对应的执行策略为 ReplExecutionStrategy.kt。CLI 还提供其他子命令webserver启动本地服务器、create项目创建器、lsp语言服务器与doctor环境诊断。最常用的编译选项README 与 docs/cli-options.qd 共同给出了完整的选项体系预览与监视-p/--preview编译完成后自动重载内容。如果本地 webserver 尚未启动会启动它并在默认浏览器中打开文档paged 文档在浏览器中渲染时此选项为必需。-w/--watch源目录中任何文件变化都会触发重新编译。-b browser/--browser browser指定预览用浏览器默认default可选none、xdg、chrome、chromium、firefox、edge仅 Windows、由BROWSER_NAME环境变量支撑的自定义名称或浏览器可执行文件的完整路径。--server-port port自定义本地 webserver 端口默认8089。组合-p -w即可实现真正的 live preview实时预览。输出控制--pdf同时生成 PDF 文件详见 docs/pdf-export.qd。-o dir/--out dir输出目录默认./quarkdown-output。--out-name name输出资源文件名位于输出目录内默认取文档名.docname特殊字符会被替换为连字符。-r renderer/--render renderer渲染目标默认html。--pipe把渲染结果输出到 stdout 而非文件并抑制其他日志便于管道接续处理。--clean生成前清空输出目录内容破坏性操作源码中还内置了checkCleanSafety安全检查拒绝清理敏感目录见 ExecuteCommand.kt。--nowrap不把渲染结果包裹进完整文档结构HTML 模式下仅输出body内部内容。--pretty生成便于阅读的格式化输出代码适合调试生产环境建议关闭以免视觉效果受影响。--timeout seconds整个执行流水线 导出允许的最大秒数0表示禁用默认 30 秒超时退出码见 ExecuteCommand.kt 中对TIMEOUT_EXIT_CODE的处理。错误处理与媒体--strict任何错误都导致进程退出默认非 strict模式下错误会以盒子形式显示在最终文档中不中断流水线。--no-media-storage关闭媒体存储系统图片等不会拷贝进输出目录的media目录相关节点也不会更新为本地路径参见 docs/media-storage.qd。--forbid-function-overwriting声明同名函数时报错而非静默覆盖参见 docs/declaring-functions.qd。--subdoc-naming strategy子文档输出命名策略默认file-name可选file-name可读但易冲突、collision-proof追加哈希降低冲突、document-name用.docname未设置则回退file-name。-DloglevellevelJVM 属性设置日志级别设为warning及以上时不再打印输出内容。另外还有--pdf-no-sandbox禁用 Chrome 沙箱做 PDF 导出潜在不安全以及--chrome-path path指定 Chromium 系浏览器可执行文件路径支持QUARKDOWN_CHROME_PATH环境变量。权限系统默认安全的脚本执行README 将Secure by default默认安全列为项目核心理念一个限制性的权限系统约束对系统资源的访问。这与 Quarkdown 的脚本能力直接相关——既然文档里可以执行任意代码就必须有边界。权限定义位于 Permission.kt共有五种权限权限名CLI 标识含义project-read读取项目目录内的文件global-read读取整个文件系统的文件含项目目录之外network通过远程资源访问网络如拉取远程媒体native-content使用原生内容特性如嵌入原始 HTMLprocess访问宿主进程环境如读取环境变量默认授予project-read与native-content即Permission.DEFAULT_SET见 Permission.kt其余权限一律不放行。CLI 通过可重复的--allow permission与--deny permission在默认集之上增删权限all可一次性授予全部权限。编译过程中任何未授权操作都会触发MissingPermissionException并中止该操作requirePermission检查逻辑见同文件。Mock 文档一站式体验全部功能README 特别推荐了一个名为Mock的示例项目它是用 Quarkdown 本身编写的、覆盖语言全部可视化元素的综合示例集非常适合探索与理解语言的关键特性——同时能以页面或幻灯片的形式直接看到具体产出甚至可以作为主题测试站点mock/README.md 中的说明。源文件位于仓库的 mock 目录覆盖 headings、lists、tables、math、mermaid、footnotes、cross-references、boxes、collapsibles、filetrees、icons、keybindings、localization 等几乎所有特性编译命令quarkdown c mock/main.qd加-p在浏览器中打开加-p -w启用实时重载加--pdf导出 PDF。实时预览的技术底座Ktor 服务器与双 iframe实时预览并非简单的文件刷新其底层由 quarkdown-server 模块基于 Ktor 的 Web 服务器支撑/preview/path端点结合 CLI 的--preview与--watch选项通过双 iframe 缓冲double iframe buffer机制提供编辑期间的实时预览详见 CLAUDE.md 的 Server 一节。HTML 前端交互与动态特性由 quarkdown-html 模块的 TypeScript 运行时负责样式布局则由 SCSS 文件定义主题分为独立的配色主题与布局主题两维可自由组合例如paperwhite latex、darko minimal、galactic hyperlegible、beaver beamer见 docs/themes.qd。README 还声称官方 Wiki100 子文档约 2 秒即可完成编译实时预览的低延迟正是围绕快速迭代设计的。另外值得一提的是生成的 HTML 文档完全离线可用——所有第三方资源字体、JS 库、CSS、代码高亮、主题都被打包进安装目录并随文档一起拷贝而不是在查看时从 CDN 拉取详见 CLAUDE.md 的 Offline asset bundling 一节。测试体系与质量保障虽然 README 不展开测试细节但作为技术参考值得说明依据 CLAUDE.md 的 Testing 一节项目拥有三层测试体系——单元测试各模块src/test/kotlinKotlin与__tests__TypeScript隔离测试单个组件集成单元测试位于 quarkdown-test/src/test/kotlin把整个编译器作为整体将 Quarkdown 源编译为 HTML 等多种输出端到端测试位于 quarkdown-html/src/test/e2e通过 Playwright 在真实浏览器中验证 HTML 输出、TypeScript 运行时与 CSS 样式的协同CSS 视觉问题只有这种测试才能捕获。每个 E2E 测试目录由main.qd源文档与test-name.spec.ts测试文件组成框架还提供testMatrix让同一断言跨plain/paged/slides等文档类型批量运行。参与贡献与许可证贡献指南见 CONTRIBUTING.md通过 issue 或 pull request 参与面向贡献者的开发与架构说明见 CLAUDE.md其中详细阐述了编译器流水线、节点体系、原语函数、标准库、Quarkdoc 文档生成、HTML 前端与测试规范。许可证Quarkdown 及其各模块默认采用GNU GPLv3见 LICENSE自带独立 LICENSE 文件的模块除外——CLIquarkdown-cli与 Language Serverquarkdown-lsp模块及二进制采用 GNU AGPLv3。结语从 README.md 的定位出发Quarkdown 的核心价值可以概括为三点以 Markdown 的熟悉语法为起点以图灵完备的函数系统提供无限扩展能力以统一的源文件覆盖从论文、演示到网站、知识库的多种输出目标。配合默认安全的权限模型、低延迟的实时预览、离线资源打包与完善的编辑器/LSP 支持它特别适合追求一份源码、多种产物的写作场景。本文涉及的 CLI 完整选项、项目创建器参数与权限体系均可进一步在 docs/cli-options.qd 与 docs/cli-project-creator.qd 中查阅动手从quarkdown create开始你的第一个文档吧。【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Quarkdown 深度指南：用 Turing-complete 的 Markdown 排版系统一次编译出论文、演示、网站与知识库
Quarkdown 深度指南用 Turing-complete 的 Markdown 排版系统一次编译出论文、演示、网站与知识库【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdownQuarkdown 是一个构建在 CommonMark/GFM 之上的现代 Markdown 排版系统通过引入函数调用function call、自定义函数、变量与标准库把 Markdown 扩展为图灵完备的脚本语言让同一份.qd源文件可以无缝编译为纸质书籍、学术论文、知识库或交互式演示文稿。本文以仓库 README.md 为主线结合quarkdown-cli、quarkdown-core、quarkdown-stdlib等模块源码与官方文档完整讲解其语言特性、输出目标、安装编译流程、CLI 选项与底层编译管线读完即可上手创建并编译自己的第一个 Quarkdown 文档。认识 QuarkdownMarkdown 之上的全能排版系统Quarkdown 的定位非常清晰一个面向通用性versatility的现代 Markdown 排版系统。它让单个项目能够编译为印刷级书籍print-ready book学术论文academic paper知识库knowledge base交互式演示interactive presentation这一切都建立在 README 所说的an incredibly powerful Turing-complete extension of Markdown之上保证你的思路自动流动到纸上ideas flow automatically into paper。从技术实现上看当前仓库是一个Kotlin 编写、Gradle 多模块管理的项目模块清单见 settings.gradle.kts其核心组件包括模块职责quarkdown-core编译器主体词法分析、解析、AST、上下文、流水线pipelinequarkdown-stdlib原生Kotlin 实现标准库布局、I/O、数学、条件语句、循环等quarkdown-htmlHTML 渲染引擎 TypeScript 前端 SCSS 主题quarkdown-html-pdf通过无头 Chromium 浏览器生成 PDFquarkdown-markdown/quarkdown-plaintextMarkdownGFM与纯文本渲染quarkdown-cli命令行工具编译、REPL、项目创建、Web 服务器、LSP、doctorquarkdown-lspLanguage Server提供编辑器语言支持quarkdown-server基于 Ktor 的 Web 服务器承载实时预览与 PDF 生成项目当前版本可在 version.txt 中查看。核心语言特性函数调用带来的无限可能Quarkdown 语言Quarkdown Flavor诞生于 CommonMark 与 GFM 的扩展其中最具标志性的语法扩展是函数functions。README 给出了一个最小示例——在 Markdown 中直接进行函数调用.somefunction {arg1} {arg2} Body argument函数调用分为两种形态详见 CLAUDE.md 与 syntax-of-a-function-call.qd内联函数inline出现在行内例如.myfunction {arg1} param:{arg2}块级函数block独占一段参数写在{...}中缩进的后续内容作为body 参数例如.myfunction {arg1} param:{arg2} arg3一个重要的实现细节是内联参数{...}内会被急切求值而body 参数缩进块会以原始DynamicValue字符串形式延迟求值由消费函数自行决定将其作为纯文本、按 Markdown 解析或两者兼用。这一设计在 CLAUDE.md 的 Inline vs body arguments 一节中有明确说明。标准库开箱即用的超能力函数能力的边界由不断扩充的标准库决定源码位于 quarkdown-stdlib/src/main/kotlin/com/quarkdown/stdlibREADME 明确列出其覆盖范围布局构建器layout buildersI/O数学math条件语句与循环conditional statements and loops从源码目录可以看到标准库按职责拆分为多个 Kotlin 模块Layout.kt布局与容器、Flow.kt流程控制、自定义函数、变量、Math.kt、Mermaid.kt、Document.kt、Collection.kt、Strings.kt、Process.kt、Slides.kt等每个模块通过QuarkdownModule声明暴露函数并统一在 Stdlib.kt 中注册。标准库中的函数还包含一类特殊的primitive functions原语函数它们是支撑 Markdown 原生语法元素的 stdlib 函数例如.heading支撑#、.paragraph支撑段落、.link支撑label、.figure支撑独立图片、.pagebreak支撑、.math支撑$...$。完整的原语列表记录在 docs/primitives.qd。由于 Markdown 语法与原语调用会产生相同的 AST 节点通过.extend {name}扩展某个原语时对应的 Markdown 语法也会同步生效——这为自定义 Markdown 语法行为提供了优雅的入口。自定义函数与变量在 Markdown 中编程还不够用——README 强调你可以完全在 Markdown 内部定义自己的函数和变量甚至可以创作库供所有人使用。README 给出的自定义函数示例.function {greet} to from: **Hello, .to** from .from! .greet {world} from:{iamgio}输出结果为Hello, worldfrom iamgio!从源码层面看用户自定义函数.function定义于Flow模块通过创建一个SimpleFunction并注册到前缀为__func__的Library中与原生函数系统打通.variable定义的变量则实现为带可选参数的函数同时扮演 getter 和 setter变量重赋值时会沿上下文层级向上查找所属上下文详见 CLAUDE.md 的 Custom functions and lambdas 小节。底层编译管线如果你关心原理Quarkdown 编译器被组织为顺序执行的流水线sequential pipeline各阶段以Pipeline-*文档记录于 docs 目录如 pipeline---lexing.qd、pipeline---parsing.qd、pipeline---tree-rewrite.qd、pipeline---rendering.qd 等。函数调用的处理链路大致为词法层FunctionCallWalker提取源文件中的函数调用形成WalkedFunctionCallFunctionCallRefiner将其精炼为FunctionCallNodeAST 节点链式调用.foo {x}::bar {y}会被转换为嵌套树bar(foo(x), y)FunctionCallNodeExpander在FunctionCallExpansionStage阶段驱动展开按名字解析函数 → 执行invoke(bindings, call)返回OutputValue→ 由NodeOutputValueVisitor将输出值映射回 AST 节点展开过程中Context是贯穿全程的关键接口负责携带库、函数、元数据与设置。上下文可以 fork 出子上下文按沙箱级别分为SharedContext双向共享、ScopeContext子上下文不向父上下文回写新声明用于.foreach等 lambda 块与SubdocumentContext仅继承、不回写用于子文档。输出目标与文档类型README 明确列出了 Quarkdown 支持的全部编译目标Targets目标说明HTML - Plain类似 Notion/Obsidian 的连续流式布局适合静态网站与知识管理HTML - Paged基于 paged.js 的分页排版适合论文、文章与书籍HTML - Slides基于 reveal.js 的交互式演示HTML - Docs带侧边栏与目录的文档站点适合 Wiki、技术文档与大型知识库PDFHTML 支持的所有文档类型与特性均可导出为 PDFMarkdown支持 GFM 导出Plain text纯文本导出文档类型无需命令行参数指定而是直接在源文件内调用.doctype函数 设置.doctype {plain}默认.doctype {paged}.doctype {slides}.doctype {docs}在 CLI 中渲染目标通过-r/--render选项指定默认html可接受值包括html、html-pdf等价于-r html --pdf、markdown/gfm、text纯文本完整清单见 docs/cli-options.qd。与 LaTeX / Typst / AsciiDoc / MDX 的对比README 用一个对比表直观呈现了 Quarkdown 在同类 Markdown/排版生态中的定位✓ 表示支持QuarkdownLaTeXTypstAsciiDocMDX简洁可读✓✗✓✓✓完整的文档控制✓✓✓✗✗脚本能力✓部分✓✗✓书籍/论文导出✓✓✓✓第三方演示导出✓✓✓✓第三方静态站点导出✓✗实验性✓✓文档/Wiki 导出✓✗✗✓✓学习曲线低高中低低输出目标HTML, PDF, MD, TXTPDF, PostScriptHTML, PDFHTML, PDF, ePubHTML注完整的文档控制指能够通过语言本身自定义文档及其输出产物的属性README.md 脚注 [^control]。README 还给出了一组LaTeX 与 Quarkdown 的源码对照最能直观说明排版能力等价、但语法更简洁的设计理念\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[width0.3\linewidth]{img1.png} \end{subfigure} \begin{subfigure}[b] \includegraphics[width0.3\linewidth]{img2.png} \end{subfigure} \begin{subfigure}[b] \includegraphics[width0.3\linewidth]{img3.png} \end{subfigure} \end{figure}而同样的内容在 Quarkdown 中写作.tableofcontents # Section ## Subsection 1. **First** item 2. **Second** item .center This text is _centered_. .row alignment:{spacebetween} Image 1 Image 2 Image 3可以看到章节标题直接复用 Markdown 的#语法列表、居中等通过标准库函数.center、.row完成图注与子图布局用函数参数alignment:{spacebetween}表达——这就是熟悉Familiar与优雅Elegant两个特性的来源。编辑器支持良好的编辑器体验是 Quarkdown 的卖点之一README 列出了两类扩展VS Code 官方扩展提供语法高亮、实时预览等能力IntelliJ IDEA 扩展由社区成员维护的非官方插件。配合编译器内置的 Language Serverquarkdown-lsp模块编辑器可以理解函数调用、变量与文档结构从而提供补全、诊断等语言服务。此外README 将Agent-friendly列为项目特性仓库中的 skills/quarkdown/SKILL.md 即为编码 Agent 设计的技能描述文件。快速上手安装、创建与编译安装方式README 为不同平台提供了多种安装路径Linux/macOS —— 官方安装脚本curl -fsSL https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.sh | sudo env PATH$PATH bash以 root 权限运行时脚本会把 Quarkdown 安装到/opt/quarkdown并把包装脚本放到/usr/local/bin/quarkdownPDF 导出所需的浏览器也会被自动安装。Linux/macOS —— Homebrewbrew install quarkdown-labs/quarkdown/quarkdownWindows —— 安装脚本irm https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.ps1 | iexWindows —— Scoopscoop bucket add quarkdown https://github.com/quarkdown-labs/scoop-quarkdown; scoop install quarkdownGitHub Actions可以使用 setup-quarkdown 动作将 Quarkdown 集成进 CI/CD 工作流README 提到 3 分钟内即可搭建好 CD 工作流。手动安装从最新稳定版发布页下载quarkdown.zip并解压或直接在仓库根目录执行./gradlew installDist自行构建构建说明见 CLAUDE.md注意项目规定使用installDist或distZip而非build。可选地把install_dir/bin加入PATH以方便调用。唯一硬性要求仅当需要PDF 导出时才需要安装 Chromium 系浏览器如chrome-headless-shell详见 docs/pdf-export.qd。创建项目quarkdown createquarkdown create [directory]会启动基于提示的项目向导project wizard以最快速度搭建新项目——元数据与初始内容都已就位详见 docs/cli-project-creator.qd。向导会交互式询问以下信息也可以通过命令行选项直接指定避免交互数据附加说明对应选项生成的 Quarkdown 函数项目名称--name.docname作者逗号分隔--authors.docauthors文档类型paged/slides/plain--type.doctype文档语言合法的语言标签或全名--lang.doclang配色主题不提示--color-theme.theme布局主题不提示--layout-theme.theme附加选项还有--empty不生成示例初始内容与--main-file name设置主.qd文件名默认取所在目录名。从模板源码 quarkdown-template/src/main/jte/creator/main.qd.jte 可以看到生成的main.qd会根据上述参数自动填充.docname、.docdescription、.doctype、.doclang、.theme、.dockeywords、.docauthors等元数据声明——这也是理解项目元数据机制的最佳参考。编译与 REPLquarkdown c file.qd编译给定文件并把输出保存到文件中c是compile的别名见 QuarkdownCli.kt 中的aliases()定义。重要约定如果项目由多个源文件组成传入的文件必须是根文件root file——即 include 其他文件的那一个。多文件组织方式见 docs/including-other-quarkdown-files.qd。想快速熟悉语法可以运行quarkdown repl进入交互式 REPL 模式对应的执行策略为 ReplExecutionStrategy.kt。CLI 还提供其他子命令webserver启动本地服务器、create项目创建器、lsp语言服务器与doctor环境诊断。最常用的编译选项README 与 docs/cli-options.qd 共同给出了完整的选项体系预览与监视-p/--preview编译完成后自动重载内容。如果本地 webserver 尚未启动会启动它并在默认浏览器中打开文档paged 文档在浏览器中渲染时此选项为必需。-w/--watch源目录中任何文件变化都会触发重新编译。-b browser/--browser browser指定预览用浏览器默认default可选none、xdg、chrome、chromium、firefox、edge仅 Windows、由BROWSER_NAME环境变量支撑的自定义名称或浏览器可执行文件的完整路径。--server-port port自定义本地 webserver 端口默认8089。组合-p -w即可实现真正的 live preview实时预览。输出控制--pdf同时生成 PDF 文件详见 docs/pdf-export.qd。-o dir/--out dir输出目录默认./quarkdown-output。--out-name name输出资源文件名位于输出目录内默认取文档名.docname特殊字符会被替换为连字符。-r renderer/--render renderer渲染目标默认html。--pipe把渲染结果输出到 stdout 而非文件并抑制其他日志便于管道接续处理。--clean生成前清空输出目录内容破坏性操作源码中还内置了checkCleanSafety安全检查拒绝清理敏感目录见 ExecuteCommand.kt。--nowrap不把渲染结果包裹进完整文档结构HTML 模式下仅输出body内部内容。--pretty生成便于阅读的格式化输出代码适合调试生产环境建议关闭以免视觉效果受影响。--timeout seconds整个执行流水线 导出允许的最大秒数0表示禁用默认 30 秒超时退出码见 ExecuteCommand.kt 中对TIMEOUT_EXIT_CODE的处理。错误处理与媒体--strict任何错误都导致进程退出默认非 strict模式下错误会以盒子形式显示在最终文档中不中断流水线。--no-media-storage关闭媒体存储系统图片等不会拷贝进输出目录的media目录相关节点也不会更新为本地路径参见 docs/media-storage.qd。--forbid-function-overwriting声明同名函数时报错而非静默覆盖参见 docs/declaring-functions.qd。--subdoc-naming strategy子文档输出命名策略默认file-name可选file-name可读但易冲突、collision-proof追加哈希降低冲突、document-name用.docname未设置则回退file-name。-DloglevellevelJVM 属性设置日志级别设为warning及以上时不再打印输出内容。另外还有--pdf-no-sandbox禁用 Chrome 沙箱做 PDF 导出潜在不安全以及--chrome-path path指定 Chromium 系浏览器可执行文件路径支持QUARKDOWN_CHROME_PATH环境变量。权限系统默认安全的脚本执行README 将Secure by default默认安全列为项目核心理念一个限制性的权限系统约束对系统资源的访问。这与 Quarkdown 的脚本能力直接相关——既然文档里可以执行任意代码就必须有边界。权限定义位于 Permission.kt共有五种权限权限名CLI 标识含义project-read读取项目目录内的文件global-read读取整个文件系统的文件含项目目录之外network通过远程资源访问网络如拉取远程媒体native-content使用原生内容特性如嵌入原始 HTMLprocess访问宿主进程环境如读取环境变量默认授予project-read与native-content即Permission.DEFAULT_SET见 Permission.kt其余权限一律不放行。CLI 通过可重复的--allow permission与--deny permission在默认集之上增删权限all可一次性授予全部权限。编译过程中任何未授权操作都会触发MissingPermissionException并中止该操作requirePermission检查逻辑见同文件。Mock 文档一站式体验全部功能README 特别推荐了一个名为Mock的示例项目它是用 Quarkdown 本身编写的、覆盖语言全部可视化元素的综合示例集非常适合探索与理解语言的关键特性——同时能以页面或幻灯片的形式直接看到具体产出甚至可以作为主题测试站点mock/README.md 中的说明。源文件位于仓库的 mock 目录覆盖 headings、lists、tables、math、mermaid、footnotes、cross-references、boxes、collapsibles、filetrees、icons、keybindings、localization 等几乎所有特性编译命令quarkdown c mock/main.qd加-p在浏览器中打开加-p -w启用实时重载加--pdf导出 PDF。实时预览的技术底座Ktor 服务器与双 iframe实时预览并非简单的文件刷新其底层由 quarkdown-server 模块基于 Ktor 的 Web 服务器支撑/preview/path端点结合 CLI 的--preview与--watch选项通过双 iframe 缓冲double iframe buffer机制提供编辑期间的实时预览详见 CLAUDE.md 的 Server 一节。HTML 前端交互与动态特性由 quarkdown-html 模块的 TypeScript 运行时负责样式布局则由 SCSS 文件定义主题分为独立的配色主题与布局主题两维可自由组合例如paperwhite latex、darko minimal、galactic hyperlegible、beaver beamer见 docs/themes.qd。README 还声称官方 Wiki100 子文档约 2 秒即可完成编译实时预览的低延迟正是围绕快速迭代设计的。另外值得一提的是生成的 HTML 文档完全离线可用——所有第三方资源字体、JS 库、CSS、代码高亮、主题都被打包进安装目录并随文档一起拷贝而不是在查看时从 CDN 拉取详见 CLAUDE.md 的 Offline asset bundling 一节。测试体系与质量保障虽然 README 不展开测试细节但作为技术参考值得说明依据 CLAUDE.md 的 Testing 一节项目拥有三层测试体系——单元测试各模块src/test/kotlinKotlin与__tests__TypeScript隔离测试单个组件集成单元测试位于 quarkdown-test/src/test/kotlin把整个编译器作为整体将 Quarkdown 源编译为 HTML 等多种输出端到端测试位于 quarkdown-html/src/test/e2e通过 Playwright 在真实浏览器中验证 HTML 输出、TypeScript 运行时与 CSS 样式的协同CSS 视觉问题只有这种测试才能捕获。每个 E2E 测试目录由main.qd源文档与test-name.spec.ts测试文件组成框架还提供testMatrix让同一断言跨plain/paged/slides等文档类型批量运行。参与贡献与许可证贡献指南见 CONTRIBUTING.md通过 issue 或 pull request 参与面向贡献者的开发与架构说明见 CLAUDE.md其中详细阐述了编译器流水线、节点体系、原语函数、标准库、Quarkdoc 文档生成、HTML 前端与测试规范。许可证Quarkdown 及其各模块默认采用GNU GPLv3见 LICENSE自带独立 LICENSE 文件的模块除外——CLIquarkdown-cli与 Language Serverquarkdown-lsp模块及二进制采用 GNU AGPLv3。结语从 README.md 的定位出发Quarkdown 的核心价值可以概括为三点以 Markdown 的熟悉语法为起点以图灵完备的函数系统提供无限扩展能力以统一的源文件覆盖从论文、演示到网站、知识库的多种输出目标。配合默认安全的权限模型、低延迟的实时预览、离线资源打包与完善的编辑器/LSP 支持它特别适合追求一份源码、多种产物的写作场景。本文涉及的 CLI 完整选项、项目创建器参数与权限体系均可进一步在 docs/cli-options.qd 与 docs/cli-project-creator.qd 中查阅动手从quarkdown create开始你的第一个文档吧。【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
原理与应用实践)
