การเขียนเอกสาร

เว็บไซต์เอกสารถูกสร้างจาก markdown: โฟลเดอร์ content/ คือฐานข้อมูล สิ่งใดก็ตาม — คน สคริปต์ หรือ agent — ที่เขียนไฟล์ markdown ลงไปในนั้นคือการต่อขยายเว็บไซต์ หน้านี้คือข้อตกลง และส่วนประกอบทุกชิ้นด้านล่างถูกเรนเดอร์จริง มันจึงทำหน้าที่เป็นแผ่นตรวจสอบภาพไปด้วยในตัว

โครงสร้างโฟลเดอร์#

docs-site/content/
  getting-started/            # category = กลุ่มในแถบด้านข้าง
    _meta.json                # title, order, icon, description
    introduction.md           # page = รายการในแถบด้านข้าง
    quickstart.md
  api-reference/
    _meta.json
    ...

category เป็นตัวจัดลำดับแถบด้านข้าง ส่วนแต่ละหน้าจัดลำดับตัวเองภายใน category นั่นคือลำดับชั้นทั้งหมด — สองระดับ โดยเจตนา หาก category หนึ่งใหญ่เกินกว่ารายการแบบแบน ให้ขยาย build.ts ก่อน อย่าคิดวิธีเลี่ยงในตัวเนื้อหา

frontmatter ของหน้า#

---
title: Your first call          # จำเป็น — H1 ของหน้าและป้ายในแถบด้านข้าง
description: One-line summary.  # อยู่ใต้ H1 บนการ์ด และในการค้นหา
order: 2                        # การเรียงลำดับภายใน category
badge: new                      # ตัวเลือก: new | beta | soon
updated: 2026-09-09             # ตัวเลือก แสดงในแถว meta
---

เริ่มเนื้อหาของ body ที่ ## — H1 มาจาก frontmatter และหัวข้อ ##/### ป้อนให้แถบ “ในหน้านี้” โดยอัตโนมัติ

การเขียนเอกสารผลิตภัณฑ์อย่างซื่อตรง#

เอกสารเหล่านี้อธิบายผลิตภัณฑ์ตามที่มันเป็นอยู่ในวันนี้ ทุก endpoint รหัสข้อผิดพลาด ฟิลด์ และขีดจำกัดในหน้าใดหน้าหนึ่ง ต้องสืบย้อนไปถึงการทำงานจริงได้ — สำหรับรุ่นปัจจุบันหมายถึงเอกสารข้อตกลงใน backend/foundation/ (API-CONTRACT.md, PRODUCT-RUNTIME.md, SANDBOX-RUNTIME.md) หรือตัวโค้ด Go เอง หากคุณตรวจสอบข้อความใดไม่ได้ ให้ตัดออก

ความสามารถที่วางแผนไว้แต่ยังไม่ได้สร้างจะถูกทำเครื่องหมายไว้ ไม่ใช่เขียนราวกับว่ามันใช้งานได้แล้ว:

• ตั้ง badge: soon ใน frontmatter และ
• เปิดหน้าด้วย callout :::warning ที่ระบุว่าความสามารถนี้ยังใช้งานไม่ได้ และ
• อธิบายเพียงรูปร่างที่วางแผนไว้เท่านั้น — ไม่มีคำแนะนำทีละขั้นที่ทำให้เข้าใจว่ามันใช้งานได้แล้ววันนี้

หน้าที่ว่าด้วยความสามารถซึ่งยังไม่ได้เปิดใช้งานจะใช้แนวปฏิบัตินี้

ลิงก์#

ลิงก์ภายในเขียนแบบอ้างอิงจากรากของเอกสารและไม่มีนามสกุลไฟล์ — ตัว build จะเขียนใหม่ให้เข้ากับ mount path ใดก็ได้:

• ภายใน: [Quickstart](/getting-started/quickstart) → เริ่มต้นอย่างรวดเร็ว
• ภายนอก: URL ธรรมดา เปิดในแท็บใหม่ → แอป

callout#

มีสี่ชนิด ใช้ไวยากรณ์เดียวกัน: :::kind หัวข้อที่เป็นตัวเลือก … :::

บล็อกโค้ด#

fence รับชื่อภาษา บวกกับ title="…" ที่เป็นตัวเลือก ทุกบล็อกมีปุ่มคัดลอก

client = OpenAI(base_url="https://api.aigridapp.com/v1")  # สลับได้ในบรรทัดเดียว

{ "model": "openai/gpt-oss-20b", "stream": true }

ใช้ตัวระบุจริงในตัวอย่าง — model id ข้างต้นเป็น id ที่โปรเจกต์หนึ่งถูกกำหนดให้ใช้ได้จริง และคีย์ API มีหน้าตาเป็น aig_… จริง ๆ ตัวแทนที่ถูกคิดขึ้นเองสอนผู้อ่านให้รู้จักผลิตภัณฑ์ที่ไม่มีอยู่จริง

บล็อก API endpoint#

fence ที่ใช้ภาษา api โดยเขียน METHOD /path หนึ่งรายการต่อบรรทัด:

ตาราง#

การ build และการสร้างอัตโนมัติ#

cd docs-site && bun run build

การ build จะสร้างทุกหน้า หน้า landing ของ category หน้าแรก และ search-index.json ขึ้นใหม่ เนื้อหาที่สร้างอัตโนมัติ (API reference จาก spec, changelog จาก release) ควรถูกปล่อยออกมาเป็นไฟล์ .md ธรรมดาใน category ที่ถูกต้อง — ตัวสร้างไม่แยกแยะระหว่างหน้าที่เขียนเองกับหน้าที่สร้างอัตโนมัติ