# Runtime Functions

All of these functions are imported from `@minidocs/astro/runtime`. Differences between multilingual and single-language sites are noted under each one.

## Pages

### `listPages(entries)`

Returns every page of the collection that needs a route. `entries` come from `getCollection`. Each page has:

| Field            | Meaning                                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| `id`             | The page id                                                                                                     |
| `entry`          | The collection entry                                                                                            |
| `href`           | The page’s URL                                                                                                  |
| `params`         | Parameters of the page route: `{ slug }` on single-language sites, `{ locale, slug }` on multilingual sites     |
| `markdownHref`   | The URL of the Markdown version                                                                                 |
| `markdownParams` | Parameters of the Markdown route: `{ path }` on single-language sites, `{ locale, path }` on multilingual sites |

On multilingual sites, every page appears once per locale, including pages shown through `fallback`, with a few more fields:

| Field           | Meaning                                                                          |
| --------------- | -------------------------------------------------------------------------------- |
| `locale`        | The locale the page is shown in                                                  |
| `contentLocale` | The locale of the content, which differs from `locale` only for fallback pages   |
| `isFallback`    | Whether the page shows content from another locale                               |
| `alternates`    | `{ locale, href }[]`, every locale the page exists in, including the current one |

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

Returns the URL of a page, with `base` and the trailing slash your Astro config implies. `id` is type-checked against `collection`. Multilingual sites must pass `locale`.

### `toLocaleParam(locale)`

Returns the value of the `[...locale]` route parameter, for pages that do not come from a collection. Returns `undefined` for the default locale when it has no locale segment.

## The document tree

### `defineTree(entries, build)`

Defines the document tree with the `build` callback and returns a list of nodes. On multilingual sites, `build` runs once per locale and the result is an object keyed by locale.

`build` receives `{ page, group, dir, link }`, plus `locale` on multilingual sites:

| Function                  | Returns                                                                                                     |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `page(id, children?)`     | A page node. Fails when `id` does not exist in the locale                                                   |
| `group(label, children)`  | A group node                                                                                                |
| `dir(path, { compare? })` | The pages and subdirectories of a directory, without its own `index`. Fails when the directory has no pages |
| `link(label, href)`       | An external link node                                                                                       |

Nodes have `label` and `children`, page nodes have `page` (where `page.entry` is the collection entry), and external links have `href`. Groups with no page, link or children are dropped.

### `navState(nodes, id)`

Returns `{ of(node) }`. `of(node)` returns:

| Field     | Meaning                                                                                   |
| --------- | ----------------------------------------------------------------------------------------- |
| `href`    | The URL of a page or external link, `undefined` for groups                                |
| `current` | Whether it is the current page. When a page appears more than once, only the first counts |
| `open`    | Whether the current page is this node or below it                                         |

### `neighbors(nodes, id)`

Returns `{ prev, next }`, the previous and next page nodes in the order of the tree, `undefined` when there is none.

### `findPath(nodes, id)`

Returns the nodes from the first level down to the current page, or an empty array when the page is not found.

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

Arranges the `headings` from `render()` into a tree, where each node has `depth`, `slug`, `text` and `children`. `depth` is the range of heading levels to keep, `[2, 3]` by default.

## Markdown and llms.txt

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

Converts the content of a page into Markdown, without the title. `page` is a page from `listPages` or the `page` of a node. When the content uses components of other frameworks, pass their renderers in `renderers`.

### `isMarkdown(Astro)`

Whether a component is rendering for a Markdown version.

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

Generates llms.txt from the document tree. `title` is the heading of the file, `describe(entry)` returns the description of a page, and the description of the `index` page also becomes the summary of the file. Trees of several collections can be joined and passed in.

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

Joins the Markdown of every page in the tree, in order, into one file.