# Markdown 页面

> 用 Markdown 编写页面：用前置元数据写元数据，用指令写组件。

`.md` 文件同样是页面。它会在其 `.html` 同名文件所在的位置提供， `guide.md` 对应 `/guide/`，并与 HTML 页面走相同的构建流程：组件、数学公式、代码块、包含、目录，以及供智能体使用的 Markdown 副本。

````md
---
title: Getting started
description: Install and run it in a minute.
order: 1
---

# Getting started

Install it, then build the docs:

```sh title="Terminal"
npx gethtmlpress build docs
```
````

这里的 Markdown 是 GitHub 风格：表格、任务列表、删除线、脚注和裸链接。原始 HTML 与任何页面一样有效，因此 `htmlpress-*` 组件可以写成标签，空一行后在其中写 Markdown。

## 前置元数据

文件开头的 YAML 设置的内容与 HTML 页面在其 `<head>` 中设置的相同，名称也相同：`title`、`description`、`order`、 `label`、`icon`、`layout`、`sidebar`、 `breadcrumbs`、`toc`、`date`、`author`、 `keywords`、`image`、`language`、`path`、 `source-url` 和 `source-action`，详见 [Frontmatter](/zh/authoring/frontmatter/)。`author` 和 `keywords` 接受列表，`head` 是添加到页面 `<head>` 中的原始 HTML：

```yaml
title: Release notes
author: [Ann, Bo]
keywords: [release, notes]
head: <link rel="alternate" type="application/rss+xml" href="/feed.xml">
```

任何其他键都会使构建失败，因此拼写错误不会被当作元数据。

## 组件

指令就是组件：`:::name` 包裹一个区块，`::name` 独占一行， `:name[label]` 位于文本之中。属性写在花括号里。这些指令与 [Livemark](https://livemark.dev) 的相同，所以 Livemark 页面在这里也能照样读取。

```md
:::warning[Back up first]
The build wipes its output folder.
:::

:::card{title="Install" href="/install/" icon="rocket"}
One command.
:::

The API is :badge[beta]{variant="warning"}.

### Write a page [step]
```

`:::note`、`tip`、`info`、`warning` 和 `danger` 是提示框，标签即标题，GitHub 提醒 `> [!NOTE]` 也是。连续的 `:::card`、`:::column` 和 `:::tab` 会分别组成卡片、分栏和标签页；其余还有 `:::details`、 `:::filetree`、`::button`、`::toc`、 `::video{type="youtube"}`、`::audio{type="soundcloud"}`、 `:badge`、`:icon` 和 `:abbr`。标题可加 `{#id}`、`[step]`、`[!toc]`（不进目录）和 `[toc]`（只进目录）。其他指令就是同名组件，包括项目自己的组件；没有对应组件的区块指令会使构建失败，在文本中像 `note:important` 这样的内容仍保持为文本。

## 代码块

代码块的语言决定其高亮，语言之后的内容取 [代码块属性](/zh/authoring/code-blocks/)，但去掉 `data-`： `title`、`collapse`、`lines`、`line-numbers`、 `add`、`remove`、`focus`、`error`、 `warning` 和 `words`。

````md
```js title="build.js" lines="2" line-numbers
import { build } from "htmlpress"
await build("docs")
```
````

## 数学公式、表情和链接

`$…$` 和 `$$…$$` 是[数学公式](/zh/authoring/advanced-syntax/)， `:rocket:` 这样的短代码是表情，与 HTML 页面相同。通过文件链接到另一个页面， `[Setup](setup.md)`，链接会取该页面的 URL。

## 哪些文件是页面

没有 `include` 时，项目中的每个 `.html` 和 `.md` 文件都是页面，`README.md` 也不例外。请在[配置文件](/zh/customization/configuration-file/)中排除不是页面的文件。以下文件永远不是页面：

- 与其 `.html` 页面并存的 `.md`，它是该页面供智能体使用的 Markdown 副本，会代替生成的副本发布；
- 页面通过 `<htmlpress-include>` 包含的 `.md` 片段，其中的指令和代码块与页面中一样有效；
- changelog 分区的 `source` 文件，由该分区自己的页面展示；
- `skills` 指定的智能体技能。