Docs 库

内置的 docs 库由 Quarkdown 编写，为docs 文档提供了标准结构，包含侧边栏、导航和目录。

该库是搭建文档项目的推荐方式，本维基正是使用它构建的。它将原始的 .doctype {docs} 配置封装成一个简单、可定制的引入。

注意：当通过 quarkdown create 创建项目时，生成的项目已经配置为使用 docs 库。

第一步是导入 该库：

.include {docs}

注意：你无需自己调用 .doctype {docs}。库会处理它。

项目结构

使用 docs 库的项目预期具有类似如下的结构：

• _setup.qd：包含共享配置，例如主题 、字体 、自定义函数 和变量 。该文件会被库自动引入。
• _nav.qd：包含用于填充页面列表侧边栏的导航链接。该文件会被库自动引入。
• main.qd：文档的首页，也是编译的入口点。
• 每个其他 .qd 文件都是一个子文档 ，并且应在顶部引入该库：

  .docname {My page}
  .include {docs}
  
  Content goes here.

该库负责处理以下事项：

1. 将文档类型设置为 docs
2. 从项目根引入 _setup.qd
3. 通过 .pagemargin 和 .navigation 将 _nav.qd 中的导航放入左侧边栏
4. 在右侧边栏放入目录
5. 从 .docname 添加一个装饰性标题

设置文件

_setup.qd 文件非常适合放置跨所有子文档共享的项目级配置。

.doclang {English}
.theme {darko} layout:{minimal}

.pagemargin {topright}
    [GitHub](https://github.com/iamgio/quarkdown)

导航文件

_nav.qd 文件包含出现在页面列表侧边栏中的链接。它由一组指向子文档的链接组成，可选择用装饰性标题分组：

###! Getting started
- [Quickstart](quickstart.qd)

###! Topics
- [Page 1](page-1.qd)
- [Page 2](page-2.qd)
  - [Section A](page-2.qd#section-a)

当前页面会在侧边栏中自动高亮。

自定义

默认情况下，页面列表出现在左侧边栏，目录出现在右侧边栏。

你可以通过覆盖 _setup.qd 文件中的两个变量来交换或更改这些位置：

.theme {darko}

.pagelistposition {righttop}
.tocposition {lefttop}

孤立页面

请注意，根据设计，Quarkdown 不会编译孤立的源文件。要作为子文档 被编译，一个源文件必须被另一个文件引用，无论是在 _nav.qd 中还是在其他页面的内容里。