Core concepts

Directory convention

docs/
├── index.md              # Chinese home page
├── guide/                # Guides (concepts, onboarding)
├── products/             # Product documentation
├── changelog.md          # Changelog
├── en/                   # English, identical structure
├── th/                   # Thai, identical structure
└── public/               # Images and other static assets

The key rule: file paths map one-to-one across all three language directories. This is not just tidiness — the automated translation script relies on path pairing to detect which pages are missing a translation and which have gone stale.

Content layers

Layer	Question it answers	Style
Guide	What is this? Why use it?	Narrative; opinions allowed
Product docs	How do I configure it? What are the parameters?	Tables and code blocks; precise, unambiguous
Changelog	What changed? Who does it affect?	Reverse chronological; flag breaking changes

Writing standards

Required front-matter

---
title: Page title          # Browser tab and search results
description: One-line summary  # SEO and search preview
---

Consistent terminology

A concept must use the same term site-wide, with a fixed translation in each language. The glossary lives in scripts/glossary.json and is enforced during automated translation.

Available callouts

Tip

Supplementary information and techniques.

Warning

Common pitfalls.

Danger

Operations causing data loss or irreversible effects.

Images

Place them under docs/public/ and reference with an absolute path:

![Architecture](/images/architecture.png)

File naming

Use plain ASCII filenames (e.g. arch-overview-v2.png). Avoid non-ASCII characters — some CDNs and browsers handle them inconsistently.

Versioning and change tracking

Any change with user-facing impact must be recorded in the changelog. When the Chinese version is updated without its English counterpart, the automated audit flags that page as having a stale translation.