站点元数据

更新于 2026年11月1日

htmlpress.yaml 中的几个顶层键用于向浏览器、搜索引擎和社交卡片描述你的站点。

字段

site: https://example.com
title: My Docs
description: Everything you need to build things.
logo: /logo.svg
favicon: /favicon.ico
banner: 'v2 is out · <a href="/zh/blog/v2/">Read the release notes</a>'
head:
  meta:
    - name: twitter:site
      content: "@me"

键	默认值	出现的位置
`site`	无	规范源地址，用于站点地图、 `<link rel="canonical">`、`og:url` 以及绝对形式的 `og:image` URL
`title`	文件夹名	每个浏览器标签页的标题（位于页面自身标题之后，首页则单独使用）、 `og:site_name`、页眉中的站点标题
`description`	无	没有自身描述的页面所用的 `<meta name="description">` 和 `og:description`，以及品牌标题下方的那行文字
`logo`	无	显示在页眉站点标题之前的图片（也是 favicon 的默认值）
`favicon`	logo	浏览器标签页图标
`banner`	无	每个页面页眉上方的公告栏
`head`	无	添加到每个页面 `<head>` 中的额外 `meta`、`links` 和 `scripts`

站点地图与 `site`

如果设置了 site，每次构建都会在输出根目录写入一个包含所有页面的 sitemap.xml，以 site（及 base）作为每个 URL 的绝对源地址，并由 robots.txt 指向它。没有 site 时，会跳过站点地图：它只能列出绝对 URL。名为 sitemap.xml 或 robots.txt 的项目文件会优先于生成的文件。

Logo 与 favicon

logo 和 favicon 接受任何 URL 或根相对路径（/logo.svg）。项目中的任何文件都会复制到输出目录的相同路径下，因此根目录下的 logo.svg 可以通过 /logo.svg 访问。
如果省略 favicon，htmlpress 会回退到 logo；两者都没有时，使用 htmlpress 图标，可用 .htmlpress/favicon.svg 替换。
logo 是 <htmlpress-brand> 中位于站点标题及其 description 之前的 <img>，该元素链接到首页。

请保持 logo 文件体积较小（SVG 最理想）。每个页面都会在页眉中加载它。

公告栏

banner 会在每个页面的页眉上方显示一个全宽横栏。它的值是 HTML，会按原样写入 <htmlpress-banner>，因此链接或任何行内标记都不需要自定义组件：

banner: 'Htmlpress is in technical preview · <a href="https://github.com/datisthq/htmlpress/discussions">Share feedback</a>'

根相对链接会加上你的 base 前缀。
如需不同的标记或样式，可以弹出 components/banner/banner.css，或用 components/banner/banner.html 替换该元素（覆盖/弹出）。

页面级标签

每个页面都会用自己的 <title>（后接 · site title）、 description、og:title 和 og:description 覆盖站点默认值； og:type 为 website。设置了 site 时，页面还会获得 og:url 和一个 <link rel="canonical">。页面的 <meta name="image"> 会成为它的 og:image，借助 site 转为绝对路径（没有它时省略本地图片），并把 twitter:card 从 summary 切换为 summary_large_image。

额外的 head 标签

head 会在默认标签和主题之后，向每个页面添加标签：由属性映射组成的列表。脚本的 children 是它的内联源码；与默认项具有相同 name 或 property 的 meta 条目会替换该默认项：

head:
  meta:
    - name: twitter:card
      content: summary_large_image
    - name: google-site-verification
      content: abc123
  links:
    - rel: me
      href: https://mastodon.social/@me
  scripts:
    - src: https://example.com/analytics.js
      defer: ""
    - children: console.log("hello")

页面自身 <head> 中的 <link>、<style> 或 <script> 排在这些标签之后，且只作用于该页面。

另请参阅

外部链接：位于标题旁边的页眉和侧边栏链接。
文章分区：组织站点本身的内容结构。

用 ❤ 和 Htmlpress 构建