This style guide establishes standards for documentation in the Proxmox project, ensuring consistency, clarity, and maintainability across all documentation.
---
## File Naming Convention
### Standard Format
**Format:** `UPPERCASE_WITH_UNDERSCORES.md`
**Examples:**
- ✅ `NETWORK_ARCHITECTURE.md`
- ✅ `DEPLOYMENT_GUIDE.md`
- ✅ `TROUBLESHOOTING_FAQ.md`
- ❌ `network-architecture.md` (incorrect)
- ❌ `deploymentGuide.md` (incorrect)
### Exceptions
- **README.md** - Standard convention (lowercase)
- **MASTER_INDEX.md** - Master index file
---
## Document Structure
### Standard Header
Every document should start with:
```markdown
# Document Title
**Last Updated:** YYYY-MM-DD
**Document Version:** X.Y
**Status:** Active Documentation / Archived / Draft
---
```
### Table of Contents
For documents longer than 500 lines, include a table of contents:
```markdown
## Table of Contents
1. [Section 1](#section-1)
2. [Section 2](#section-2)
3. [Section 3](#section-3)
```
---
## Markdown Standards
### Headings
**Hierarchy:**
-`#` - Document title (H1)
-`##` - Major sections (H2)
-`###` - Subsections (H3)
-`####` - Sub-subsections (H4)
**Guidelines:**
- Use H1 only for document title
- Don't skip heading levels (H2 → H4)
- Use descriptive headings
### Code Blocks
**Inline Code:**
```markdown
Use `backticks` for inline code, commands, and file names.
1.**Commands:** Run shell commands in a safe environment (e.g. read-only or test host) and confirm output matches or is consistent with documented expected output.
2.**Paths and links:** Use `docs/scripts/check-docs-links.sh` (or markdown-link-check/lychee) to find broken links; fix docs-internal and root links first.
3.**Headers:** Run `docs/scripts/validate-doc-headers.sh` to ensure Last Updated, Status, and `---` are present; add Document Version where missing.
4.**Cross-references:** Run `docs/scripts/check-docs-crossrefs.sh` to list docs missing a Related Documentation section; add cross-refs where appropriate.
5.**Procedures:** For step-by-step guides, perform the procedure once in a test environment and update steps or expected output if they diverge.
| **Quarterly** | Architecture and design documents (02-architecture, 05-network, 11-references/NETWORK_CONFIGURATION_MASTER) | Review for accuracy; sync directory trees in MASTER_INDEX and docs/README; run link validation. |
| **As needed** | Troubleshooting, quick references | Update when procedures or endpoints change. |
---
## Document Versioning and Dates
- **Last Updated:** Use ISO format `YYYY-MM-DD` (e.g. 2026-01-31).
- **Document Version:** Use `X.Y` (e.g. 1.0, 1.1). Bump minor for non-breaking edits; consider major for structural changes.
- **Status:** Use one of: `Active Documentation`, `Archived`, `Draft`. Do not use emoji in the status field; keep emoji in body content if desired.
**Optional document status indicators (visual):** You may add a single emoji before or after the Status line for quick scanning:
- 🟢 **Active**– Active Documentation
- 📁 **Archived**– Archived
- 📝 **Draft**– Draft
- ⚠️ **Deprecated**– Being phased out
Example: `**Status:** 🟢 Active Documentation` or `**Status:** Active Documentation 🟢`. Use sparingly and consistently (e.g. only in MASTER_INDEX or key entry-point docs).
- Update "Last Updated" and optionally "Document Version" whenever you make substantive edits.
---
## Link and Header Validation
- **Link validation:** Use `markdown-link-check` or `lychee` to find broken links. Run periodically (e.g. from `docs/` or repo root). See [DOCUMENTATION_FIX_TASK_LIST.md](DOCUMENTATION_FIX_TASK_LIST.md) for report references.
- **Header validation:** Use `docs/scripts/validate-doc-headers.sh` (if present) to check that documents have standard headers (Last Updated, Document Version, Status, `---`).
- **Cross-references:** Use `docs/scripts/check-docs-crossrefs.sh` (optional) to list docs that may be missing a "Related Documentation" section; add cross-refs manually where appropriate.
---
## Optional: Accessibility and Output Formats
- **Print-friendly / PDF:** Key docs can be exported to PDF (e.g. via Pandoc, VS Code Markdown PDF, or browser Print to PDF). Prefer single-column layout and avoid wide tables where possible.
- **Mobile-friendly:** Keep paragraphs and tables concise; use collapsible sections in long docs if your renderer supports it. Test key pages on small viewports.
- **Dark mode:** Optional dark theme for rendered docs (e.g. MkDocs with readthedocs theme, or CSS `prefers-color-scheme: dark`). Not required; apply consistently if adopted.
---
## Optional: Screenshots and Images
- **When to use:** Add screenshots where they materially help (e.g. UI wizards, dashboard layouts, error dialogs). Prefer text + code for procedures.
- **Where to store:** Use `docs/assets/` or a per-doc folder (e.g. `docs/04-configuration/cloudflare/screenshots/`). Reference with relative paths.
- **Naming:** Use descriptive names: `omada-vlan-config.png`, `proxmox-storage-summary.png`. Keep file size reasonable (compress if needed).
---
## Optional: Diagrams and Visual Aids
- **Automated diagram generation:** For config-driven diagrams, consider: Mermaid CLI (`mmdc`), Structurizr, or custom scripts that emit Mermaid/PlantUML. Evaluate per use case; hand-maintained Mermaid in-doc is often sufficient.
- **Service state machines:** Optional state diagrams for key services (e.g. container lifecycle: created → running → stopped). Use Mermaid `stateDiagram-v2` or a short ASCII flow.
- **ASCII art diagrams:** For terminals or minimal dependencies, simple ASCII diagrams are acceptable (e.g. `[Client] --> [NGINX] --> [Backend]`). Prefer Mermaid for version-controlled, editable diagrams.
- **Visual table of contents:** In long docs, optional priority/status indicators in the TOC (e.g. 🟢 Active, 📁 Archived) can aid scanning; use sparingly and consistently.
- **Document relationship map:** An optional high-level diagram of doc relationships (e.g. MASTER_INDEX → category READMEs → key docs) lives in [DOCUMENT_RELATIONSHIP_MAP.md](DOCUMENT_RELATIONSHIP_MAP.md).
