Quarkdown 库libs机制全解析从.include {name}加载到自定义函数库的构建与分发【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdownQuarkdown 的quarkdown-libs模块承载了官方内置的 Quarkdown 函数库库本身以.qd文件编写随发行包自动分发在主文档中通过.include {name}一句即可加载并复用其中的全部函数。本文基于该模块的 README 及其 源码逐层拆解库的编写 → Gradle 分发 → CLI 定位 → 运行时加载 → 主文档调用的完整链路并给出可复制的实战用法。一、什么是 Quarkdown 库在 Quarkdown 中库library是指用 Quarkdown 语言自身编写的一组可复用声明主要是函数定义、变量与本地化表存放于.qd文件中。与普通被包含的文档不同库的定位是符号的复用载体加载库后库内定义的函数即可在主文档中直接调用而不会把库文件中的 Markdown 内容原样混入正文。quarkdown-libs正是承载这类库的 Gradle 子模块。按 settings.gradle.kts 的include(quarkdown-libs)它被纳入整个 Quarkdown 多模块构建。模块的源码结构非常精简quarkdown-libs/src/main/resources/docs.qd面向文档型输出的布局库quarkdown-libs/src/main/resources/paper.qd面向论文型输出的排版库摘要、定义、引理、定理、证明等块。之所以放在src/main/resources下是因为这些.qd文件属于随发行包发布的静态资源会被 Gradle 原样打包进发行物而不是参与编译。二、库的构建与分发Gradle 自动拷贝到lib/qdREADME 明确了分发规则Gradle 构建系统会自动把src/main/resources中的.qd文件拷贝到发行 zip 的lib/qd目录。也就是说当你下载 Quarkdown 发行包或通过distZip任务自行构建时得到的目标目录结构大致如下与 docs/importing-external-libraries.qd 中的 filetree 一致- quarkdown - lib - qd - docs.qd - paper.qd - ... - bin - quarkdown.jar这个固定目录约定是后续一切库加载机制的地基CLI 的默认库目录、.include {name}的查找范围都建立在其上。三、加载库.include {name}与.include {path}的本质区别在主文档中加载一个库使用.include {name}函数name为库文件名不带.qd扩展名。例如加载paper.qd写作.include {paper}见 docs/importing-external-libraries.qd。这里有一个关键的语义区分官方文档特别用 Note 强调docs/importing-external-libraries.qd与.include {path}不同.include {name}这种方式只加载库中声明的符号函数、变量、本地化表等不会把库文件里的 Markdown 内容追加进正文。因此.include {name}是面向函数库的加载方式而.include {path}是面向子文档内容的引入方式。在 docs/paper-library.qd 中可以看到二者的典型组合使用.include {docs} .include {paper}先加载两个库拿到docs与paper提供的全部函数随后文档正文中就能直接调用.abstract、.definition、.proof等库函数。源码印证.include的查找范围从核心实现看.include {name}的可加载库集合与库目录直接相关。在 quarkdown-core/src/main/kotlin/com/quarkdown/core/context/Context.kt 中运行时上下文同时维护两类集合libraries已加载的库用于函数查找loadableLibraries可从库目录即--libs指定的目录按名加载的外部库注释明确说明它们由用户通过.include {name}函数加载。这从数据结构上印证了文档描述的行为.include {name}并不会立刻把文件内容渲染进文档而是把库注册进上下文的加载库集合供后续函数解析使用。四、指定库目录CLI 选项-l/--libs库目录默认为安装目录/lib/qd即上一节提到的分发约定位置。需要覆盖默认值时使用 CLI 的-l或--libs选项README、docs/importing-external-libraries.qd。该选项的声明位于执行命令的实现中quarkdown-cli/src/main/kotlin/com/quarkdown/cli/exec/ExecuteCommand.kt/** * Optional library directory. * If not set, defaults to the qd/ subdirectory of the resolved install directory. */ private val libraryDirectory: File? by option(-l, --libs, help Library directory) .file( mustExist true, canBeFile false, canBeDir true, )从这段源码可以得到几个精确的约束与默认行为默认值未指定时回退到解析出的安装目录下的qd/子目录即lib/qd必须是已存在目录mustExist true表示路径必须真实存在canBeFile false禁止指向文件canBeDir true要求其确为目录别名短选项-l与长选项--libs等价。典型用法示例quarkdown --libs /path/to/my-libs compile main.qd # 等价写法 quarkdown -l /path/to/my-libs compile main.qd通过该选项指向自己的库目录后lib/qd中同名库会被影子化——loadableLibraries将从你指定的目录解析从而实现库的自定义与替换。五、库的实战源码docs.qd与paper.qd仅理解加载机制还不够真正有价值的是官方库本身的写法。quarkdown-libs恰好提供了两份完整的、可运行的库源码是学习如何用 Quarkdown 编写库的最佳教材。5.1docs.qd文档布局库docs.qd 定义了文档型doctype {docs}输出的整体布局核心思路是用变量集中管理可调参数再把这些参数喂给分页边距布局.doctype {docs} .var {pagelistposition} {lefttop} .var {tocposition} {righttop} .include {.pathtoroot/_setup.qd} .pagemargin {.pagelistposition} .navigation role:{pagelist} .include {.pathtoroot/_nav.qd} .pagemargin {.tocposition} .tableofcontents #! .docname值得注意的库编写要点变量即配置项pagelistposition、tocposition以.var声明并给出默认值用户加载库后可通过同名.var覆盖实现零侵入定制相对根目录引用库内通过.pathtoroot前缀引用仓库根目录下的_setup.qd、_nav.qd保证了库被任意位置的项目加载时路径依然正确#!是不转义内容#! .docname表示原样输出当前文档的文档名而不把它当作普通标题文本渲染。5.2paper.qd论文排版库paper.qd 是更复杂的函数库范例提供了abstract、definition、lemma、theorem、proof五个论文常用块其设计分三层非常值得借鉴。第一层多语言本地化表。.localization {paper}定义了中文、英文、法文、德文、意大利文、日文、波兰文、葡萄牙文、俄文、乌克兰文共 10 种语言的术语映射.localization {paper} - Chinese - abstract: 摘要 - definition: 定义 - lemma: 引理 - proof: 证明 - theorem: 定理 - English - abstract: Abstract ...第二层可调变量。库用注释明确标注每个变量的用途并给出默认值!-- Alignment of the Abstract title, relative to its body content -- .var {abstractalignment} {center} !-- The suffix that follows the title of a block, e.g. Definition, Lemma, ... -- .var {paperblocksuffix} {\.} !-- Content at the end of a proof block -- .var {proofend} {∎}三个变量分别控制摘要标题对齐方式默认居中、块标题后缀默认句点、证明块结尾符号默认 ∎。用户只需在加载库后重新.var即可定制例如.abstractalignment {start}会把摘要标题改为左对齐对应文档 docs/paper-library.qd 中的用法。第三层函数定义。五个公开函数共享内部实现避免重复代码。以abstract为例.function {abstract} content: .container padding:{0 1cm} fullwidth:{yes} .align {.abstractalignment} ####! .localize {paper:abstract} .container padding:{2mm 0} .content .whitespace而definition、lemma、theorem、proof四个编号块则通过内部辅助函数namedparagraph与INTERNALtypedparagraph层层复用namedparagraph接收名称、可选的编号标签和内容利用.numbered生成编号并用.concatenate与.isnotempty在有编号时才拼接 .number最后附加paperblocksuffix后缀INTERNALtypedparagraph根据类型名definition等查本地化表得到标题文本并生成复数形式的编号标签definitions、lemmas等再委托给namedparagraph顶层definition/lemma/theorem/proof一行转调INTERNALtypedparagraph其中proof额外在末尾用.align {end}输出proofend符号.function {proof} content: .INTERNALtypedparagraph {proof} {.content} .align {end} .text {.proofend} size:{huge}这种公开函数薄封装 内部辅助函数复用 变量集中配置的三层结构是编写高质量 Quarkdown 库的推荐范式paper.qd本身就是一份完整的参考实现。六、实战在文档中使用paper库下面把整条链路串起来展示一个真实可运行的使用场景完整用法参见 docs/paper-library.qd。6.1 引入库在文档开头加载库.include {paper}若paper.qd不在默认的lib/qd目录则用-l/--libs指向其所在目录后再编译。6.2 使用abstract块库加载后主文档即可直接调用库函数.abstract This is my *abstract*! Here goes the summary of the document.渲染结果即标准的、带居中标题的摘要块对应文档配图 abstract.png。若希望标题左对齐在调用前覆盖变量.abstractalignment {start} .abstract This is my *abstract*! Here goes the summary of the document.6.3 使用编号块definition / lemma / theorem / proofdefinition、lemma、theorem与proof直接以内容参数调用.theorem For any three points, there is a unique line passing through them. .proof Suppose that two distinct lines pass through the same three points...配合 numbering.qd 中定义的编号格式这些块会自动编号——编号格式名使用复数形式definitions、lemmas、theorems、proofsdocs/paper-library.qd。默认情况下块标题带paperblocksuffix默认\.后缀证明块以proofend默认∎收尾块标题文案随文档语言在 10 种本地化表中自动切换。七、小结从quarkdown-libs模块出发可以总结出 Quarkdown 库机制的完整画像环节机制依据编写库即.qd文件置于src/main/resources可包含函数、变量、本地化表quarkdown-libs/src/main/resources分发Gradle 在构建发行 zip 时自动拷贝.qd到lib/qdREADME定位CLI-l/--libs指定库目录默认lib/qd要求目录必须存在ExecuteCommand.kt加载.include {name}只注册符号、不混入 Markdown 内容加载后函数可直接调用Context.kt、importing-external-libraries.qd复用官方库docs.qd与paper.qd即最佳范例公开函数薄封装、内部函数复用、变量集中配置docs.qd、paper.qd对想要一套排版逻辑多处复用的开发者而言最直接的路径是仿照paper.qd编写自己的.qd库 → 通过-l指向该目录 → 在主文档.include {name}后调用库函数。官方更多用法细节可继续阅读 docs/importing-external-libraries.qd 与 docs/paper-library.qd。【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考