Quarkdown 视觉元素实战指南用 Mock 示例文档掌握 Markdown 超能力与主题测试工作流【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdownQuarkdown 是一个带有超能力的 MarkdownMarkdown with superpowers能够把一份.qd源文档编译为论文、演示文稿、网站、书籍与知识库。本文以仓库内 mock/README.md 及其对应的 mock 目录为研究对象全面拆解 Mock 文档——一个由 Quarkdown 语言编写的综合视觉元素集合它既是探索语言核心特性的最佳入口也是验证自定义主题与文档类型的主题测试场。读完本文你将掌握 Mock 文档的编译命令、结构组织方式、主题/文档类型切换机制以及其中覆盖的标题、代码、公式、图表、表格、布局、交叉引用等全部视觉元素的真实写法与源码级支撑。Mock 文档是什么Mock位于 mock 目录是用 Quarkdown 编写的一份示例文档。它并非零散的功能演示而是对 Quarkdown 语言提供的视觉元素visual elements的系统性集合从标题层级、段落排版、列表到代码块、表格、数学公式、Mermaid 图表、引用、提示框、脚注、文件树、图标、分隔线、对齐方式、布局堆栈、交叉引用与参考文献几乎每一类可渲染的视觉元素都在其中有清晰而简洁的示例。这份文档有两个典型用途语言探索通过一份看得见结果的具体文档页面或幻灯片直观理解 Quarkdown 各功能的语法与输出效果主题测试场由于它几乎覆盖了全部视觉元素切换不同主题theme与文档类型doctype后即可快速检验主题的完整性官方在 mock/setup.qd 中明确写道Different themes and document types may be tested by changing the first lines ofmain.qd。编译 Mock 文档CLI 命令与参数README.md 给出了最核心的编译命令quarkdown c mock/main.qd在此基础上可以组合以下参数参数作用-p编译后在浏览器中打开preview-p -w打开浏览器并开启实时重载watch 模式修改源文件自动重新编译刷新--pdf额外导出 PDF这些参数并非 README 的臆造而是有源码依据的在 ExecuteCommand.kt 中可以看到-p/--previewOpen or reload content after compiling与-w/--watchWatch for file changes的真实定义--pdf则在 CompileCommand.kt 中声明为 Export to PDF。也就是说一条quarkdown c mock/main.qd -p -w --pdf即可同时获得浏览器实时预览与 PDF 产物。提示执行编译前需要先进入mock目录cd mock如 mock/setup.qd 中所演示的用法cd mock quarkdown c main.qd -p。Mock 文档的入口结构main.qd编译的入口是 mock/main.qd它本身只有两个开关和一个文件清单结构非常清晰是理解整份文档的钥匙!-- Change here to test a different theme -- .theme {paperwhite} layout:{latex} !-- Change here to paged/slides/plain to test a different document type -- .doctype {paged} .includeall - setup.qd - headings.qd - paragraphs.qd - lists.qd - images.qd - tables.qd - code.qd - textformatting.qd - colorpreview.qd - quotes.qd - boxes.qd - math.qd - footnotes.qd - mermaid.qd - collapsibles.qd - errors.qd - keybindings.qd - filetrees.qd - icons.qd - separators.qd - alignment.qd - stacks.qd - crossreferences.qd - bibliography.qd - localization.qd主题与文档类型开关.theme与.doctype是 Mock 文档最值得实验的两个入口参数.theme {paperwhite} layout:{latex}当前使用paperwhite配色主题并套用latex布局。Quarkdown 的主题系统把配色theme与布局layout解耦仓库中 quarkdown-html/src/main/scss 下的color/如paperwhite.scss、beaver.scss、darko.scss、galactic.scss与layout/如latex.json、latex.scss、minimal.json、beamer.json、focus.json、hyperlegible.json分别对应这两个维度.doctype {paged}文档类型在paged分页适合论文/书籍、slides幻灯片、plain普通网页之间切换。README 提到the form of pages or slides配合 mock/setup.qd 中的.conditionalpagebreak ontype:{slides}自定义函数可以在切换到幻灯片类型时自动插入分页符——这正是一份源文档、多种输出形态的体现。includeall按文件组织的模块化文档.includeall把 25 个.qd文件按顺序引入主文档每个文件负责一个视觉元素类别。这种入口文件 分类模块的组织方式让 Mock 兼具完整覆盖与易维护两大特性也方便读者按需定位某个功能的示例例如只看 mock/code.qd 就能了解代码块的全部能力。全局配置setup.qd 中的文档元数据与页面编排mock/setup.qd 承担了整份文档的前言与全局配置职责包含以下几个值得注意的要点文档元数据.docname {Quarkdown Mock} .docauthor {Giorgio Garofalo} .doclang {English} .pageformat borderbottom:{1px} bordercolor:{grey} .include {paper}.docname、.docauthor、.doclang定义文档名、作者与语言.pageformat为页面添加灰色底边框这是用 Quarkdown 配置页面格式的直观例子.include {paper}引入纸张相关设定。自定义函数条件分页与编号初始化.function {conditionalpagebreak} ontype: .if {.doctype::equals {.ontype}} .function {initnumbering} .resetpagenumber .pagemargin {bottominside} *.lastheading depth:{1}* .pagemargin {bottomoutside} .currentpageconditionalpagebreak接收一个ontype参数当.doctype等于该值时输出分页符——用于在幻灯片类型下自动分页initnumbering重置页码并在页面内侧底边距显示一级标题*.lastheading depth:{1}*、在外侧底边距显示当前页码.currentpage这是 Quarkdown 页面边距内容page margin content能力的典型用法。封面、摘要与目录.footer Quarkdown .center #! .docname .docauthor (c) 2024-2026 --- .abstract Welcome to ... Quarkdowns mock document. ... .whitespace .tableofcontents.center居中显示文档名与作者形成封面.abstract渲染摘要其中说明 Mock 文档定位为detailed reference guide for all the visual elements以及主题测试用途.tableofcontents自动生成目录.whitespace用于留白。这段配置展示了 Quarkdown 在文档级的完整编排能力。视觉元素纵览从源码模块看 Mock 覆盖的功能以下是 Mock 文档中主要的视觉元素模块及其代表语法全部来自mock目录下的真实示例。标题与编号headings.qdmock/headings.qd 展示了六级标题的完整用法#! First-level heading ##! Second-level heading ###! Third-level heading ####! Fourth-level heading #####! Fifth-level heading ######! Sixth-level heading带!的标题会自动编号并在每个标题组之间用分页配合 setup.qd 中定义的initnumbering完成页码重置。读者可以在这里直观比较 6 个层级的字体、间距与编号样式在不同主题下的表现。代码块code.qdmock/code.qd 是代码功能的集中展示核心示例为代码内容来自 mock/code/Wrapper.java.code lang:{java} .read {code/Wrapper.java} .code lang:{java} caption:{A wrapper class} .read {code/Wrapper.java} .code lang:{java} callouts:{ - 4: The constructor. - 8: Getter for the wrapped value. } .read {code/Wrapper.java} .code lang:{java} focus:{4..6} .read {code/Wrapper.java} .code lang:{java} linenumbers:{no} .read {code/Wrapper.java}这段示例覆盖了代码块的五大能力语言高亮lang、标题/题注caption、行标注callouts用行号: 说明的形式为指定行添加注释气泡、聚焦高亮focus:{4..6}突出显示第 46 行、以及关闭行号linenumbers:{no}。.read指令用于把外部文件内容直接嵌入代码块保持源码与示例同步。数学公式math.qdmock/math.qd 展示四类公式写法Let $ F(u) $ be the *Fourier Transform* of the function $ f(x) $. $ F(u) \int_{-\infty}^{\infty} f(x) e^{-2 \pi i u x} dx $ $$$ f(x) \begin{cases} x^2, \text{if } x \ge 0 \\ -x, \text{if } x 0 \end{cases} $$$ $ E mc^2 $ {#_} .texmacro {\binomdef} \frac{#1!}{#2!(#1 - #2)!} $ \binom{n}{k} \binomdef{n}{k} $$ ... $行内公式$ ... $独立成段块级公式$$$ ... $$$多行块级公式此处用\begin{cases}实现分段函数$ E mc^2 $ {#_}带编号的公式.texmacro自定义 TeX 宏随后可直接在公式中调用\binomdef{n}{k}。Mermaid 图表mermaid.qdmock/mermaid.qd 演示了 Quarkdown 对 Mermaid 的深度集成包含XY 图表可用函数生成曲线数据也可用纯数据列表绘制柱状图、类图、时序图、流程图、Git 图和饼图例如.xychart lines:{no} bars:{yes} x:{Months} y:{Revenue} - 5000 - 6000 - 7500 ... .mermaid caption:{Class diagram of a bank system.} .read {mermaid/class.mmd}其中.mermaid支持caption题注并通过.read引入外部.mmd文件对应 mock/mermaid 下的class.mmd、sequence.mmd、flow.mmd、git.mmd、pie.mmd。表格tables.qdmock/tables.qd 展示了 Markdown 表格的三种形态基础表格、带题注表格题注写在表格下方用引号包裹User information.、以及带对齐控制的表格通过表头行的:---:等符号控制列对齐后者常用于展示游戏键位绑定这类信息密集型内容。布局堆栈stacks.qdmock/stacks.qd 是 Quarkdown 布局能力的代表覆盖行、列、网格与容器四种定位技术.row alignment:{center} A B C D .row alignment:{spacearound} A B C D .column A / B / C垂直排列 .grid columns:{3} A B C / D E F三列网格 .row alignment:{spacebetween} gap:{1cm} .container ##! Container 1 .loremipsum .container ##! Container 2 .loremipsum .grid columns:{2} gap:{1cm} .repeat {4} .container ##! Container .1 .loremipsum .clip {circle} .skyimg要点.row/.column通过alignment控制主轴与交叉轴对齐如center、spacearound、spacebetweengap控制间距.grid columns:{2} gap:{1cm}声明两列网格.repeat {4}是 Quarkdown 的循环指令配合容器批量生成内容.var {skyimg}把图片定义为变量以便复用.clip {circle}还能对图片做圆形裁剪。这里使用的示例图片即 mock/images/sky.jpg。交叉引用crossreferences.qdmock/crossreferences.qd 演示了 Quarkdown 强大的引用体系可以为标题、图片、公式、表格等任意元素打上标签{#cross-references}、{#qd-icon}、{#circle-eq}、{#polygons}然后用.ref {label}自动生成指向该元素的交叉引用如图 1公式 (1)表格 2等编号与链接均由引擎自动维护# Cross-references {#cross-references} .ref {cross-references} shows various examples of cross-references. Quarkdown icon {#qd-icon} $ (x - a)^2 (y - b)^2 r^2 $ {#circle-eq} | Polygon | Sides | ... |{#polygons}其他元素Mock 还通过其余模块覆盖了更多视觉元素段落与排版paragraphs.qd、textformatting.qd、列表lists.qd、图片images.qd、颜色预览colorpreview.qd、引用与引语quotes.qd、提示框boxes.qd、脚注footnotes.qd、折叠面板collapsibles.qd、错误提示errors.qd、快捷键展示keybindings.qd、文件树filetrees.qd、图标icons.qd、分隔线separators.qd、对齐alignment.qd、参考文献bibliography.qd与本地化localization.qd。由于 Mock 是按文件分类组织的你可以直接打开对应.qd文件查看该元素最精简的示例再把它复制到自己的文档中改造。源码印证Mock 背后的渲染与样式体系Mock 文档之所以能作为主题测试场底层依赖的是 quarkdown-html 模块的渲染与样式体系quarkdown-html/src/main/scss配色层color/paperwhite.scss当前 Mock 所用、beaver.scss、darko.scss、galactic.scss等定义不同色彩方案布局层layout/latex.scsslatex.json当前布局、minimal、beamer、focus、hyperlegible等定义页面骨架组件层components/_heading.scss、_code.scss、_table.scss、_math.scss、_mermaid.scss、_stack.scss、_footnote.scss、_filetree.scss、_icon.scss等与 Mock 的各个模块一一对应每个.qd示例最终都渲染为这些 SCSS 描述的样式。因此当你在 mock/main.qd 开头把.theme换成darko、把.doctype换成slides再编译实际就是在用同一套视觉元素集合去检验另一套主题/布局/文档类型的表现——这正是主题测试场的含义。实战建议把 Mock 用起来快速体验cd mock quarkdown c main.qd -p -w打开浏览器后随意修改任意.qd模块页面会实时刷新测试主题编辑 mock/main.qd 前两行把paperwhite换为beaver/darko/galactic把latex换为minimal把paged换为slides观察同一份内容在不同外观下的差异作为语法速查表需要某个功能时直接搜索mock目录下对应模块如写代码块前先看 mock/code.qd把.read换成自己的文件即可产出演示文稿或 PDFquarkdown c main.qd --pdf导出 PDF或切到.doctype {slides}后用-p在浏览器中翻页演示——这也是 Mock 文档在 setup.qd 中预置conditionalpagebreak ontype:{slides}的用意所在。总而言之Mock 文档是进入 Quarkdown 世界最直接的一扇门一份源文档、几十个模块、上百个视觉元素编译成页面或幻灯片再通过修改两行配置就能遍历所有主题与文档类型。理解了 mock/README.md、mock/main.qd 与 mock/setup.qd 三者之间的关系你就掌握了 Quarkdown 从语法示例到主题测试的完整工作流。【免费下载链接】quarkdown Markdown with superpowers: from ideas to papers, presentations, websites, books, and knowledge bases.项目地址: https://gitcode.com/GitHub_Trending/qu/quarkdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考