Documentation conventions & naming
Purpose
Section titled “Purpose”Keep the handover site consistent for search, bookmarks, and onboarding.
URL slugs (paths)
Section titled “URL slugs (paths)”- English, kebab-case where possible:
reading-order,scenario-billing-xero. - Stable: avoid renaming slugs without adding a redirect (Starlight
redirectsinastro.config.mjs). - Generated DocType pages use the Frappe folder name in snake_case segments:
/doctype-reference/finance-ar-integrations/xero_invoice/.
Sidebar groups (logical names)
Section titled “Sidebar groups (logical names)”Sidebar uses short group labels without a Reference — prefix so the nav stays scannable. Content is still reference material unless it lives under Tutorial.
| Group label | Meaning |
|---|---|
| Start | Onboarding, scope, glossary, deliverables |
| Tutorial | Guided reading order and business scenarios |
| Platform & architecture | Frappe/ERPNext context, diagrams, overview, stack, feature inventory |
| Modules & domains | Frappe modules and Lee Kim areas |
| Data & features | DocTypes, ERD page, generated reference, catalogs |
| Integrations | Third-party systems |
| APIs & code hooks | APIs, hooks, overrides, flows |
| Operations | Deployment, security, known issues, docs site hosting |
Page titles
Section titled “Page titles”- Use sentence case or title case consistently per section.
- Generated DocType pages use the DocType
namefrom JSON (often Title Case).
Mermaid diagrams
Section titled “Mermaid diagrams”- Use fenced blocks with language
mermaid. - Prefer flowchart, sequenceDiagram, and small subgraphs; avoid huge diagrams that are hard to maintain.
- Build renders diagrams to SVG at build time (
rehype-mermaid,strategy: 'inline-svg').
Related
Section titled “Related”Frontmatter (Starlight)
Section titled “Frontmatter (Starlight)”| Field | Guidance |
|---|---|
title | Short, unique; appears in browser tab and search |
description | One sentence for SEO and card previews |
sidebar.order | Lower numbers appear earlier within a section |
Keep titles stable when possible — changing titles often is fine; changing slugs requires redirects.
Links to code paths
Section titled “Links to code paths”When referencing files, use backticks and repo-relative paths: `leekimerp/api/xero.py`. For browsable docs links, use root-absolute paths: [API inventory](/api/inventory/).
Confidentiality
Section titled “Confidentiality”Do not paste production URLs, tenant IDs, or PII in examples. Use placeholders like https://example.com and CUST-0001.