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.
```
**Code Blocks:**
````markdown
```bash
# Use language identifier
command --option value
```
````
**Supported Languages:**
-`bash` - Shell commands
-`yaml` - YAML files
-`json` - JSON files
-`python` - Python code
-`javascript` - JavaScript code
-`markdown` - Markdown examples
### Lists
**Unordered Lists:**
```markdown
- Item 1
- Item 2
- Sub-item 2.1
- Sub-item 2.2
```
**Ordered Lists:**
```markdown
1. Step 1
2. Step 2
3. Step 3
```
**Task Lists:**
```markdown
- [ ] Task 1
- [x] Completed task
- [ ] Task 3
```
### Tables
**Format:**
```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1 | Data 2 | Data 3 |
```
**Alignment:**
- Left: Default
- Center: `:---:`
- Right: `---:`
### Links
**Internal Links:**
```markdown
[Link Text](../path/to/file.md)
[Link Text](../path/to/file.md#section)
```
**External Links:**
```markdown
[Link Text](https://example.com)
```
### Emphasis
- **Bold:** `**text**` - For important terms, warnings
- *Italic:* `*text*` - For emphasis, variable names
-`Code:` `` `text` `` - For commands, file names, code
---
## Content Guidelines
### Writing Style
1.**Clarity:**
- Use clear, concise language
- Avoid jargon when possible
- Define technical terms
2.**Tone:**
- Professional but approachable
- Direct and actionable
- Helpful and informative
3.**Structure:**
- Logical flow
- Progressive detail
- Clear sections
### Technical Content
**Commands:**
- Show complete commands
- Include expected output
- Explain what commands do
**Examples:**
```markdown
# Check Proxmox cluster status
pvecm status
# Expected output:
# Cluster information
# ...
```
**Warnings and Notes:**
```markdown
> **Warning:** This action cannot be undone.
> **Note:** This feature requires Proxmox VE 8.0 or later.
```
---
## Document Types
### Getting Started Guides
**Structure:**
1. Overview
2. Prerequisites
3. Step-by-step instructions
4. Verification
5. Next steps
### Configuration Guides
**Structure:**
1. Overview
2. Prerequisites
3. Configuration steps
4. Verification
5. Troubleshooting
### Troubleshooting Guides
**Structure:**
1. Problem description
2. Symptoms
3. Solutions (ordered by likelihood)
4. Prevention
5. Related documentation
### Reference Documents
**Structure:**
1. Overview
2. Reference tables
3. Examples
4. Related documentation
---
## Cross-References
### Linking to Other Documents
**Format:**
```markdown
See **[Document Name](path/to/document.md)** for more information.
```
**Examples:**
```markdown
For network architecture details, see **[NETWORK_ARCHITECTURE.md](../02-architecture/NETWORK_ARCHITECTURE.md)**.
