/

Quarkdown

v2.4.0

文档

本页目录

引入其他 Quarkdown 文件

.include {file} {sandbox?} 文档 ↗ 函数用于加载并求值一个外部的 Quarkdown 源文件。

该参数接受一个代表目标文件路径的字符串，路径可以是相对于主源文件位置的，也可以是绝对路径。

若要引入外部库，请参阅导入外部库 。

示例 1

file.qd

### Hello Quarkdown

This is external content.

main.qd

.include {file.qd}

Hello Quarkdown

This is external content.

重要：循环依赖会导致错误。

不要将引入与子文档 混淆。有关二者的对比，请参阅引入 vs. 子文档 。

批量引入

在使用排版系统时，一种干净的做法是创建一个主文件，将各个子文件汇总起来。.includeall 函数接受一个路径的可迭代对象 ，可作为重复调用 .include 的便捷简写。

以下代码片段来自 Mock 项目的 main.qd 文件：

Error: code

Cannot call function code(...) with arguments (...):
Cannot call function read(Context context, String path, optional Range lines) with arguments (../mock/main.qd, 6..): File C:\Users\bbylw\Desktop\quarkdown-main\docs-zh\..\mock\main.qd does not exist.

.code lang:{markdown}
    .read {../mock/main.qd} lines:{6..}

你也可以将该函数与 .listfiles 结合，自动引入某个目录下的所有文件：

.includeall {.listfiles {somedirectory} sortby:{name}}

上下文共享

.include 函数的 sandbox 参数让你控制被引入文件与主文件之间的隔离程度。被引入的文件始终会继承主文件的上下文，但你也可以选择性地允许被引入文件中的变更回传。

对于这些示例，请考虑以下文件：

file.qd

.docname {New name}

.function {greet}
  name:
  Hello, **.name**!

main.qd

.docname {My document}
.include {file.qd} sandbox:{<value>}

1. .docname
2. .greet {John}

以下是可用的选项，按隔离程度从低到高排列：

share（默认）

两个上下文进行双向同步。在被引入文件中声明的任何自定义项、函数、变量以及其他信息，在主文件中也可用，反之亦然。

输出：

  1. New name
  2. Hello, John!

scope

与 share 类似，但函数和变量的声明不会回传到主文件。

这与嵌套 lambda 作用域（例如 .function 和 .foreach ）中的行为相同。

输出：

  1. New name
  2. 编译错误：.greet 未定义。

subdocument

被引入的文件与主文件完全隔离。任何变更，包括元数据与布局选项，都不会回传。

这与子文档 的行为相同。

输出：

  1. My document
  2. 编译错误：.greet 未定义。

使用场景：初始化设置

一个常见的用法是将所有初始化函数调用放在一个单独的文件中。有关全部可用选项，请参阅本维基的文档设置章节。

setup.qd

.docname {My document}
.docauthor {iamgio}
.doctype {slides}
.doclang {English}
.theme {darko} layout:{minimal}

.footer
   ...

main.qd

.include {setup.qd}

# My cool document

...