iamgio/quarkdown
GitHub: iamgio/quarkdown
基于 Markdown 的现代排版系统，通过图灵完备的函数扩展实现从单一源文件到论文、演示文稿、网站、书籍等多种格式的无缝输出。
Stars: 12530 | Forks: 332
Releases
Latest
|
Stable
# 目录
1. [关于](#about)
2. [演示](#as-simple-as-you-expect)
3. [目标输出格式](#targets)
4. [对比](#comparison)
5. [入门指南](#getting-started)
1. [安装](#installation)
2. [快速开始](#quickstart-)
3. [创建项目](#creating-a-project)
4. [编译](#compiling)
6. [Mock 文档](#mock-document)
7. [贡献](#contributing)
8. [赞助](#sponsors)
9. [理念](#concept)
10. [许可证](#license)
# 关于
Quarkdown 是一个基于 Markdown 的现代排版系统，专为**多功能性**而设计。它允许单个项目无缝编译为可打印的书籍、学术论文、知识库或交互式演示文稿。
这一切都归功于极其强大的图灵完备 Markdown 扩展，确保你的想法能够自动跃然纸上。
Original credits: Attention Is All You Need
Quarkdown Flavor 诞生于 CommonMark 和 GFM 的扩展，它为 Markdown 引入了**函数**，以及许多其他语法扩展。
得益于不断扩展的[标准库](quarkdown-stdlib/src/main/kotlin/com/quarkdown/stdlib)，**可能性是无限的**，
它提供了布局构建器、I/O、数学运算、条件语句和循环。
**还不够？** 你仍然可以在 Markdown 中定义自己的函数和变量。
你甚至可以为所有人创建出色的库。
这种开箱即用的脚本支持，为创建复杂和动态的内容打开了大门，而这些在原生 Markdown 中是无法实现的。
结合实时预览、:zap: 极快的编译速度以及强大的 [VS Code 扩展](https://marketplace.visualstudio.com/items?itemName=quarkdown.quarkdown-vscode)，Quarkdown 能够轻松搞定一切，
无论是学术论文、书籍、知识库还是交互式演示文稿。
在寻找什么？
查看 wiki
以开始入门并了解更多关于该语言及其特性的信息！
## 如你期望般简单...
Inspired by: X-ray flashes from a nearby supermassive black hole accelerate mysteriously
...如你所需般复杂。
# 目标输出格式
- **HTML**
- [X] **Plain**
类似 Notion/Obsidian 的连续流，非常适合静态网站和知识管理 - 查看作者的[个人网站](https://iamgio.eu/)。
- [X] **Paged**
via [paged.js](https://pagedjs.org)
非常适合论文、文章和书籍 - 查看[演示文档](https://github.com/quarkdown-labs/generated/blob/main/mock/paperwhite_latex.pdf)。
- [X] **Slides**
via [reveal.js](https://revealjs.com)
非常适合交互式演示文稿。
- [X] **Docs**
非常适合 wiki、技术文档和大型知识库 - 查看 [Quarkdown 的 wiki](https://quarkdown.com/wiki)。
- **PDF**
- [X] HTML 支持的所有文档类型和特性在导出为 PDF 时也同样受支持。
- **纯文本**
可以通过在源文件中调用 [`.doctype` 函数](https://quarkdown.com/wiki/document-types) 来设置所需的文档类型：
- `.doctype {plain}` (默认)
- `.doctype {paged}`
- `.doctype {slides}`
- `.doctype {docs}`
# 对比
| | Quarkdown | LaTeX | Typst | AsciiDoc | MDX |
|-----------------------|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|
| 简洁易读 | :white_check_mark: | :x: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| 完整的文档控制[^control] | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: |
| 脚本支持 | :white_check_mark: | Partial | :white_check_mark: | :x: | :white_check_mark: |
| 书籍/文章导出 | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | Third-party |
| 演示文稿导出 | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | Third-party |
| 静态站点导出 | :white_check_mark: | :x: | Experimental | :white_check_mark: | :white_check_mark: |
| 文档/Wiki 导出 | :white_check_mark: | :x: | :x: | :white_check_mark: | :white_check_mark: |
| 学习曲线 | :green_circle: | :red_circle: | :orange_circle: | :green_circle: | :green_circle: |
| 目标格式 | HTML, PDF, TXT | PDF, PostScript | HTML, PDF | HTML, PDF, ePub | HTML |
[^control]: 通过语言本身自定义文档及其输出产物属性的能力。
| 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[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}
```
|
```
.tableofcontents
# 小节
## 子节
1. **First** item
2. **Second** item
.center
This text is _centered_.
.row alignment:{spacebetween}
```
|
# 入门指南
## 安装
### 安装脚本 (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/quarkdown`。
如果缺少依赖，将使用系统包管理器自动安装 Java 17、Node.js 和 npm。
有关更多安装选项，请查看 [get-quarkdown](https://github.com/quarkdown-labs/get-quarkdown)。
### Homebrew (Linux/macOS)
```
brew install quarkdown-labs/quarkdown/quarkdown
```
### 安装脚本 (Windows)
```
irm https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.ps1 | iex
```
### Scoop (Windows)
```
scoop bucket add java
scoop bucket add quarkdown https://github.com/quarkdown-labs/scoop-quarkdown
scoop install quarkdown
```
### GitHub Actions
查看 [setup-quarkdown](https://github.com/quarkdown-labs/setup-quarkdown) 以轻松将 Quarkdown 集成到你的 GitHub Actions 工作流中。
### 手动安装
手动安装说明
从[最新稳定版本](https://github.com/iamgio/quarkdown/releases/latest)下载 `quarkdown.zip` 并解压，
或使用 `gradlew installDist` 进行构建。
或者，将 `/bin` 添加到你的 `PATH` 中，以便更轻松地访问 Quarkdown。
系统要求：
- Java 17 或更高版本
- (仅适用于 PDF 导出) Node.js、npm、Puppeteer。详情请参阅 [*PDF 导出*](https://quarkdown.com/wiki/pdf-export)。
## 快速开始 🆕
新用户？你会在**[快速开始指南](https://quarkdown.com/wiki/quickstart)** 中找到**所需的一切**，为你的第一份文档注入生命！
## 创建项目
**`quarkdown create [directory]`** 将启动基于提示的项目向导，使得设置新 Quarkdown 项目比以往任何时候都快，并且所有[元数据](https://quarkdown.com/wiki/document-metadata)和初始内容均已存在。
有关项目创建器的更多信息，请查看其 [wiki 页面](https://quarkdown.com/wiki/cli-project-creator)。
或者，你可以手动创建一个 `.qd` 源文件并从此开始。
## 编译
运行 **`quarkdown c file.qd`** 将编译给定文件并将输出保存为文件。
如果你想先熟悉一下 Quarkdown，`quarkdown repl` 可以让你体验交互式 REPL 模式。
#### 选项
最常用的选项有：
- **`-p`** 或 **`--preview`**：在编译后启用自动内容重载。
- **`-w`** 或 **`--watch`**：每次源目录中的文件发生更改时重新编译。
- **`--pdf`**：生成 PDF 文件。在 wiki 的 [*PDF 导出*](https://quarkdown.com/wiki/pdf-export) 页面了解更多。
有关完整的选项列表，请查看 [CLI 选项](https://quarkdown.com/wiki/cli-options) wiki 页面。
## Mock 文档
用 Quarkdown 编写的 ***Mock*** 是该语言所提供的视觉元素的全面集合，
非常适合探索和理解其关键特性——同时以页面或幻灯片的具体形式进行动手实践和实验。
- 该文档的源文件可在 [`mock`](mock) 目录中找到，可以通过 `quarkdown c mock/main.qd -p` 进行编译。
- 所有可能的主题组合生成的 PDF 产物均可在 [`generated`](https://github.com/quarkdown-labs/generated) 仓库中查看。
## 贡献
欢迎贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何通过 issues 或 pull requests 进行贡献。
## 理念
该 logo 类似于原始的 [Markdown 图标](https://github.com/dcurtis/markdown-mark)，重点关注 Quarkdown 的完备性，
丰富的特性和自定义选项，并通过球体周围旋转的箭头加以强调。
那些可能被误认为是星球的物体实际上是一个 **quark**（夸克），或者更准确地说是一个 **down quark**（下夸克），
这是一种构成物质主要成分的基元粒子：它们赋予了我们已知每一种复杂结构以生命，
同时也是现存最轻的物体之一。
这正是 **Quarkdown** 所基于的理念。
## 许可证
默认情况下，Quarkdown 及其模块均根据 [GNU GPLv3](./LICENSE) 授权，除了包含其自身 `LICENSE` 文件的模块：
CLI (`quarkdown-cli`) 和 Language Server (`quarkdown-lsp`) 模块及二进制文件均根据 GNU AGPLv3 授权。
## 脚注
标签：DNS解析, JS文件枚举, Kotlin, Markdown, MITM代理, Quarkdown, Ruby, VSCode 扩展, 内容管理, 后台面板检测, 威胁情报, 学术工具, 富文本, 开发者工具, 开源项目, 技术写作, 技术栈, 排版引擎, 数字出版, 文档生成, 文档系统, 文档转换, 演示文稿, 电子书制作, 知识库, 科技写作, 论文排版, 静态网站生成