빌드 파이프라인

이 페이지는 콘텐츠 저장소가 @f5-sales-demo/docs-theme npm 패키지를 사용하여 완전히 브랜딩된 문서 사이트를 생성하는 방법을 설명합니다.

아키텍처

┌─────────────────┐
│  Content Repo   │
│  (docs/ folder) │
└────────┬────────┘
         │
         ▼
┌───────────────────────────┐
│   f5xc-docs-builder       │
│   (Docker image)          │
│                           │
│  npm install              │
│  @f5-sales-demo/docs-theme ─────┐  │
│                        ▼  │
│  node_modules/            │
│    @f5-sales-demo/docs-theme/       │
│      ├── config.ts        │
│      ├── index.ts         │
│      ├── fonts/           │
│      ├── styles/          │
│      ├── assets/          │
│      └── components/      │
│                           │
│  Astro Build              │
└─────────────┬─────────────┘
              ▼
┌───────────────────────────┐
│   Astro Build Output      │
│   (static HTML/CSS)       │
└─────────────┬─────────────┘
              ▼
┌───────────────────────────┐
│   GitHub Pages            │
└───────────────────────────┘

빌드 프로세스 단계별 설명

콘텐츠 저장소 푸시 — main으로의 푸시(또는 수동 디스패치)가 GitHub Pages 배포 워크플로를 트리거합니다

재사용 가능한 워크플로 — 콘텐츠 저장소의 워크플로가 빌더를 호출합니다:

jobs:
  docs:
    uses: f5-sales-demo/docs-control/.github/workflows/github-pages-deploy.yml@main

Docker 빌더 실행 — f5xc-docs-builder Docker 이미지에는 npm을 통해 테마가 미리 설치되어 있습니다. 빌드 시:
- node_modules/@f5-sales-demo/docs-theme/에서 astro.config.mjs와 content.config.ts를 Astro 프로젝트 루트로 복사합니다
- 콘텐츠 저장소의 docs/ 파일을 src/content/docs/로 복사합니다
Astro 빌드 — Astro가 createF5xcDocsConfig()를 호출하는 설정을 읽습니다. 팩토리는 npm 패키지 지정자(예: @f5-sales-demo/docs-theme/styles/custom.css)를 통해 모든 테마 에셋을 해석합니다
배포 — 빌드된 정적 사이트가 GitHub Pages에 배포됩니다

콘텐츠 저장소 요구 사항

콘텐츠 저장소에는 다음만 필요합니다:

Markdown(.md) 또는 MDX(.mdx) 파일이 포함된 docs/ 디렉터리
빌더를 호출하는 GitHub Actions 워크플로

최소 워크플로

name: GitHub Pages Deploy
on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  docs:
    uses: f5-sales-demo/docs-control/.github/workflows/github-pages-deploy.yml@main

이것은 이 테마 저장소 자체에서 현재 읽고 있는 문서를 빌드하는 데 사용하는 것과 동일한 워크플로입니다.

경로 해석

테마의 모든 경로는 package.json의 exports 맵을 통해 해석되는 npm 패키지 지정자를 사용합니다:

// CSS — node_modules에서 해석
'@f5-sales-demo/docs-theme/fonts/font-face.css'
'@f5-sales-demo/docs-theme/styles/custom.css'

// Components — node_modules에서 해석
'@f5-sales-demo/docs-theme/components/Footer.astro'
'@f5-sales-demo/docs-theme/components/Banner.astro'

// Assets — node_modules에서 해석
'@f5-sales-demo/docs-theme/assets/github-avatar.png'

빌드 워크스페이스에는 ./theme/ 디렉터리가 없습니다. Docker 빌더는 테마를 일반 npm 의존성으로 설치하고, Astro는 node_modules를 통해 모든 지정자를 해석합니다.

변경 사항 전파

테마 변경 사항은 npm 패키지 업데이트를 통해 전파됩니다:

@f5-sales-demo/docs-theme의 main에 변경 사항이 병합됩니다
Docker 빌더 이미지가 업데이트된 패키지로 재빌드됩니다
다음에 콘텐츠 저장소의 워크플로가 실행될 때 업데이트된 빌더 이미지를 사용합니다
Astro 빌드가 업데이트된 폰트, 스타일, 로고, 구성 요소, 플러그인을 반영합니다
콘텐츠 저장소의 사이트가 새로운 테마로 배포됩니다

콘텐츠 저장소는 항상 Docker 이미지에 번들된 최신 테마를 사용합니다. 이를 통해 모든 사이트에서 시각적 일관성이 보장되지만, 테마 변경 사항은 병합 전에 신중하게 테스트해야 함을 의미합니다.