新闻详情

新闻详情

首页 / 资讯中心 / 详情

Starlight 自定义 404 页面配置实战:从 splash 模板到 hero 组件

发布时间:2026/11/16 7:28:53来源:尧图网络
Starlight 自定义 404 页面配置实战:从 splash 模板到 hero 组件
文档前端开发工具【免费下载链接】starlight Build beautiful, accessible, high-performance documentation websites with Astro项目地址https://gitcode.com/gh_mirrors/st/starlight点击查看免费下载导读本篇文章以 Starlight 官方文档仓库中真实存在的葡萄牙语版 404 页面 docs/src/content/docs/pt-br/404.md 为核心样本系统讲解在 Astro Starlight 文档站点中如何自定义页面未找到404页面。读完本文你将掌握 404 页面的自动生成机制、splash布局模板的作用、hero配置块的全部字段语义以及如何结合editUrl、lastUpdated和disable404Route等配置实现多语言站点下的友好 404 体验。一、从一个真实的 404 页面样本说起docs/src/content/docs/pt-br/404.md是 Starlight 官方文档站点的葡萄牙语巴西404 页面其完整内容如下--- title: Não encontrado template: splash editUrl: false lastUpdated: false hero: title: 404 tagline: strongHouston, temos um problema./strong Não conseguimos encontrar essa página.brVerifique a URL ou tente utilizar a barra de pesquisa. actions: - text: Ir para o início icon: right-arrow link: /pt-br/ variant: primary ---这段仅含 frontmatter 的文档页面没有任何正文 Markdown 内容因为它不需要正文——整页内容完全由 frontmatter 中的hero配置块驱动渲染。这实际上体现了 Starlight 文档站点的两个核心能力任意内容文件都可作为 404 页面只要文件名是404.md或404.mdxStarlight 就会自动将其注册为站点的 404 路由splash模板 hero配置可以完全脱离文档页的侧边栏、目录等布局用 hero 区块呈现一个独立、聚焦的错误提示页面。英文版对应文件为 docs/src/content/docs/404.md结构完全一致仅文案和链接不同链接指向/两份文件形成了多语言 404 的配对实现。二、404 路由是如何自动生成的在 Starlight 中404 页面并非需要手动在astro.config里声明路由而是由集成自动注入。在 packages/starlight/src/index.ts 中可以看到路由注入的核心逻辑if (!starlightConfig.disable404Route) { injectRoute({ pattern: 404, entrypoint: ... ? astrojs/starlight/routes/static/404.astro : astrojs/starlight/routes/ssr/404.astro, }); }也就是说当用户内容集合中存在404.md之类的文件时该文件会与注入的 404 路由模板相结合静态输出模式prerender true与 SSR 模式prerender false分别对应两个不同的路由实现packages/starlight/src/routes/static/404.astro声明export const prerender true在构建期生成404.html适用于纯静态部署packages/starlight/src/routes/ssr/404.astro声明export const prerender false在服务器端按需返回 404 响应适用于 SSR 部署packages/starlight/src/routes/ssr/index.astro 中同样会以new Response(null, { status: 404 })配合返回正确状态码。两者最终都渲染同一个 packages/starlight/src/routes/common.astro由它读取路由数据、渲染页面并包裹进Page组件中。因此你只需在内容目录中编写404.md剩下的路由与状态码处理都由框架完成。三、template: splash无侧边栏的宽版布局frontmatter 中的template字段决定页面布局风格。其取值在 packages/starlight/src/schema.ts 中定义template: z.enum([doc, splash]).default(doc),doc默认标准文档布局包含左侧导航侧边栏、右侧目录等splash宽版布局不渲染任何侧边栏适合首页、落地页或像 404 这样需要全屏聚焦的页面。splash模板对页面结构的影响在路由数据层就有体现。packages/starlight/src/utils/routing/data.ts 中hasSidebar: entry.data.template ! splash,template splash时hasSidebar为falsepackages/starlight/src/components/Page.astro 便不会渲染Sidebar slotsidebar /同时html:not([data-has-sidebar])会把内容区宽度从--sl-sidebar-width约束中释放出来扩大到67.5rem。这正是splash页面内容居中、无干扰视觉效果的来源。四、hero 配置块逐字段拆解hero是 frontmatter 中驱动页面首屏的核心配置其完整 schema 定义于 packages/starlight/src/schemas/hero.ts。对照pt-br/404.md的用法逐字段说明如下4.1title大标题title: 404类型可选字符串支持 HTML语义hero 区块的大号标题文字若不提供则回退使用页面顶层的title字段。这里显式给出404使页面核心视觉元素就是醒目的数字 404。4.2tagline副标题说明文字tagline: strongHouston, temos um problema./strong Não conseguimos encontrar essa página.brVerifique a URL ou tente utilizar a barra de pesquisa.类型可选字符串支持 HTML因此可以使用strong加粗关键词、br换行语义在标题下方以较小的字号显示的项目简介或提示文案。这里用一句休斯顿我们遇到问题了的幽默文案引导用户检查 URL 或使用搜索栏。在 packages/starlight/src/components/Hero.astro 的渲染逻辑中tagline通过set:html{tagline}注入 DOM字号由 CSSclamp(var(--sl-text-base), calc(0.0625rem 2vw), var(--sl-text-xl))控制颜色使用--sl-color-gray-2确保与当前主题色系统联动。4.3actions行动按钮组actions: - text: Ir para o início icon: right-arrow link: /pt-br/ variant: primaryactions是按钮数组每个按钮支持以下字段见 packages/starlight/src/schemas/hero.ts字段类型说明text字符串必填按钮上显示的文本link字符串必填按钮href值支持站内路径如/pt-br/或外部 URLvariantprimary/secondary/minimal按钮样式默认primaryicon内置图标名或内联svg显示在链接文字旁的图标本仓库中right-arrow是 Starlight 内置图标之一定义见 packages/starlight/src/components-internals/Icons.tsattrs对象附加到链接上的 HTML 属性如class、target等pt-br/404.md中配置的Ir para o início回到首页按钮使用primary强调样式 right-arrow图标指向葡萄牙语站点的首页/pt-br/——注意多语言站点中链接必须带上语言前缀而英文版 404 的对应配置则指向/。4.4 hero 渲染细节Hero.astro 完整演示了 hero 的渲染管线支持image字段file相对路径、dark/light双主题图片或html原始 HTML 三种形式404 页面未使用标题渲染为带idmain-content语义的h1对应常量PAGE_TITLE_ID保证可访问性锚点按钮渲染复用LinkButton组件桌面端min-width: 50rem采用7fr 4fr双栏网格移动端单栏居中——这些响应式规则都定义在Hero.astro内联样式层starlight.core中。五、editUrl: false与lastUpdated: false的含义frontmatter 中这两行同样有明确语义editUrl: false关闭本页的编辑此页链接。404 页面本质是错误提示页指向源码编辑链接没有意义因此显式禁用。字段定义见 packages/starlight/src/schema.ts 中的editUrl: z.union([z.url(), z.boolean()]).optional().default(true)——默认为true继承全局editLink.baseUrl配置传false可逐页关闭。lastUpdated: false关闭本页的最后更新时间显示。同理错误页不应展示时间戳。这两个字段展示了 Starlight 的全局配置可被页面级 frontmatter 覆盖的设计原则全局开启的能力可以在任意单页上按需关闭。六、多语言站点的 404回退与翻译系统Starlight 的多语言站点中每个语言目录都可放置自己的404.md。若某个语言没有提供框架还有一层内置兜底各语言翻译文件如 packages/starlight/src/translations/en.json、packages/starlight/src/translations/pt.json中的404.text键定义了默认 404 提示文案该键在 packages/starlight/src/schemas/i18n.ts 中声明并在 packages/starlight/src/global.ts 中通过Astro.locals.t(404.text)暴露给全局模板。因此自定义 404 页面的推荐做法是优先用hero块构建品牌化的 404 体验如本样本所示把翻译系统保留为未覆盖语言时的兜底方案。七、扩展如何完全关闭内置 404 路由如果你希望完全接管 404 处理例如在边缘层自定义可以在astro.config.mjs的 Starlight 配置中设置starlight({ title: My Docs, disable404Route: true, // ... })当disable404Route为true时packages/starlight/src/index.ts 中的injectRoute注入逻辑会被跳过不再生成内置 404 页面。反之默认情况只要你的内容集合里存在404.md它就自动成为站点 404 页。八、实践要点小结对照pt-br/404.md这个真实样本自定义 Starlight 404 页面时可以沉淀以下经验文件命名与位置在每个语言目录下放置404.md如docs/src/content/docs/pt-br/404.md无需手动配置路由布局选择template: splash去掉侧边栏让错误提示更聚焦需要标准文档布局时保留默认doc内容即配置整个页面通过hero.title、hero.tagline、hero.actions驱动无需撰写正文 Markdown回链要带语言前缀多语言站点中按钮link指向对应语言首页如/pt-br/英文根站则指向/关闭无意义的 UIeditUrl: false、lastUpdated: false避免在错误页出现编辑链接与时间戳兜底机制未提供 404 文档的语言会自动回退到翻译文件中的404.text默认文案。相关实现与配置文件的完整路径索引index.ts404 路由注入、static/404.astro 与 ssr/404.astro双模式路由、schema.tstemplate/editUrl/lastUpdated字段定义、hero.tshero 完整 schema、Hero.astro渲染实现、Page.astrosplash 布局影响与 404 页面的 pagefind 排除逻辑。赞分享文档前端开发工具【免费下载链接】starlight Build beautiful, accessible, high-performance documentation websites with Astro项目地址https://gitcode.com/gh_mirrors/st/starlight点击查看免费下载相关推荐2019 年 GraphiQL 第二次工作组会议议程解析插件系统、可复用 UI 包与 LSP/编辑器技术选型的历史起点2019 年 GraphiQL 第二次工作组会议议程解析插件系统、可复用 UI 包与 LSP/编辑器技术选型的历史起点 本文围绕 working group/文档前端开发工具Starlight 404 页面定制指南用 splash 模板与 hero 构建多语言错误页Starlight 404 页面定制指南用 splash 模板与 hero 构建多语言错误页 本篇技术指南以 Starlight 官方文档站中 印地语 404文档前端开发工具Iosevka 25.1.0 发布说明深度解析新增字符、字符变体覆盖扩展与风格集赋值修复Iosevka 25.1.0 发布说明深度解析新增字符、字符变体覆盖扩展与风格集赋值修复 Iosevka 是一款由代码编写的代码字体Versatile文档前端开发工具上一篇从部署到跑通 RAG 问答与知识图谱Yuxi 多租户智能体平台完整指南下一篇AutoCAD字体管家三步搞定字体缺失设计效率提升300%创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
网站建设高端定制企业官网
RELATED

相关资讯

更多精彩内容,欢迎继续阅读

较早相关资讯

最新相关资讯

【外设】之大彩串口显示屏 2026/11/15 4:54:16

【外设】之大彩串口显示屏

大彩串口屏初步使用 1 .官网下载 STM32 屏幕 GUI 设计资料 http://www.gz-dc.com/category/typeid/4112 找到 STM32 Keil 工程,移植相关代码因项目而异进行移植,由于项目简单,本人只对用到的指令接口进行修改。 比如:注意事项&…

阅读更多 →
无法下载Windows系统iso文件 2026/11/15 2:04:12

无法下载Windows系统iso文件

当我遇到这个问题的时候,我打开了一个网站: 登录 然后我打算下载的时候: 突然那个官方的连接就可以下载了:

阅读更多 →
【清华代码熊】DeepSeek V4.1 Flash 后训练详解 2026/11/14 10:11:15

【清华代码熊】DeepSeek V4.1 Flash 后训练详解

📌 上期解析了 DeepSeek V4.1 Flash 模型架构改进,本期解析 DeepSeek V4.1 Flash 预训练/后训练技术: 🌟 预训练:45T 文本 多模态混合语料、直接训练 sparse attention(取消 DeepSeek V4 的 dense 冷启动&…

阅读更多 →
Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ... 2026/11/16 6:47:19

Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ...

文章主要内容和创新点 主要内容 本文聚焦于多模态大语言模型(MLLM)强化学习(RL)训练中的效率问题,提出了一个名为Shuffle-R1的框架。研究发现,当前RL训练存在两个关键缺陷: 优势值坍缩(Advantage Collapsing):批次中大多数优势值集中在零附近,导致有效梯度信号被淹…

阅读更多 →
PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction 2026/11/14 16:35:50

PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction

一、文章主要内容总结 本文聚焦于利用大型语言模型(LLMs)实现个人身份信息(PII)脱敏的研究,旨在解决传统脱敏方法(如基于规则的系统、领域特定命名实体识别(NER)模型)泛化能力差、跨格式/跨语境适应性弱的问题。 研究通过全面评估多种LLM架构(包括密集型LLM(D-LLM…

阅读更多 →
LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model 2026/11/16 17:28:18

LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model

文章主要内容和创新点 主要内容 本文聚焦于二进制图像-文本相关性评估任务(判断图像与文本“相关”或“不相关”),针对该任务中文本格式多样、相关性定义随场景变化等挑战,提出了基于多模态大语言模型(MLLM)的解决方案LLaVA-RE。 模型设计:LLaVA-RE基于LLaVA 1.5架构,…

阅读更多 →

今日资讯

本周资讯

本月资讯

看完文章仍有疑问?

联系尧图顾问,获取一对一建站咨询

立即免费咨询 📞 400-888-8888
📞 ✉