Docusaurus 配置

主配置文件

docusaurus.config.ts 为站点核心配置，以下为与日常维护相关的字段。

站点基本信息

字段	当前值	说明
title	BU CSSA 技术部文档站	浏览器标题、OG 标题
tagline	技术部官方文档中心	首页副标题
favicon	img/bucssalogo.png	位于 static/img/
url	生产域名	部署前需改为实际 URL
baseUrl	/	子路径部署时修改

Markdown 与 Mermaid

markdown: {
  mermaid: true,
},
themes: ['@docusaurus/theme-mermaid'],

启用后，任意 docs/blog 的 Markdown 代码块语言设为 mermaid 即可渲染图表。

国际化

i18n: {
  defaultLocale: 'zh-Hans',
  locales: ['zh-Hans', 'en'],
},

locale	说明
zh-Hans	默认语言，主文档源
en	英文，翻译文件在 i18n/en/

Docs 插件

选项	值	说明
sidebarPath	./sidebars.ts	侧边栏定义
lastVersion	current	默认打开的版本
versions.current.label	Current	版本下拉显示名
versions.v1.label	V1.0	历史版本

Blog 插件

选项	说明
routeBasePath: 'blog'	Blog 路由前缀
showReadingTime: true	显示阅读时间
feedOptions.type	RSS + Atom

themeConfig 要点

Navbar

• 文档：docSidebar，sidebarId docs
• Blog：链至 /blog
• 版本下拉：docsVersionDropdown
• 语言切换：localeDropdown

Footer

「相关链接」列出 BUCSSA 官网、Portal、网盘、抽奖、GPT 等外部 URL。

其他

选项	值
onBrokenLinks	warn
colorMode.respectPrefersColorScheme	true
future.v4	true（Docusaurus v4 兼容）

Wrangler 配置

wrangler.jsonc：

字段	值	说明
name	bucssa-documentation	Workers 服务名
assets.directory	build	指向 Docusaurus 构建输出
compatibility_date	日期	Workers 运行时兼容日期

修改配置的注意点

• 修改 docusaurus.config.ts 后需重启 dev server
• 修改 url / baseUrl 会影响 sitemap 与 canonical URL
• editUrl 当前仍指向 Docusaurus 模板地址，建议改为本仓库 GitHub 路径以便「编辑此页」功能