Markdown 页面

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

---
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。author 和 keywords 接受列表，head 是添加到页面 <head> 中的原始 HTML：

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 的相同，所以 Livemark 页面在这里也能照样读取。

:::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 这样的内容仍保持为文本。

代码块

代码块的语言决定其高亮，语言之后的内容取 代码块属性，但去掉 data-： title、collapse、lines、line-numbers、 add、remove、focus、error、 warning 和 words。

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

数学公式、表情和链接

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

哪些文件是页面

没有 include 时，项目中的每个 .html 和 .md 文件都是页面，README.md 也不例外。请在配置文件中排除不是页面的文件。以下文件永远不是页面：

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