# 运行时函数

以下函数都从 `@minidocs/astro/runtime` 导入。多语言站点和单语言站点的差别写在每个函数下面。

## 页面

### `listPages(entries)`

返回集合里所有要生成的页面。`entries` 来自 `getCollection`。每个页面有：

| 字段               | 含义                                                         |
| ---------------- | ---------------------------------------------------------- |
| `id`             | 页面 id                                                      |
| `entry`          | 集合里的条目                                                     |
| `href`           | 页面的地址                                                      |
| `params`         | 页面路由的参数。单语言站点是 `{ slug }`，多语言站点是 `{ locale, slug }`        |
| `markdownHref`   | Markdown 版本的地址                                             |
| `markdownParams` | Markdown 路由的参数。单语言站点是 `{ path }`，多语言站点是 `{ locale, path }` |

多语言站点上，每种语言的每个页面各有一项，包括通过 `fallback` 显示的页面，还多几个字段：

| 字段              | 含义                                    |
| --------------- | ------------------------------------- |
| `locale`        | 页面显示在哪种语言下                            |
| `contentLocale` | 内容实际的语言，只有 fallback 的页面和 `locale` 不同  |
| `isFallback`    | 是否显示的是另一种语言的内容                        |
| `alternates`    | `{ locale, href }[]`，页面存在的所有语言，包括当前语言 |

### `toHref(collection, id, locale?)`

返回页面的地址，带上 `base` 和 Astro 配置决定的末尾斜杠。`id` 按 `collection` 检查类型。多语言站点必须传 `locale`。

### `toLocaleParam(locale)`

返回 `[...locale]` 路由参数的值，给不来自集合的页面用。默认语言不带语言段时返回 `undefined`。

## 文档树

### `defineTree(entries, build)`

用 `build` 回调定义文档树，返回节点数组。多语言站点对每种语言执行一次 `build`，返回按语言索引的对象。

`build` 收到 `{ page, group, dir, link }`，多语言站点还有 `locale`：

| 函数                        | 产出                                    |
| ------------------------- | ------------------------------------- |
| `page(id, children?)`     | 一个页面节点。`id` 在这种语言里不存在时报错              |
| `group(label, children)`  | 一个分组节点                                |
| `dir(path, { compare? })` | 目录里的页面和子目录，不含目录自己的 `index`。目录里没有页面时报错 |
| `link(label, href)`       | 一个外部链接节点                              |

节点有 `label`、`children`，页面节点有 `page`（其中 `page.entry` 是集合里的条目），外部链接有 `href`。没有页面、链接和子节点的分组会被去掉。

### `navState(nodes, id)`

返回 `{ of(node) }`。`of(node)` 返回：

| 字段        | 含义                         |
| --------- | -------------------------- |
| `href`    | 页面或外部链接的地址，分组是 `undefined` |
| `current` | 是不是当前页面。同一个页面出现多次时，只有第一次算  |
| `open`    | 当前页面是不是这个节点本身或在它下面         |

### `neighbors(nodes, id)`

返回 `{ prev, next }`，按文档树的顺序找出上一个和下一个页面节点，没有时是 `undefined`。

### `findPath(nodes, id)`

返回从第一层到当前页面的节点数组，找不到时是空数组。

### `tocTree(headings, { depth? })`

把 `render()` 返回的 `headings` 整理成树，每个节点有 `depth`、`slug`、`text` 和 `children`。`depth` 是保留的标题层级范围，默认 `[2, 3]`。

## Markdown 和 llms.txt

### `toMarkdown(page, { renderers? })`

把页面的正文转成 Markdown，不带标题。`page` 是 `listPages` 返回的页面，或者节点的 `page`。正文里有其他框架的组件时，用 `renderers` 传入它们的渲染器。

### `isMarkdown(Astro)`

组件是否正在为 Markdown 版本渲染。

### `toLlmsTxt(nodes, { title, describe? })`

从文档树生成 llms.txt。`title` 是文件的标题，`describe(entry)` 返回页面的描述，`index` 页面的描述同时作为文件的简介。可以把几个集合的树拼在一起传入。

### `toLlmsFullTxt(nodes, { renderers? })`

把树里所有页面的 Markdown 按顺序拼成一个文件。