Installation

Welcome to Quarkdown! This is the starting point of your document.

To compile this document, please cd to this file’s parent directory and run:
quarkdown c quarkdown_guide.qd
To enable live preview, run:
quarkdown c quarkdown_guide.qd -p -w

For further information and guides, please check out the official wiki.

Step by Step

软件链接: https://github.com/iamgio/quarkdown.git Clone wiki locally ：https://github.com/iamgio/quarkdown.wiki.git

安装Scoop

打开powershell（不能用管理员模式），运行一下命令使得默认策略为自动同意：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

下载安装脚本：

irm get.scoop.sh -outfile 'Install.ps1'

查看可配置参数：

.\install.ps1 -?

将scoop安装到自定义目录：

.\install.ps1 -ScoopDir 'D:\Applications\ScoopApps' -ScoopGlobalDir 'D:\Applications\ScoopApps' -NoProxy

-ScoopDir: 用户级软件路径 -ScoopGlobalDir: 全局软件路径（需管理员权限） -NoProxy: 绕过系统代理

提示：Scoop was installed successfully! 说明安装成功。

安装quarkdown

scoop bucket add java
scoop bucket add quarkdown https://github.com/quarkdown-labs/scoop-quarkdown
scoop install quarkdown

参考资料 https://zhuanlan.zhihu.com/p/1931641798855458999 https://blog.csdn.net/m0_74412436/article/details/145394440

quikly start

文档创建、布局/主题定义

quarkdown project created by :

quarkdown create dir_name

This will create a new directory named dir_name with the following structure:

dir_name/
├── dir_name.qd
├── image/
├──...

document type 选择和定义:

slides : 带交互式导航的演示格式。
plain : 类似 Notion 或 Obsidian 的连续流布局，适合知识管理和网页浏览。
paged : 传统文档布局，带分页，完美适用于 PDF。

.doctype {slides}

document theme 选择和定义:

quarkdown 的主题分两部分：color theme、layout theme :

.theme {paperwhite} layout:{latex}

几个常用的主题组合：

paperwhite + latex : 干净的学术风格（这是默认主题）
darko + minimal : 暗色主题，样式简洁
galactic + hyperlegible : quarkdown维基使用的主题,字体高度易读
beaver + beamer : 学术演示风格

请参阅主题列表以获取所有可用主题.

编译/预览文档

进入.qd文件所在的目录，运行以下命令来编译文档：

quarkdown c dir_name.qd

如果要导出pdf文件则:

quarkdown c dir_name.qd --pdf

如果要启用实时预览，运行命令：

quarkdown c dir_name.qd -p -w

如果指定浏览器:

quarkdown c dir_name.qd -p -w --browser=chrome

图片大小

quarkdown 指定图片比例的语法:

<!-- !(50%)[图片描述](图片路径) -->
!(50%)[Logo](image/logo.png)

也可以直接指定图片大小, 支持 px, pt, cm, mm, in, and %等单位

指定宽度和高度 
!(6cm 2cm)[Logo](image/logo.png)
只指定高度 
!(_ 2cm)[Logo](image/logo.png)

图表

当一张图片单独存在，与其他内容分离时，它会自动成为一幅图。图可以居中显示，并且可以带有标题. 可以在引号中添加标题来添加说明文字:

!(50%)[Logo](image/logo.png "The Quarkdown logo")

效果:

The Quarkdown logo

方程和公式

使用 $ expression $ 来定义行内TeX 公式,请注意空格很重要, 并且独立的行内方程会自动成为居中块状方程.

例如:

$ E = mc^2 $ is Einstein's mass-energy equivalence formula.

$ f(x, y) = \frac{x}{y} $

效果:

E = mc^2 is Einstein’s mass-energy equivalence formula.

f(x, y) = \frac{x}{y}

函数调用

quarkdoown有很多内置函数来增强markdown的功能, 也可以自定义函数来满足特定需求. 函数调用以.开头，并使用花括号作为参数。参数可以是位置参数或命名参数:

.pow {5} to:{2} is a mathematical operation.

效果:

25 is a mathematical operation.

函数调用可以是内联的或块状的，这取决于它们是否出现在其他内容中或独立存在。块函数调用支持缩进的块参数，对应函数的最后一个参数:

.align {center}
    This multi-line paragraph is the block argument,
    and it's now centered in the document.

效果:

This multi-line paragraph is the block argument, acentered in the document.

this is a line

可以将多个函数调用连在一起，每个函数的输出都成为下一个函数的第一个参数:

.align {center}
    .sqrt {10}::round::multiply {2}

效果:

所有可用函数的完整列表请参阅函数列表。

变量

quarkdown 允许定义和使用变量来存储和重用数据. 使用 .var 函数定义变量,后跟变量名和变量值，并像访问其他函数一样访问它;并且可以修改变量值.

<!-- 定义var -->
.var {name} {John}
<!-- 调用var -->
My name is .name
<!-- 修改var值 -->
.name {Jane}

自定义元素

quarkdown 允许用户定义自定义元素来扩展markdown的功能. 使用 .function 定义自定义函数。函数是封装逻辑和内容的可重用组件。在本节中，我们创建一个生成 Example box 的函数,这种box在教育文档中常用.

定义一个不带参数的函数并且调用:

<!-- .function {函数名} -->
.function {example}
    .box {Example} type:{tip}
        This is my example!

.example

效果:

Example

This is my example!

进一步的，我们可以为函数添加参数来增强其灵活性, 定义形参的方法是在函数名的下一行增加函数列表, 形如param_name1 param_name2 param_name3:,然后在函数体内通过.param_name1来访问参数值, 注意的是参数名不能有下划线:

定义
.function {example2}
    boxcontent:
    .box {Example} type:{tip}
        .boxcontent
调用函数
.example2
    This is my new example!

效果:

Example

This is my new example!

对于自定义元素的高级样式，可以使用 CSS 规则。有关更多信息，请参阅 CSS

编号

文档，尤其是学术文档，需要为章节、图表、表格、公式和代码等元素进行编号。在 Quarkdown 中，你可以使用 .numbering 函数来实现这一点

paged 类型的文档默认启用编号功能。

要使用编号功能,需要在文档内容开始之前，在顶部添加编号方案,类似 YAML 的语法:

.docauthors
    - ...

.numbering
    - headings: 1.1.1
    - figures: 1.1

## Quickstart
...

上述代码定义了两种编号方案：一种用于标题，格式为 1.1.1，另一种用于图表，格式为 1.1。效果如下:

你可以根据需要定义更多的编号方案，例如：1.a.i、A.I等。以下是quardown支持的格式符号:

1 for decimal numbers
A for uppercase letters
a for lowercase letters
I for uppercase Roman numerals
i for lowercase Roman numerals

脚注

在 plain 文档中，脚注出现在参考旁边的页边空白处，类似于旁注。在 paged 和 slides 文档中，脚注出现在页面或幻灯片的底部。

脚注允许你在不干扰正文的情况下添加额外信息。比如为引言添加一个脚注:

### A Quarkdown tour

No need to reinvent the wheel: you can make text **bold** or *italic*,
~~strike through~~, add `inline code`,
create [links](https://quarkdown.com), and much more[^1].

[^1]: All Markdown features are supported in Quarkdown

这是 GFM 脚注语法,Quarkdown 完全支持。Quarkdown 还支持紧凑型脚注，允许你在引用它的位置直接定义脚注:

and much more[^: All Markdown features are supported in Quarkdown].

两者的效果如下:

A Quarkdown tour

No need to reinvent the wheel: you can make text bold or italic, ~~strike through~~, add inline code, create links, and much more¹.

No need to reinvent the wheel: you can make text bold or italic, ~~strike through~~, add inline code, create links, and much more²²this is second footnote. .

¹All Markdown features are supported in Quarkdown

交叉引用

交叉引用允许你引用文档中其他位置的编号元素。

首先，为目标元素添加一个 ID。然后使用 .ref {id} 函数引用它:

!(50%)[Logo](image/logo.png "The Quarkdown logo") {#logo}

The Quarkdown logo is shown in .ref {logo}.

效果:

The Quarkdown logo

The Quarkdown logo is shown in .

quarkdown也可以为其他元素(如章节、表格、公式和代码块)添加 ID,并引用它们,参见Cross-references

页面边距和计数器

页面格式, 页面页边距内容, 页面计数器

在 paged 和 slides 文档中，通常需要页码计数器来帮助读者导航和理解他们在文档中的位置.

首先，通过更改文档顶部的 .doctype 值来切换到 paged 文档类型, 页码功能对palin文档无效:

.doctype {paged}

quarkdown默认页面格式为 A4。您可以使用 .pageformat 函数更改属性：
.pageformat {letter} margin:{2cm}

第二步, 在每页的底部中心添加一个页码：

.docauthors
    - ...

.pagemargin {bottomcenter}
    .currentpage / .totalpages

.numbering
    - ...

.pagemargin 函数可以向每一页添加任何类型的内容。有关所有可用的页边距位置，参阅页边距内容.

持久性标题

页面边距可以在每页显示当前章节标题。以下示例显示了当前一级标题在左下角边距中：

.pagemargin {bottomcenter}
    ...

.pagemargin {bottomleft}
    .lastheading depth:{1}

.numbering
    - ...

多文件

将大型文档拆分为多个源文件有两种主要方法：include和subdocument。include将一个文件的内容直接插入到另一个文件中，而subdocument则允许你将一个文件作为独立的文档进行编译，并在主文档中引用它。

include files

.include 函数将另一个 Quarkdown 文件的内容插入当前文件中。这种方法在 LaTeX 和其他标记语言中很常见，用于将大型文档拆分成更小、更易于管理的文件，例如每个章节或每个部分一个文件.

比如这个文档可以拆分成多个文件:

main-document.qd

.include {setup.qd}

.include {content.qd}

setup.qd

.docname {MyDocument}
.doctype {paged}
.doclang {English}
.theme {paperwhite} layout:{latex}

.docauthors
    - Quarkdown

.pagemargin {bottomright}
    .currentpage / .totalpages

.numbering
    - headings: 1.1.1
    - figures: 1.1

content.qd

.tableofcontents

## Quickstart

...

对于更多的文件，可以考虑使用 .includeall:

main-document.qd

.includeall
    - setup.qd
    - content.qd

引用文件

使用子文档，这在知识库和维基中尤其常见,子文档是独立的内容单元，它们共享相同的设置和配置。你可以通过链接从其他文档中引用它们

main-document.qd

- [Introduction](introduction.qd)
- [Chapter 1](chapter1.qd)
- [Chapter 2](chapter2.qd)
- [Conclusion](conclusion.qd)

可视化由子文档形成的知识图谱:

.subdocumentgraph

效果:

graph LR
100346066["index"] --> 63058797["About"]
100346066["index"] --> 1741126858["quarkdown_guidelines"]
100346066["index"] --> 71602["Git"]
100346066["index"] --> 1900752513["IBVP_of_ODEs_Notes"]
100346066["index"] --> 790032746["Wilson_PS4"]
1741126858["quarkdown_guidelines"] --> 947936748["section1"]
1741126858["quarkdown_guidelines"] --> 947936749["section2"]

结论

入门完毕,更多高级主题请参阅官方wiki。

返回主页