Loading files
---
applyTo: "**/*.md"
---
# 📝 Markdown Documentation Guidelines
## Purpose & Scope
These guidelines ensure documentation in HomeRacker stays consistent, discoverable, and actionable.
Every code change that adds, modifies, or removes functionality **must** include a corresponding documentation update.
## ✍️ Writing Style
- Use **emojis** to improve scannability (section headers, admonitions, list bullets where fitting).
- Be **brief** — prefer bullet points over prose. Link to existing docs instead of duplicating content.
- Use **code blocks** with language hints for commands and config snippets.
- Cross-reference from the parent `README.md` when adding new pages so they remain discoverable.
## 📐 Document Structure
If not stated otherwise by the user, every new documentation page must follow this skeleton:
```markdown
# 🏷️ Title
## 📌 What
What component/feature/process this covers and which code paths are affected.
## 🤔 Why
Use-case description, design rationale, and/or architectural context.
## 🔧 How
Step-by-step instructions, commands, and/or examples for a user and/or CI to integrate/execute.
## 📚 References
- Originating issue / PR / discussion
- Related documentation in the repo
- Upstream / vendor documentation
```
> Sections may be omitted only when truly not applicable (e.g., a pure reference page).
## 🏗️ Model README Template
Each model folder (`models/<name>/`) should have a `README.md` following this structure:
```markdown
# 🏷️ Model Name
## 📌 What
Brief description of the model — what it is, what problem it solves.
## 🤔 Why
Design rationale: why this shape, these dimensions, this approach.
## 🔧 How
How to use/customize the model:
- Customizer parameters
- OpenSCAD CLI examples
- Print settings or tips (if applicable)
## 📸 Catalog
Preview images for each part. Generate with `export-png.sh`:
| Part | Preview |
|------|---------|
| Part Name |  |
> For flat models (no `parts/` subfolder), show a single preview next to the `.scad` file.
To generate or refresh previews:
./cmd/export/export-png.sh models/<name>/parts/<part>.scad
## 📚 References
- Related models or libraries
- MakerWorld listing (if published)
```
> - The 📸 Catalog section must list **every** `.scad` file under `parts/` (or the model's main `.scad` for flat models) with a preview PNG.
> - PNGs are generated by `cmd/export/export-png.sh` and stored next to their source `.scad` file.
> - When adding or modifying a parts file, **always** generate/refresh its PNG and update the Catalog table.
> - When adding a new model or part, also update the parent `models/README.md` index with a description and preview image.
## 🗂️ File Organization
- **Placement:** READMEs live next to their code — each model folder and `cmd/` subfolder gets its own `README.md`.
- **Naming:** Use lowercase `kebab-case`. Name files after the topic, not the ticket.
- **Restructuring:** When adding docs, check if existing files should be renamed or reorganized to avoid overlap. Keep the directory tree tidy — fewer well-named files beat many scattered ones.
- **Index:** Reference new model folders from `models/README.md`.
## 🔗 Linking Conventions
- Use **relative paths** for repo-internal links.
- For external resources (BOSL2 wiki, MakerWorld), include the full URL.
## 🚫 Anti-Patterns
- Don't create docs that only repeat what the code already says — add *context* the code can't convey.
- Don't leave placeholder sections empty — either fill them or remove the heading.
- Don't duplicate content across files — link to the single source of truth.
- Don't commit PNGs without a corresponding README entry linking them.
- Don't add or modify parts files without generating/refreshing preview PNGs.
- Don't update a model README without checking if the parent `models/README.md` index needs updating too.
988743a91This file is pinned to the selected release. Download the original to open it in your design tool.