配置参考

站点配置通过 absolutePress(defineSiteConfig({...})) 传入，类型定义在 src/shared/types.ts（SiteConfig）与 src/node/config.ts（AbsolutePressConfig，构建层扩展）。本文按字段逐一说明，全部以实现为准。

基础字段

locales

ts
locales: {
  en: { lang: 'en', label: 'English' },
}

iconProvider

ts
iconProvider: 'fontawesome',

内置图标源，注册表叠加在自定义 icons 之下（同名时 icons 优先）。'fontawesome' 把 Font Awesome 全部免费字形按 <pack>/<name> 注册（solid / regular / brands 三组，如 solid/rocket、brands/github），frontmatter icon 直接引用，无需逐个登记。未配置时不注册任何图标。

icons

ts
icons: {
  'my-logo': '<svg xmlns="..." viewBox="0 0 16 16" fill="currentColor">...</svg>',
}

自定义图标 kv：key 是 frontmatter icon 的合法取值（构建期校验，未注册的 key 报错）；value 是完整 <svg>...</svg> 字符串，或裸 SVG 内部标记（客户端会包一层 24x24 svg）。navbar/sidebar/文章卡片消费这些图标。与 iconProvider 的 key 同名时此处优先。

islands

ts
islands: {
  Counter: 'docs/islands/Counter.tsx',
}

站点追加的自定义 island：PascalCase 标签名 → 相对项目根的模块路径。内置名单（Giscus/PasswordGate/ZoomedImg/Mermaid/G2Plot/ExpandableList）之外的能力入口，详见Islands。

buildComponents

ts
buildComponents: {
  disable: ['RecentArticles'],
}

内置构建组件的总开关：构建组件是构建期渲染为最终静态 HTML 的 markdown 标签（清单与用法见 Markdown 扩展）。disable 按标签名关闭内置组件——被关闭的标签渲染为空并输出构建警告；未知名字在配置解析时报错并列出全部可用名。

refs

ts
refs: ['reference', '../glossary'],

术语库根目录列表（可选，单项可直接写字符串）：[[id]] 术语引用语法的数据源，详见 Markdown 扩展。

encrypt

ts
encrypt: [
  {
    match: '/guide/secret', // 字符串全等匹配路由，或 RegExp.test
    passwords: ['docs-demo'],
    hint: '可选提示文案',
  },
];

客户端密码门规则数组：match 命中（字符串精确匹配或正则，避免 /g 标志）的页面正文被 PasswordGate island 包裹，输入 sha256 命中的密码后解锁，sessionStorage 按路由记住。中文等非 ASCII 路由直接写明文路径（构建期按解码后的路由匹配，正则看到的也是解码形式），不要写百分号编码。明文密码不会进入页面 payload（只输出 sha256 hex）。详见加密。

algolia

ts
algolia: {
  appId: 'XXX',
  apiKey: 'xxx',
  indexName: 'xxx',
}

配置后主题 chrome 挂载 Algolia DocSearch 搜索框，凭证进入页面 payload。

giscus

ts
giscus: {
  repo: 'owner/repo',
  repoId: 'R_xxx',
  category: 'General',
  categoryId: 'DIC_xxx',
}

配置后文章页尾部自动挂载 Giscus 评论 island（无需在 markdown 手写标签）；评论 iframe 主题随站点亮暗切换，不重载 iframe。

googleAnalytics

ts
googleAnalytics: 'G-XXXXXXX',

测量 ID 字符串，构建期注入 GA 脚本。框架会在 SPA 软导航后补发 page_view（首次加载由 GA 自身统计）；请在 GA4 数据流的增强衡量里关闭「基于浏览器历史事件的页面浏览」，否则软导航会被重复计数。

ts
nav: {
  exclude: ['/hide'], // 从 navbar/sidebar 排除的路由前缀（页面仍会构建）
  logo: '/logo.jpg', // navbar（与移动端抽屉）的品牌图
  align: 'center', // 顶层导航条对齐：'left'（默认）| 'center'
  order: ['coding', 'hobbies'], // 顶层条目按内容目录名排序
  tweaks: { /* 按顶层内容目录名微调 navbar 条目，见下 */ },
  social: [
    { icon: 'github', url: 'https://github.com/owner/repo', title: 'GitHub' },
  ],
}

navbar 相关配置的归拢入口：导航树由内容目录自动生成，nav.* 只对生成结果整形。

导航栏还固定渲染一个 RSS 按钮（链接 /rss.xml，base 自适应，title 走 i18n nav.rss）；RSS 始终生成，无需配置开关。

ts
sidebar: {
  order: ['blog', 'guide'], // 顶层分组按内容目录名排序
  tweaks: {
    guide: ['getting-started', 'writing', 'markdown'], // 目录内成员顺序
    'guide/advanced': ['deep'], // 嵌套目录用相对内容根的路径做 key
  },
}

sidebar 由内容目录树完整生成，sidebar.* 只调整生成结果的顺序——条目可以重排，不能增删（隐藏页面走 nav.exclude）。

seo

ts
seo: {
  image: '/og.png', // 分享卡片图，相对站点 public 根解析或绝对 URL
  author: { name: 'Alice', url: 'https://example.com/about' }, // JSON-LD 作者，url 可选
  exclude: ['/hide'], // 不进入 sitemap 且 robots.txt 追加 Disallow 的路由前缀
}

SEO head 选项：image 是分享卡片图，构建期输出 og:image（相对值如 '/og.png' 解析到站点 public 根，拼上 hostname 成绝对地址，与 nav.logo 同语义；https:// 开头的绝对 URL 原样透传）并把 twitter:card 升级为 summary_large_image。未配置时输出 twitter:card: summary（无图卡片），不输出 og:image。author 是文章页 BlogPosting JSON-LD 的作者（schema.org Person），未配置或 name 为空则不输出 author 字段。exclude 让若干路由前缀保持不被抓取：不进 sitemap.xml，robots.txt 各追加一条 Disallow；页面仍会构建。加密页用 encrypt 即可，无需重复列在这里。每页的 meta description 取正文摘要（见 SEO），无需逐页配置。

ts
head: ['<meta name="algolia-site-verification" content="ADD39C0998F22200">'],

注入每个页面 <head> 的原始 HTML 片段数组，原样输出、保持配置顺序，位于框架自身标签之后（speculation rules 脚本之前），空字符串条目被丢弃。面向站点所有权验证 meta（Algolia DocSearch、Google Search Console、Bing…）、第三方统计代码片段、额外的 <link>/<script> 等场景。片段内的资源 URL 必须写绝对地址（https:// 开头）：页面按部署深度生成相对前缀，裸路径在不同深度的页面会指向错误位置。

ts
related: {
  depth: 1, // 1 | 2 | 3，默认 1
  maxNodes: 60, // 每页图的节点上限（含当前页），默认 60
  maxEdges: 240, // 每页成员连边上限，默认 240
  twoHopNodeLimit: 48, // 枢纽页回退阈值，默认 48
}

关联文章图的聚合范围：depth 是文章互引图的 BFS 层数——1 只收互引的一度邻居（默认），2/3 把两跳/三跳内的文章连同它们之间的真实连边一起收进来。非 1/2/3 的值构建期直接报错。

code

ts
code: {
  lineNumbers: true,         // 代码块行号，默认 true
  collapsedLines: 15,        // 超过 N 行折叠；null 显式禁用折叠，默认 15
  wrap: true,                // 软换行，默认 true
  copyLabel: '复制代码',      // 复制按钮的 aria-label/title，用于界面本地化
}

代码块呈现的站点级默认值（markdown 管线消费）：collapsedLines 用 ??= 语义区分「未配置」与「显式 null」，写 null 才是关闭折叠。每个代码块可用围栏 meta 覆盖站点默认：{1,3-5} 行高亮、title="..."、:collapsed-lines[=N]、:no-collapsed-lines、:wrap=true|false，语法与演示见Markdown 扩展。

xlist

ts
xlist: {
  externalize: 16, // KiB 阈值；false 保持全部内联，默认 16
}

ExpandableList（含内置名单内的同类 entry-list 岛屿）的条目正文外置阈值：单个列表渲染后的正文合计超过该值（KiB）时，正文离开页面 HTML，写入内容 hash 的资产模块（assets/xlist-<hash>.js），静态页只留标题行、meta 行与 data-ap-slot 槽位标记；客户端岛挂载后再拉取资产回填。条目多的列表页因此不再把全部折叠正文压进首屏文档。交换代价：无 JS 访客只能看到标题与 meta（锚点保留），正文不参与搜索索引。设 false 全部内联。

home

ts
home: {
  feed: true, // 默认 true
  feedPerPage: 3, // 首页文章流每页篇数，默认 3
}

首页选项：feed 控制是否在各 locale 首页顶部渲染分页文章流。博客首页保持默认；文档/landing 式首页可设 false，让正文介绍（hero/特性/阅读路线）成为视觉主体。feedPerPage 是文章流每页篇数（客户端分页，取值须为不小于 1 的整数）；非默认值才写入页面 payload。

profile

ts
profile: {
  name: 'Alice',              // 卡片显示名，默认站点 title
  avatar: '/me.jpg',          // 头像图，默认 nav.logo（都没有则不渲染头像）
  link: '/about',             // 头像+名称包裹的链接，可选
  articlesLink: '/timeline/', // 「文章」统计数字的链接，可选；默认链接到时间轴内置页
  exclude: ['/hide/'],        // 计数排除的路由前缀（文章总数与分类/标签计数）
  drawer: true,               // 抽屉统计行计数开关，配了 profile 默认 true
}

作者主页卡片，严格 opt-in：不配置时框架行为零变化。配置后每个 locale 首页在构建期于正文顶部注入一张静态卡片（头像 / 统计行 / 社交图标行 / 分类+标签 chips，最终 HTML、零客户端 JS，爬虫与 no-JS 直接可见），同时该首页不再输出 TOC 容器（卡片占位轮廓泳道，客户端软导航会自动补回/移除容器）。

archive

ts
archive: {
  perPage: 10, // 分类/标签归档页每页篇数，默认 10
}

归档页选项：每个分类/标签归档页（/category/*、/tag/*）的文章分页大小，客户端分页，取值须为不小于 1 的整数；非默认值才写入页面 payload。

pages

ts
pages: {
  timeline: true,   // 时间轴页（/timeline/），默认 true
  categories: true, // 分类总览页（/categories/），默认 true
  tags: true,       // 标签总览页（/tags/），默认 true
}

框架内置列表页开关。三个页面都是每 locale 一张的合成静态页（最终 HTML、零客户端 JS，爬虫与 no-JS 直接可读），URL 固定为 <locale>/timeline、<locale>/categories、<locale>/tags（canonical 形态遵循 urls.directoryIndex），由框架在构建期生成，永不出现在 navbar/sidebar。

文档 / landing 站不需要这些页面时逐项设 false 即可。

urls

ts
urls: {
  directoryIndex: 'slash', // 'slash' | 'bare'，默认 'slash'
}

URL 形态选项。目前只有一个键：目录索引页（guide/index.md）的 canonical 路由。

两个平台对对方形态都会补一次重定向（GH 把 /guide 301 到 /guide/，CF 反向），没有通吃的零跳转形态，按部署平台选即可。落盘文件名不受影响，永远是 guide/index.html。

feed

ts
feed: {
  rssLimit: 20, // rss.xml 收录的最新文章数，默认 20
}

订阅源选项：rss.xml 收录各 locale 最新文章的总数上限（feed: false 的页面始终排除），取值须为不小于 1 的整数。全文输出 RSS 需要把站内资源链接改写为绝对 URL，框架刻意不做（摘要 + 链接是订阅源的实用形态），可调的只有收录条数。

ts
footer: {
  credit: '© 2026 Someone',
}

页脚：桌面端一行两栏，右侧固定「Powered by absolute-press」链接指向框架仓库。左侧署名行（桌面页脚与移动端抽屉底部共用）默认是 CC 图标 + 框架名；配置后整段替换为自定义纯文本（组件不解析 HTML，需要图标请走站点 CSS 或自定义 island）。留白字符串视为未配置。

ts
strictLinks: 'warn', // 'off' | 'warn' | 'error'，默认 'warn'

裸相对链接策略：正文里不带 ./ ../ 前缀的站内 markdown 链接（如 guide/a.md）既不会被改写为站内路由，也不参与死链检查，会原样产出指向 .md 的链接——几乎总是漏写前缀的笔误。

只影响构建期报告；dev 服务器不检查。语法细节见Markdown 扩展。

readingTime

ts
readingTime: true, // 默认 true

阅读时长统计：构建期按正文估算——中文按字数（300 字/分钟）、英文按词数（200 词/分钟），混合文本线性合并；frontmatter、代码围栏与行内代码不计入。结果写入页面 payload 的 page.readingTime（整数分钟，向上取整，最小 1），供归档卡片等展示处选用；文章顶部 meta 行当前不渲染该值。设为 false 后 payload 不携带该字段。

onScan

ts
import type { SiteScanContext } from 'absolute-press';

onScan: (ctx: SiteScanContext) => ({
  pages: ctx.pages.map(page => ({
    route: page.route,
    date: page.createdAt,
    tags: page.frontmatter.tag ?? [],
  })),
}),

站点数据钩子：框架单遍扫描内容树，每轮扫描完成后、渲染前运行一次——dev 启动、构建、dev 结构变更 resync 与内容编辑都会触发。参数 SiteScanContext 是 { config, pages }：config 是全量解析后的站点配置（ResolvedConfig），pages 是全部 locale 的页面清单，按配置 locale 顺序排列，类型可从 absolute-press 导入。

返回值会被 JSON 序列化进 virtual:absolute-press/site-data 虚拟模块（default export 即返回值），供站点 island 消费，消费方式见Islands。因此返回值必须 JSON 可序列化（rawFrontmatter 里的裸日期是 Date 对象，需要字符串时先自行 toISOString）；返回 Promise 会被 await。

动机：locale 目录归属、README/index 语义、frontmatter 规范化与未知键告警、git 时间都以框架扫描为准。消费方不必再自己 walk 目录、parse frontmatter、查 git 时间——在 onScan 里从 pages 派生站点数据，语义与框架天然一致；dev 下内容编辑触发新一轮扫描，数据自动刷新，无需重启 dev server（在 vite.config.ts 里自扫内容的老做法需要重启才能拿到新数据）。

SiteScanPage 字段（import type { SiteScanPage } from 'absolute-press'）：

构建层扩展字段（AbsolutePressConfig）

vite 层

absolutePress() 之外仍是标准 vite 配置：build.target 建议 esnext；产物目录用 build.outDir 控制（本站输出到 dist）。UnoCSS 与 vite-plugin-solid 需要显式接入，模板见快速开始。

页面级配置（frontmatter）

frontmatter 只认六个键：date / category / tag / icon / feed / overview，语义见写作指南。feed: false 的页面退出 RSS（文章流仍收录）。