跳转到内容
Theme

Astro 配置

内容仓库不维护自己的 astro.config.mjs。取而代之，它们从 @f5-sales-demo/docs-theme npm 包中导入一个配置工厂，该工厂会返回一个完整的 Astro 配置，其中包含 Starlight、八个内置插件以及所有主题默认值。

使用主题

Section titled “使用主题”

内容仓库的 astro.config.mjs（由 Docker 构建器提供）是一个轻量包装器：

import { createF5xcDocsConfig } from '@f5-sales-demo/docs-theme/config';


export default createF5xcDocsConfig();

所有自定义均通过选项对象或环境变量完成——无需手动处理插件连接、CSS 导入或组件覆盖。

配置选项

Section titled “配置选项”

createF5xcDocsConfig 接受一个 F5xcDocsConfigOptions 对象。每个字段均为可选；环境变量和合理的默认值会自动填充缺失项。

interface F5xcDocsConfigOptions {
  site?: string;
  base?: string;
  title?: string;
  description?: string;
  githubRepository?: string;
  llmsOptionalLinks?: Array<{ title: string; url: string }>;
  additionalIntegrations?: AstroIntegration[];
  additionalRemarkPlugins?: Array<unknown>;
  megaMenuItems?: MegaMenuItem[];
  head?: HeadEntry[];
  logo?: { src: string } | { light: string; dark: string };
}
选项默认值 / 环境变量回退用途
siteDOCS_SITE 或 https://f5-sales-demo.github.io规范基础 URL
baseDOCS_BASE 或 /项目站点的 URL 基础路径
titleDOCS_TITLE 或 Documentation页眉和浏览器标签页中的站点标题
descriptionDOCS_DESCRIPTION 或空字符串用于元数据和 llms.txt 的站点描述
githubRepositoryGITHUB_REPOSITORY 或空字符串启用编辑链接和 GitHub 社交图标
llmsOptionalLinksLLMS_OPTIONAL_LINKS（JSON）或 []llms.txt 插件的附加链接
additionalIntegrations[]追加的额外 Astro 集成
additionalRemarkPlugins[]在 remark-mermaid 之后添加的额外 remark 插件
megaMenuItems内置的产品/解决方案/文档/支持菜单顶级超级菜单条目
headMermaid CDN <script> 标签自定义 <head> 条目
logo@f5-sales-demo/docs-theme/assets/github-avatar.png侧边栏 Logo（单个 src 或明暗模式对）

内置 Starlight 插件

Section titled “内置 Starlight 插件”

该工厂会自动连接八个 Starlight 插件：

插件用途
starlight-mega-menu支持网格/列表布局的顶部导航超级菜单
starlight-videos在文档页面中嵌入视频
starlight-image-zoom点击图片放大
@f5-sales-demo/docs-theme（自身）CSS 注入、组件覆盖、路由中间件
starlight-scroll-to-top带进度环的回到顶部按钮
starlight-heading-badges标题上的徽章注释
starlight-page-actions页面操作按钮
starlight-plugin-iconsStarlight 中的图标支持
starlight-llms-txt生成供 LLM 使用的 llms.txt 和 llms-full.txt

这些插件按顺序在 config.ts 中注册。主题插件（@f5-sales-demo/docs-theme）本身也是一个 Starlight 插件，并在此列表中运行。

主题插件钩子

Section titled “主题插件钩子”

主题插件在 index.ts 中定义，并在上述内置插件列表中注册。其 config:setup 钩子完成三件事：

  1. 注入 CSS — 将 fonts/font-face.css 和 styles/custom.css 前置到 Starlight 的 customCss 数组
  2. 覆盖组件 — 替换五个 Starlight 组件：
    • Banner — 带编辑链接的面包屑导航
    • EditLink — 故意留空（编辑链接位于 Banner 中）
    • Footer — 在默认页脚下方追加社交媒体链接
    • SiteTitle — 带主页链接的 Logo
    • MarkdownContent — 启用视频和图片缩放的包装器
  3. 添加路由中间件 — 注册 route-middleware.ts，用于从侧边栏过滤索引页面，并在索引页面上禁用目录
// index.ts — Starlight plugin entry point
export default function f5xcDocsTheme(): StarlightPlugin {
  return {
    name: '@f5-sales-demo/docs-theme',
    hooks: {
      'config:setup'({ config, updateConfig, addRouteMiddleware }) {
        addRouteMiddleware({
          entrypoint: '@f5-sales-demo/docs-theme/route-middleware',
          order: 'pre',
        });
        updateConfig({
          customCss: [
            ...(config.customCss ?? []),
            '@f5-sales-demo/docs-theme/fonts/font-face.css',
            '@f5-sales-demo/docs-theme/styles/custom.css',
          ],
          components: {
            ...config.components,
            Banner: '@f5-sales-demo/docs-theme/components/Banner.astro',
            EditLink: '@f5-sales-demo/docs-theme/components/EditLink.astro',
            Footer: '@f5-sales-demo/docs-theme/components/Footer.astro',
            SiteTitle: '@f5-sales-demo/docs-theme/components/SiteTitle.astro',
            MarkdownContent: '@f5-sales-demo/docs-theme/components/MarkdownContent.astro',
          },
        });
      },
    },
  };
}

所有路径均使用 npm 包说明符（例如 @f5-sales-demo/docs-theme/styles/custom.css），通过 package.json 中的 exports 映射进行解析。

其他集成

Section titled “其他集成”

除 Starlight 及其插件外，该工厂还注册了：

  • @astrojs/react — 在 MDX 页面中启用 React 组件支持
  • remark-mermaid — 自定义 remark 插件，将 ```mermaid 代码块转换为渲染后的图表

额外的集成和 remark 插件可通过 additionalIntegrations 和 additionalRemarkPlugins 选项追加。

侧边栏

Section titled “侧边栏”

未定义自定义侧边栏。Starlight 根据 docs/ 中的文件结构自动生成侧边栏，使用每个页面的 title frontmatter 作为链接文本，sidebar.order 用于排序。路由中间件会自动将索引页面从侧边栏中过滤掉。