Astro 구성

콘텐츠 저장소는 자체적인 astro.config.mjs를 유지하지 않습니다. 대신, @f5-sales-demo/docs-theme npm 패키지에서 구성 팩토리를 가져와 Starlight, 8개의 번들 플러그인, 그리고 모든 테마 기본값이 포함된 완전한 Astro 구성을 반환합니다.

테마 사용하기

콘텐츠 저장소의 astro.config.mjs(Docker 빌더가 제공)는 얇은 래퍼입니다:

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

export default createF5xcDocsConfig();

모든 사용자 정의는 옵션 객체 또는 환경 변수를 통해 이루어집니다. 플러그인 연결, CSS 가져오기, 또는 구성 요소 재정의를 직접 수정할 필요가 없습니다.

구성 옵션

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

옵션	기본값 / 환경 변수 폴백	목적
`site`	`DOCS_SITE` 또는 `https://f5-sales-demo.github.io`	정식 기본 URL
`base`	`DOCS_BASE` 또는 `/`	프로젝트 사이트의 URL 기본 경로
`title`	`DOCS_TITLE` 또는 `Documentation`	헤더 및 브라우저 탭의 사이트 제목
`description`	`DOCS_DESCRIPTION` 또는 빈 문자열	메타데이터 및 llms.txt를 위한 사이트 설명
`githubRepository`	`GITHUB_REPOSITORY` 또는 빈 문자열	편집 링크 및 GitHub 소셜 아이콘 활성화
`llmsOptionalLinks`	`LLMS_OPTIONAL_LINKS` (JSON) 또는 `[]`	llms.txt 플러그인을 위한 추가 링크
`additionalIntegrations`	`[]`	추가할 추가 Astro 통합
`additionalRemarkPlugins`	`[]`	remark-mermaid 이후에 추가되는 추가 remark 플러그인
`megaMenuItems`	내장 Products/Solutions/Docs/Support 메뉴	최상위 메가 메뉴 항목
`head`	Mermaid CDN `<script>` 태그	사용자 정의 `<head>` 항목
`logo`	`@f5-sales-demo/docs-theme/assets/github-avatar.png`	사이드바 로고 (단일 src 또는 라이트/다크 쌍)

번들된 Starlight 플러그인

팩토리는 8개의 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-icons`	Starlight에서 아이콘 지원
`starlight-llms-txt`	LLM 사용을 위한 `llms.txt` 및 `llms-full.txt` 생성

이들은 config.ts 내부에서 순서대로 등록됩니다. 테마 플러그인(@f5-sales-demo/docs-theme)은 이 목록에서 실행되는 Starlight 플러그인 자체입니다.

테마 플러그인 훅

테마 플러그인은 index.ts에 정의되어 있으며 위의 번들 플러그인 중 하나로 등록됩니다. config:setup 훅은 세 가지 작업을 수행합니다:

CSS 주입 — Starlight의 customCss 배열에 fonts/font-face.css와 styles/custom.css를 앞에 추가합니다
구성 요소 재정의 — 다섯 개의 Starlight 구성 요소를 교체합니다:
- Banner — 편집 링크가 있는 브레드크럼 내비게이션
- EditLink — 의도적으로 비워둠 (편집 링크는 Banner에 위치)
- Footer — 기본 푸터 아래에 소셜 미디어 링크 추가
- SiteTitle — 홈 링크가 있는 로고
- MarkdownContent — 동영상 및 이미지 확대를 활성화하는 래퍼
라우트 미들웨어 추가 — 사이드바에서 인덱스 페이지를 필터링하고 인덱스 페이지의 목차를 숨기는 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 맵을 통해 해석됩니다.

기타 통합

Starlight 및 해당 플러그인 외에도 팩토리는 다음을 등록합니다:

@astrojs/react — MDX 페이지에서 React 구성 요소 지원을 활성화합니다
remark-mermaid — ```mermaid 코드 블록을 렌더링된 다이어그램으로 변환하는 사용자 정의 remark 플러그인입니다

추가 통합 및 remark 플러그인은 additionalIntegrations 및 additionalRemarkPlugins 옵션을 통해 추가할 수 있습니다.

사이드바

사용자 정의 사이드바는 정의되지 않습니다. Starlight는 docs/의 파일 구조에서 사이드바를 자동으로 생성하며, 각 페이지의 title 프론트매터를 링크 텍스트로 사용하고 sidebar.order로 정렬합니다. 라우트 미들웨어는 인덱스 페이지를 사이드바에서 자동으로 필터링합니다.