# Guides content (/my/guides)

Read by `App\Support\Guides`, rendered by `GuidesController` and `Pages/Main/Site/Guides/*`.
`glossary.json` holds terms (/my/guides/glossary/{slug}); `guides.json` holds articles (/my/guides/{slug}).
Both are JSON arrays of entries. Plain text only: no HTML, no Markdown.

| Field | Required | Notes |
| --- | --- | --- |
| id | yes | Content-queue ID from the SEO sheet (GL01, GD01...) |
| slug | yes | lowercase-with-hyphens; the URL. Never rename a published slug |
| status | yes | `draft` or `published`. Only a fact-checked entry is `published` |
| term / title | yes | `term` for glossary entries, `title` for guides |
| termZh / titleZh | no | Chinese name shown next to the title |
| aka | no | Other names readers search for (e.g. "cukai pintu") |
| short | yes | One line, at most 25 words (A-Z list) |
| answer | yes | 40-60 words that stand alone (AI answers quote this) |
| sections | yes | `[{"heading": "Question-style heading?", "paragraphs": ["..."]}]` |
| example | no | `{"heading": "...", "text": "..."}`, a worked RM example |
| faqs | no | `[{"q": "...", "a": "40-60 words"}]` |
| related | no | Glossary slugs; missing or hidden ones are skipped |
| sources | yes | `[{"title": "...", "url": "... or null", "accessed": "YYYY-MM-DD or null"}]` |
| updated | yes | YYYY-MM-DD |
| checkedBy | for published | Name of the fact-checker shown on the page |
| seoTitle / seoDescription | no | At most 60 / 155 characters |

Drafts are visible only where `config('guides.show_drafts')` is on (default: wherever `SEO_CANONICAL_URL` is unset,
i.e. dev workspaces). A draft is marked on the page, served noindex and left out of the sitemap.

## Guides (`guides.json`)

Same fields as above (`title`, not `term`), plus:

| Field | Notes |
| --- | --- |
| topic | One of the six labels in `App\Support\Guides::TOPICS` (the /my/guides filter) |
| sections | `[{"heading": "...?", "blocks": [...]}]`. A block is `{"type": "p", "text"}`, `{"type": "ul" or "ol", "items": []}`, `{"type": "table", "head": [], "rows": [[]]}` or `{"type": "h3", "text"}` |
| intro | Blocks shown between the short answer and the first section (usually empty) |
| cta | `{"text": "...", "label": "..."}`, the one next step (links to sign-up) |
| readMinutes / reviewer | Shown in the trust line / on the draft banner |
| relatedProjects | `[{"slug", "name", "url"}]`, at most 3 |
| zh | Simplified Chinese version: `title`, `answer`, `intro`, `sections`, `faqs`, `sources`, `cta`, `readMinutes`, `updated` |
| volume | Semrush MY monthly volume of the target keyword (orders guides within a topic) |

Text fields of guides may use `**bold**` and `[label](/path or https://...)`; the page renders
these as elements (still no v-html). Build the file from the Google Doc drafts with
`python3 scripts/seo/guides_from_drafts.py <drafts dir> resources/content/guides/guides.json`.
Every generated entry is `draft` until the checker signs it off.
