Astro Configuration

Content repositories do not maintain their own astro.config.mjs. Instead, they import a configuration factory from the @f5xc-salesdemos/docs-theme npm package that returns a complete Astro config with Starlight, eight bundled plugins, and all theme defaults.

Consuming the Theme

A content repo’s astro.config.mjs (provided by the Docker builder) is a thin wrapper:

import { createF5xcDocsConfig } from '@f5xc-salesdemos/docs-theme/config';

export default createF5xcDocsConfig();

All customization is done through the options object or environment variables — there is no need to touch plugin wiring, CSS imports, or component overrides.

Configuration Options

createF5xcDocsConfig accepts an F5xcDocsConfigOptions object. Every field is optional; environment variables and sensible defaults fill in the gaps.

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 };
}

Option	Default / Env Fallback	Purpose
`site`	`DOCS_SITE` or `https://f5xc-salesdemos.github.io`	Canonical base URL
`base`	`DOCS_BASE` or `/`	URL base path for project sites
`title`	`DOCS_TITLE` or `Documentation`	Site title in header and browser tab
`description`	`DOCS_DESCRIPTION` or empty string	Site description for metadata and llms.txt
`githubRepository`	`GITHUB_REPOSITORY` or empty string	Enables edit links and GitHub social icon
`llmsOptionalLinks`	`LLMS_OPTIONAL_LINKS` (JSON) or `[]`	Additional links for the llms.txt plugin
`additionalIntegrations`	`[]`	Extra Astro integrations to append
`additionalRemarkPlugins`	`[]`	Extra remark plugins added after remark-mermaid
`megaMenuItems`	Built-in Products/Solutions/Docs/Support menu	Top-level mega menu entries
`head`	Mermaid CDN `<script>` tag	Custom `<head>` entries
`logo`	`@f5xc-salesdemos/docs-theme/assets/github-avatar.png`	Sidebar logo (single src or light/dark pair)

Bundled Starlight Plugins

The factory wires up eight Starlight plugins automatically:

Plugin	Purpose
`starlight-mega-menu`	Top navigation mega menu with grid/list layouts
`starlight-videos`	Embed videos in documentation pages
`starlight-image-zoom`	Click-to-zoom on images
`@f5xc-salesdemos/docs-theme` (self)	CSS injection, component overrides, route middleware
`starlight-scroll-to-top`	Scroll-to-top button with progress ring
`starlight-heading-badges`	Badge annotations on headings
`starlight-page-actions`	Page action buttons
`starlight-plugin-icons`	Icon support in Starlight
`starlight-llms-txt`	Generates `llms.txt` and `llms-full.txt` for LLM consumption

These are registered in order inside config.ts. The theme plugin (@f5xc-salesdemos/docs-theme) is itself a Starlight plugin that runs in this list.

Theme Plugin Hook

The theme plugin is defined in index.ts and registered among the bundled plugins above. Its config:setup hook does three things:

Injects CSS — prepends fonts/font-face.css and styles/custom.css to Starlight’s customCss array
Overrides components — replaces five Starlight components:
- Banner — breadcrumb navigation with edit link
- EditLink — intentionally empty (edit link lives in Banner)
- Footer — social media links appended below default footer
- SiteTitle — logo with home link
- MarkdownContent — wrapper enabling videos and image zoom
Adds route middleware — registers route-middleware.ts which filters index pages from the sidebar and suppresses the table of contents on index pages

// index.ts — Starlight plugin entry point
export default function f5xcDocsTheme(): StarlightPlugin {
  return {
    name: '@f5xc-salesdemos/docs-theme',
    hooks: {
      'config:setup'({ config, updateConfig, addRouteMiddleware }) {
        addRouteMiddleware({
          entrypoint: '@f5xc-salesdemos/docs-theme/route-middleware',
          order: 'pre',
        });
        updateConfig({
          customCss: [
            ...(config.customCss ?? []),
            '@f5xc-salesdemos/docs-theme/fonts/font-face.css',
            '@f5xc-salesdemos/docs-theme/styles/custom.css',
          ],
          components: {
            ...config.components,
            Banner: '@f5xc-salesdemos/docs-theme/components/Banner.astro',
            EditLink: '@f5xc-salesdemos/docs-theme/components/EditLink.astro',
            Footer: '@f5xc-salesdemos/docs-theme/components/Footer.astro',
            SiteTitle: '@f5xc-salesdemos/docs-theme/components/SiteTitle.astro',
            MarkdownContent: '@f5xc-salesdemos/docs-theme/components/MarkdownContent.astro',
          },
        });
      },
    },
  };
}

All paths use npm package specifiers (e.g., @f5xc-salesdemos/docs-theme/styles/custom.css) which resolve through the exports map in package.json.

Other Integrations

Beyond Starlight and its plugins, the factory also registers:

@astrojs/react — enables React component support in MDX pages
remark-mermaid — custom remark plugin that converts ```mermaid code blocks into rendered diagrams

Additional integrations and remark plugins can be appended via the additionalIntegrations and additionalRemarkPlugins options.

No custom sidebar is defined. Starlight auto-generates the sidebar from the file structure in docs/, using each page’s title frontmatter as the link text and sidebar.order for sorting. The route middleware filters index pages out of the sidebar automatically.