สถาปัตยกรรม

ภาพรวม

ตัวสร้างเอกสาร (docs builder) เป็นระบบ Astro + Starlight ที่ทำงานในคอนเทนเนอร์ รีโปเนื้อหาจัดเตรียมไฟล์ Markdown/MDX ส่วนตัวสร้างจัดเตรียมเฟรมเวิร์ก ธีม และลอจิกการ build ทั้งสองส่วนมาพบกันในเวลา build ภายในคอนเทนเนอร์ Docker

โมเดลการนำเข้าเนื้อหา

รีโปเนื้อหาเก็บเอกสารไว้ในไดเรกทอรี docs/ ในเวลา build คอนเทนเนอร์จะคัดลอกไฟล์เหล่านั้นไปยัง src/content/docs/ ซึ่ง content collection ของ Astro จะนำไปใช้งาน

content-repo/
  docs/           ← เขียนโดยทีมเนื้อหา
    index.mdx
    guide.mdx

docs-builder/
  src/content/docs/ ← ว่างเปล่าในสภาวะปกติ (.gitkeep)

สคริปต์ entrypoint (docker/entrypoint.sh) ทำการคัดลอก:

cp -r "$CONTENT_DIR"/* /app/src/content/docs/

ซึ่งหมายความว่ารีโปตัวสร้างจะมีไดเรกทอรี src/content/docs/ ที่ว่างเปล่า เนื้อหาจะปรากฏเฉพาะในเวลา build เท่านั้น

ระบบธีม

ธีม Starlight ถูกเผยแพร่เป็นแพ็กเกจ npm แยกต่างหาก package.json ใช้ npm alias เพื่อแมปชื่อย่อไปยังแพ็กเกจในรีจิสทรีที่กำหนดขอบเขต:

"@f5-sales-demo/docs-theme": "^1.29.0"

แพ็กเกจธีมเป็นเจ้าของ astro.config.mjs ในเวลา build สคริปต์ entrypoint จะคัดลอกไปยังรูทของโปรเจกต์:

cp /app/node_modules/@f5-sales-demo/docs-theme/astro.config.mjs /app/astro.config.mjs

วิธีนี้ทำให้การกำหนดค่ารวมศูนย์อยู่ที่เดียว — รีโปเนื้อหาและตัวสร้างเองไม่ต้องดูแลไฟล์ Astro config ของตัวเอง

โครงสร้างไดเรกทอรีซอร์สโค้ด

src/
  components/
    PlaceholderForm.tsx          # ฟอร์ม React สำหรับแก้ไขค่า placeholder
    PlaceholderFormWrapper.astro # Astro wrapper โหลดสคริปต์ DOM และ CSS ส่วนกลาง
  content/
    docs/                        # จุดเมาท์สำหรับเนื้อหาที่นำเข้า
  content.config.ts              # คำจำกัดความ content collection ของ Starlight
  data/
    placeholders.json            # คำจำกัดความโทเค็น placeholder
  lib/
    placeholder-store.ts         # การจัดการ state: โหลด บันทึก คำนวณ ส่งเหตุการณ์
  scripts/
    placeholder-dom.ts           # DOM walker ฝั่งไคลเอนต์ และตัวเรนเดอร์ Mermaid

Content Collection

src/content.config.ts กำหนดคอลเลกชัน docs เดียวโดยใช้ loader และ schema ของ Starlight:

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};

ไฟล์ .md หรือ .mdx ใดๆ ที่วางไว้ใน src/content/docs/ จะกลายเป็นหน้าหนึ่งในเว็บไซต์ที่ build แล้ว

ขั้นตอนการ Build

แผนภาพต่อไปนี้แสดง pipeline การ build ตั้งแต่ต้นจนจบเมื่อคอนเทนเนอร์ Docker ทำงาน:

flowchart LR
    A[Content Repo<br/>docs/] -->|mount| B[Container<br/>/content/docs]
    B -->|entrypoint.sh<br/>cp| C[src/content/docs/]
    D[npm registry] -->|npm install| E[node_modules/<br/>@f5-sales-demo/docs-theme]
    E -->|cp astro.config| F[astro.config.mjs]
    C --> G[astro build]
    F --> G
    G --> H[dist/<br/>static HTML]
    H -->|cp| I[/output]

การประมวลผลเวลา Build เทียบกับเวลาไคลเอนต์

ข้อกังวล	เมื่อไหร่	อย่างไร
MDX → HTML	เวลา build	คอมไพเลอร์ Astro
บล็อกโค้ด Mermaid → container divs	เวลา build	ปลั๊กอิน remark-mermaid.mjs (จาก docs-theme)
โทเค็น placeholder → span แบบโต้ตอบได้	เวลาไคลเอนต์	TreeWalker ของ placeholder-dom.ts
การเรนเดอร์ Mermaid SVG	เวลาไคลเอนต์	mermaid CDN import ใน placeholder-dom.ts
state ของฟอร์ม placeholder	เวลาไคลเอนต์	placeholder-store.ts + localStorage
การเปลี่ยนหน้า Astro	เวลาไคลเอนต์	event listener ของ astro:page-load