富元素

少量 htmlpress-* 元素覆盖了 HTML 没有对应元素的场景。它们是轻量 DOM（light DOM）自定义元素，因此其内容仍是普通 HTML，即使在脚本加载之前也能良好阅读。每个元素的样式和脚本只在使用它的页面上引入。在组件中放置块级内容（<p>、<h3>、<pre>），而不是裸文本。

表格

<table> 会直接应用样式，带有 <thead> 的表格点击任意表头即可按该列排序：

<table>
  <thead><tr><th>Language</th><th>Year</th><th>Typing</th></tr></thead>
  <tbody><tr><td>TypeScript</td><td>2012</td><td>Static</td></tr>…</tbody>
</table>

| Language | Year | Typing |
| --- | --- | --- |
| TypeScript | 2012 | Static |

渲染为：

提示框

提示框用于突出重要信息。type 可以是 info（默认）、 note、tip、warning 或 danger，title 会替换该类型自带的标题：

<htmlpress-callout><p>This is a note.</p></htmlpress-callout>

<htmlpress-callout type="warning" title="Breaking Change">
  <p>This API has been removed in v2.</p>
</htmlpress-callout>

:::info
This is a note.
:::

:::warning[Breaking Change]
This API has been removed in v2.
:::

渲染为：

提示框内的标题不会进入页面目录。

可展开内容

无需组件：主题会为普通的 <details> 设置样式。

<details>
  <summary>Click to expand</summary>
  <p>Hidden content here with <strong>HTML</strong> support.</p>
</details>

:::details[Click to expand]
Hidden content here with **Markdown** support.
:::

渲染为：

其中可以嵌套任何 HTML，包括代码块、列表和提示框：

site: https://htmlpress.dev
title: Htmlpress

代码标签页

只包含代码块的标签页会合并为一个带边框的块。每个 <section> 是一个标签页，以其 title 命名：

<htmlpress-tabs sync="lang">
  <htmlpress-tab title="JavaScript"><pre><code>console.log("hello")</code></pre></htmlpress-tab>
  <htmlpress-tab title="Python"><pre><code>print("hello")</code></pre></htmlpress-tab>
</htmlpress-tabs>

```js tab="JavaScript" sync="lang"
console.log("hello")
```

```python tab="Python"
print("hello")
```

渲染为：

console.log("hello")

print("hello")

添加 sync="key" 可让多个标签页组保持同步，详见下文“内容标签页”。

内容标签页

用 <htmlpress-tabs> 把任意内容分组为标签页，每个标签页对应一个 <htmlpress-tab title>。

添加 sync 属性可在多个标签页组之间同步选中状态。当读者在某个组中选择一个标签页时，所有具有相同 sync 键的其他组都会切换到对应的标签页，并且该选择会通过 localStorage 在页面之间记住。

<htmlpress-tabs sync="channel">
  <htmlpress-tab title="cargo"><p>From crates.io, built on your machine.</p></htmlpress-tab>
  <htmlpress-tab title="npm"><p>A prebuilt binary per platform.</p></htmlpress-tab>
  <htmlpress-tab title="pip"><p>A binary wheel.</p></htmlpress-tab>
</htmlpress-tabs>

:::tab{title="cargo" sync="channel"}
From crates.io, built on your machine.
:::

:::tab{title="npm"}
A prebuilt binary per platform.
:::

:::tab{title="pip"}
A binary wheel.
:::

渲染为（两个组共享 sync="channel"；切换其中一个试试）：

cargo install htmlpress

npm install -g gethtmlpress

pip install htmlpress

步骤

带 data-step 的标题是一个带编号的步骤，步骤在整个页面中依次计数； 其内容照常跟在后面。这些标题不会进入页面目录。

<h3 data-step>Install</h3>
<p>…</p>
<h3 data-step>Write a page</h3>
<p>…</p>

### Install [step]

…

### Write a page [step]

…

渲染为：

安装

从上面的标签页中选择一个渠道。

编写页面

文件夹中的任意 .html 文件。

启动

运行 htmlpress start 并打开它输出的 URL。

卡片

<htmlpress-cards> 中的卡片排成两列，窄屏时为一列。卡片的 title 是它的标题，href 让整张卡片可点击，icon 以强调色显示在标题前，卡片的内容就是它的正文。

<htmlpress-cards>
  <htmlpress-card title="Getting Started" href="/introduction/" icon="rocket">
    <p>Learn how to set up your first project.</p>
  </htmlpress-card>
  <htmlpress-card title="Plain HTML"><p>…</p></htmlpress-card>
</htmlpress-cards>

:::card{title="Getting Started" href="/introduction/" icon="rocket"}
Learn how to set up your first project.
:::

:::card{title="Plain HTML"}
…
:::

渲染为：

卡片内的标题不会进入页面目录。

徽章

行内标签。variant 为 secondary 或 outline 时样式更朴素，为 positive、warning 或 destructive 时带有色调；不设置时使用强调色。

<htmlpress-badge>New</htmlpress-badge>
<htmlpress-badge variant="positive">Stable</htmlpress-badge>

:badge[New] :badge[Stable]{variant="positive"}

渲染为： 新 次要 稳定 测试版 已移除 描边

按钮

<htmlpress-button href label> 是一个链接到其 href 的行动号召按钮。variant 为 secondary、outline、 ghost 或 link 时更低调，为 positive、 warning 或 destructive 时带有色调；size 可以是 sm 或 lg。

<htmlpress-button href="/introduction/" label="Get Started"></htmlpress-button>
<htmlpress-button href="…" label="GitHub" variant="secondary"></htmlpress-button>

::button[Get Started]{href="/introduction/"}

::button[GitHub]{href="…" variant="secondary"}

渲染为：

快速开始 GitHub 描边 链接

图标

<htmlpress-icon name="…"> 以行内方式绘制一个内置的 Lucide 图标，使用文本的颜色和大小；同样的名称也可用于链接或分区的 icon。未知的名称会导致构建失败。以下是全部 114 个内置图标：

<htmlpress-icon name="rocket"></htmlpress-icon> Get started

:icon{name="rocket"} Get started

文件树

<htmlpress-filetree> 中的嵌套列表；包含列表的项即为文件夹。

<htmlpress-filetree>
  <ul>
    <li>docs<ul><li>index.html</li></ul></li>
    <li>htmlpress.yaml</li>
  </ul>
</htmlpress-filetree>

:::filetree
- docs
  - index.html
- htmlpress.yaml
:::

渲染为：

分栏

<htmlpress-columns> 把子元素并排布局，默认两列，用 cols 最多四列，每个 <htmlpress-column> 是一列：

<htmlpress-columns cols="2">
  <htmlpress-column><p><strong>Left column</strong> with content.</p></htmlpress-column>
  <htmlpress-column><p><strong>Right column</strong> with more content.</p></htmlpress-column>
</htmlpress-columns>

:::column
**Left column** with content.
:::

:::column
**Right column** with more content.
:::

渲染为：

主题令牌

颜色、字体和宽度都是 :root 上的 CSS 自定义属性，在 prefers-color-scheme 或页眉的主题切换下有一套深色值： --htmlpress-accent、--htmlpress-accent-text、 --htmlpress-banner、--htmlpress-banner-text、 --htmlpress-highlight、--htmlpress-highlight-text、 --htmlpress-bg、--htmlpress-surface、 --htmlpress-text、--htmlpress-muted、 --htmlpress-border、--htmlpress-info、 --htmlpress-success、--htmlpress-warning、 --htmlpress-danger、--htmlpress-font、 --htmlpress-mono、--htmlpress-radius、 --htmlpress-shadow、--htmlpress-width 和 --htmlpress-nav-width。可在页面自己的样式表中覆盖它们：

:root {
  --htmlpress-accent: oklch(0.6 0.18 30);
  --htmlpress-font: "Inter", system-ui, sans-serif;
  --htmlpress-width: 52rem;
}

布局

布局就是普通 HTML。Htmlpress 会填充它的 <head>（字符集、视口、标题、描述、社交预览标签、规范链接、favicon、主题、页面所用组件的样式和脚本、htmlpress.yaml 中的 head 标签，最后是页面自己的 head 标签），并在构建时替换以下元素：

<htmlpress-content>

页面内容。

<htmlpress-brand>

站点标题及其下方的 description，设置了 logo 时位于其后，链接到首页。

<htmlpress-banner>

htmlpress.yaml 中的 banner。

<htmlpress-breadcrumbs>

首页、页面之上的每个文件夹（有索引页时以索引页命名并链接到它），然后是页面本身。

<htmlpress-nav>

当前打开分区的页面（未设置 sections 时为所有页面），在“文章”标签下按顶层文件夹分组（博客中为“文章”，更新日志中为“版本”）；文件夹的分组以其索引页命名并链接到它。侧边栏分区位于其开头，侧边栏 links 位于其末尾，归在“链接”之下。

<htmlpress-links>

页眉分区（标记当前打开的分区），然后是 htmlpress.yaml 中的页眉 links。

<htmlpress-page-toc>

页面的 <h2> 和 <h3>，并高亮当前可见的那个。没有 id 的标题会根据其文本获得一个 ID。

<htmlpress-pager>

按导航顺序排列的上一页和下一页。

<htmlpress-edit>

根据 htmlpress.yaml 中的 edit 生成的“编辑此页”链接。

<htmlpress-search>

借助脚本搜索所有页面：页眉中的一个按钮，也可以通过 S、/ 或 ⌘K / Ctrl K 打开。构建会把索引写入 _htmlpress/search.json，并在每个页面的标题处拆分，对话框在首次打开时加载它。查询中的任一词语都可匹配；结果会以 ?highlight= 加查询打开其页面，匹配处用 --htmlpress-highlight 标出并滚动到可见位置。宽度小于 56rem 时，搜索框会占据页眉而不是弹出对话框。

<htmlpress-toolbar>

指向页面 Markdown 副本的链接；脚本会添加“复制 Markdown”“在 ChatGPT 中打开”和“在 Claude 中打开”。

<htmlpress-footer>

“用 Htmlpress 构建”的署名。

<htmlpress-language>

语言选择器，链接到本页面的各语言版本，以下拉菜单显示，在手机上则以底部面板显示；仅在启用了 翻译的站点上显示。

<htmlpress-shortcuts>

页眉中的键盘快捷键菜单，需要脚本，列出所有按键并禁用本页面不可用的按键，例如没有下一页时禁用 L；点击某一行也会触发该按键。宽度小于 56rem 时隐藏，因为没有键盘可用。

<htmlpress-skip>

“跳到正文”链接，仅在获得焦点时显示。

这些元素及其脚本显示的所有字符串都使用页面的语言。脚本从 htmlpress 写入 head 的 <script type="application/json" id="htmlpress-messages"> 中读取字符串，缺少它时回退为英语。

没有内容可显示的元素会被移除。 <htmlpress-nav-toggle>（在手机上把侧边栏变为抽屉；在更宽的屏幕上则折叠侧边栏并记住该状态）、 <htmlpress-theme-toggle>（浅色、深色和系统选择的菜单，以下拉菜单显示，在手机上则以底部面板显示）和 <htmlpress-back-to-top> 由脚本在浏览器中构建。它们的快捷键与 Livemark 一致：M 切换侧边栏，T 在浅色和深色之间切换， U 返回顶部，而 J 和 K 可在任何页面上向下和向上滚动，D 跳到底部。页面上有 <htmlpress-pager> 时，L 和 H 前往下一页和上一页。在输入框中输入时，这些快捷键都不会触发。

手机上的每个底部面板（目录、主题、语言和侧边栏的栏目选择）都是同一个由脚本添加到 body 的 <htmlpress-sheet>。向下滑动、点击背景、按 Esc 或点击关闭按钮都会关闭它，因此转义 components/sheet/sheet.css 即可为所有面板重新设置样式。

它们周围的框架同样由元素构成。这些元素本身不包含内容，只负责为其中的内容设置样式和定位，因此布局可以保留需要的元素，并以属性的形式为它们赋予地标角色：

<htmlpress-shell>

侧边栏与其余部分并排；在手机上堆叠排列。

<htmlpress-sidebar>

品牌和导航；在手机上为抽屉。

<htmlpress-main>

侧边栏旁边的栏。

<htmlpress-header>

顶部的粘性栏，仅在手机上显示品牌和菜单按钮。

<htmlpress-page>

它包含的 <main> 与侧栏并排。

<htmlpress-aside>

内容旁边的栏，为空或屏幕较窄时隐藏。

项目中的 .htmlpress/layout.html 会替换内置布局，页面也可以从 .htmlpress/layouts/ 中选择自己的布局。每个组件的样式和脚本都可以用同样的方式替换或添加：见 覆盖/弹出。