# HTML 页面

> 一个 .html 页面：完整文档或片段，其 head 即元数据，任何元素、样式或脚本都放在站点的布局之中。

项目中的每个 `.html` 文件都是一个页面，可以是完整文档，也可以是片段；htmlpress 以相同方式读取两者。它的 `<title>` 和 `<meta name="…">` 标签就是它的元数据，即 [前置元数据](/zh/authoring/frontmatter/)所列的键，body 的其余部分是内容。[Markdown 页面](/zh/authoring/markdown-pages/)是同样的页面，只是用 Markdown 编写。

页面就是纯 HTML，htmlpress 不对它做限制：任何元素、属性、内联 SVG、`<canvas>`、`<iframe>`、自定义元素、样式或脚本都按原样工作。没有模板语言，也没有白名单。Htmlpress 把页面包进站点的布局，让它获得导航、主题和搜索，其余交给浏览器。

这让页面不止是一篇文档：仪表盘、报告、幻灯片或交互式浏览器都只是一个 `.html` 文件。参见[示例](/zh/examples/)，其中十几个页面都基于真实的公开数据。

## 自包含的页面

页面自己的 `<style>`、`<script>` 和 `<link>` 会被保留，并添加到布局的 head 中，位于主题之后。片段取其第一个内容之前的标签；完整文档取其 `<head>`。

```html
<title>计数器</title>
<style>
  .counter button {
    border: 1px solid var(--htmlpress-border);
    background: var(--htmlpress-surface);
    color: var(--htmlpress-text);
  }
</style>
<script type="module">
  const button = document.querySelector(".counter button")
  let count = 0
  button.addEventListener("click", () => {
    button.textContent = `已点击 ${++count} 次`
  })
</script>

<h1>计数器</h1>
<div class="counter">
  <button type="button">点我</button>
</div>
```

## 融入站点

- **把样式限定在一个类下。**&#x9875;面的 CSS 作用于整个文档，包括布局，所以每条规则都要以页面自身根元素上的类开头，如上面的 `.counter`。
- **使用主题令牌。**&#x6765;自 [`--htmlpress-*` 令牌](/zh/authoring/rich-elements/) 的颜色会跟随浅色和深色主题以及任何覆盖，无需自己的媒体查询。
- **以模块方式运行脚本。**`type="module"` 在页面解析完成后运行，并让其中的名称不进入全局作用域。
- **优先使用语义化元素。**&#x4E3B;题已经为标题、表格、列表和表单设置了样式；页面只需为 HTML 没有对应元素的部分编写自己的 CSS。

## htmlpress 会改动什么

内容按原样放入布局，只有以下构建时处理除外：

- 没有 `id` 的 `<h2>` 到 `<h6>` 会获得一个，`<h2>` 到 `<h4>` 会进入目录；参见[标题](/zh/authoring/headings/)。
- 指向页面文件的链接会变成它的 URL，相对 URL 从源文件解析；参见[链接](/zh/authoring/links/)。
- `<pre><code class="language-*">` 会被高亮；参见[代码块](/zh/authoring/code-blocks/)。
- 正文中，裸 URL 变成链接，`:emoji:` 短代码变成表情，`$…$` 变成公式；参见[高级语法](/zh/authoring/advanced-syntax/)。代码、链接、脚本、样式以及带 `data-literal` 的元素保持不变。
- `htmlpress-*` 标签会变成组件；参见[富元素](/zh/authoring/rich-elements/)。

对于完全不需要站点外框的页面，例如落地页，用 `<meta name="layout">` 选择另一个布局；参见[前置元数据](/zh/authoring/frontmatter/)。
