RelatedArticles 相关文章组件

发表于 2026-04-19

最后修改 2026-07-11

阅读量 —

RelatedArticles 组件在每篇文档页面的底部（位于"提出问题或修改建议"与"Updated at"之上）自动渲染一组相关文章链接。链接定义在页面的 frontmatter 中，不需要在正文中手动写链接，保持内容整洁。

本页面自身的 frontmatter 就写了三种形式的条目，滚动到页面底部即可看到实际渲染效果。

基本用法（推荐：字符串简写）

只需在页面 frontmatter 中添加 relatedArticles 数组即可，正文中无需任何标签——主题已经在 doc-footer-before 槽中自动挂载该组件。

站内文章推荐直接写链接字符串，组件会自动从目标页 frontmatter 读取 title 和 description 并展示：

---
title: 我的文章
relatedArticles:
  - /work-visas/resource/supervisor-choice.md
  - /life-in-atomeocean/legal-conflict/h1b-related/wage-level-determination.md
---

链接书写约定

• 站内链接一律使用从站点根开始的路径（即去掉 docs/zhHans 前缀后的路径），如 /work-visas/h1b/before-we-begin.md。
• 不要带 /zhHans 前缀，字符串形式不要带 #锚点 或 ?参数。
• .md 后缀写不写都可以，组件会自动去掉。
• 不符合约定或指向不存在页面的链接不会报错，只会把路径本身当作标题展示——看到路径出现在相关文章列表里，就说明该链接需要修正。
• 目标页 frontmatter 没有 title 时同样回退为展示路径，给目标页补上 title: 即可。

对象形式

需要自定义显示文字、添加分类标签或链接到外部网站时，使用对象形式：

relatedArticles:
  # 省略 title：标题/描述仍自动解析，同时可以加分类标签
  - href: /guide/contribute-note/component-usage/reference-source.md
    category: 组件用法
  # 显式 title：完全按书写内容渲染，不会自动带出目标页描述
  - title: Supervisor选择
    href: /work-visas/resource/supervisor-choice.md
    category: 合规与流程
  # 外部链接：必须写 title
  - title: USCIS 官网
    href: https://www.uscis.gov/

Frontmatter 字段说明

条目可以是链接字符串，也可以是包含以下字段的对象：

字段	类型	必填	说明
href	String	是	目标页面路径（根路径，可带 .md 后缀）或外部 URL
title	String	否	链接显示文字；省略时自动读取目标页 frontmatter 的 title
description	String	否	标题下方的描述文字；仅在未显式指定 title 时自动读取目标页 description
category	String	否	分类标签，显示在条目旁边

注意事项

• 如果 relatedArticles 不存在或为空数组，组件不会渲染任何内容。
• 条目按 frontmatter 中的顺序平铺展示，category 以标签形式显示在条目内，不会分组。
• 该组件已全局注册，并由主题自动挂载在每篇文档底部，作者无需在 markdown 正文中添加任何标签。
• 标题/描述在构建时解析，修改目标页 frontmatter 后引用它的页面会自动更新。

重构方法

如果使用网页版LLM工具，只允许复制信息，不能跨多个文件，可以复制下面的信息

请修改下面的markdown，把正文里的"相关文章"链接列表改为 frontmatter 的 relatedArticles 字段。
站内链接直接写链接字符串即可（无需 title，组件会自动解析标题）。
类似的例子
## 相关文章

1. [Atomeocean 稳定H1b合作开始之前](/work-visas/h1b/before-we-begin.md)
修改如下
relatedArticles:
  - /work-visas/h1b/before-we-begin.md