docs: Add style guide based on existing repo conventions

2026-05-09 22:07:32 +02:00 · 2026-03-13 04:39:05 +01:00
parent 8fe0c96f7b
commit 84141d06cf
1 changed files with 630 additions and 0 deletions
@@ -0,0 +1,630 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+  <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+
+# Style Guide
+
+> Conventions and formatting rules for contributing to Claude How To. Follow this guide to keep content consistent, professional, and easy to maintain.
+
+---
+
+## Table of Contents
+
+- [File and Folder Naming](#file-and-folder-naming)
+- [Document Structure](#document-structure)
+- [Headings](#headings)
+- [Text Formatting](#text-formatting)
+- [Lists](#lists)
+- [Tables](#tables)
+- [Code Blocks](#code-blocks)
+- [Links and Cross-References](#links-and-cross-references)
+- [Diagrams](#diagrams)
+- [Emoji Usage](#emoji-usage)
+- [YAML Frontmatter](#yaml-frontmatter)
+- [Images and Media](#images-and-media)
+- [Tone and Voice](#tone-and-voice)
+- [Commit Messages](#commit-messages)
+- [Checklist for Authors](#checklist-for-authors)
+
+---
+
+## File and Folder Naming
+
+### Lesson Folders
+
+Lesson folders use a **two-digit numbered prefix** followed by a **kebab-case** descriptor:
+
+```
+01-slash-commands/
+02-memory/
+03-skills/
+04-subagents/
+05-mcp/
+```
+
+The number reflects the learning path order from beginner to advanced.
+
+### File Names
+
+| Type | Convention | Examples |
+|------|-----------|----------|
+| **Lesson README** | `README.md` | `01-slash-commands/README.md` |
+| **Feature file** | Kebab-case `.md` | `code-reviewer.md`, `generate-api-docs.md` |
+| **Shell script** | Kebab-case `.sh` | `format-code.sh`, `validate-input.sh` |
+| **Config file** | Standard names | `.mcp.json`, `settings.json` |
+| **Memory file** | Scope-prefixed | `project-CLAUDE.md`, `personal-CLAUDE.md` |
+| **Top-level docs** | UPPER_CASE `.md` | `CATALOG.md`, `QUICK_REFERENCE.md`, `CONTRIBUTING.md` |
+| **Image assets** | Kebab-case | `pr-slash-command.png`, `claude-howto-logo.svg` |
+
+### Rules
+
+- Use **lowercase** for all file and folder names (except top-level docs like `README.md`, `CATALOG.md`)
+- Use **hyphens** (`-`) as word separators, never underscores or spaces
+- Keep names descriptive but concise
+
+---
+
+## Document Structure
+
+### Root README
+
+The root `README.md` follows this order:
+
+1. Logo (`<picture>` element with dark/light variants)
+2. H1 title
+3. Introductory blockquote (one-line value proposition)
+4. "Why This Guide?" section with comparison table
+5. Horizontal rule (`---`)
+6. Table of Contents
+7. Feature Catalog
+8. Quick Navigation
+9. Learning Path
+10. Feature sections
+11. Getting Started
+12. Best Practices / Troubleshooting
+13. Contributing / License
+
+### Lesson README
+
+Each lesson `README.md` follows this order:
+
+1. H1 title (e.g., `# Slash Commands`)
+2. Brief overview paragraph
+3. Quick reference table (optional)
+4. Architecture diagram (Mermaid)
+5. Detailed sections (H2)
+6. Practical examples (numbered, 4-6 examples)
+7. Best practices (Do's and Don'ts tables)
+8. Troubleshooting
+9. Related guides / Official documentation
+10. Document metadata footer
+
+### Feature/Example File
+
+Individual feature files (e.g., `optimize.md`, `pr.md`):
+
+1. YAML frontmatter (if applicable)
+2. H1 title
+3. Purpose / description
+4. Usage instructions
+5. Code examples
+6. Customization tips
+
+### Section Separators
+
+Use horizontal rules (`---`) to separate major document regions:
+
+```markdown
+---
+
+## New Major Section
+```
+
+Place them after the introductory blockquote and between logically distinct parts of the document.
+
+---
+
+## Headings
+
+### Hierarchy
+
+| Level | Use | Example |
+|-------|-----|---------|
+| `#` H1 | Page title (one per document) | `# Slash Commands` |
+| `##` H2 | Major sections | `## Best Practices` |
+| `###` H3 | Subsections | `### Adding a Skill` |
+| `####` H4 | Sub-subsections (rare) | `#### Configuration Options` |
+
+### Rules
+
+- **One H1 per document** — the page title only
+- **Never skip levels** — don't jump from H2 to H4
+- **Keep headings concise** — aim for 2-5 words
+- **Use sentence case** — capitalize first word and proper nouns only (exception: feature names stay as-is)
+- **Add emoji prefixes only on root README** section headers (see [Emoji Usage](#emoji-usage))
+
+---
+
+## Text Formatting
+
+### Emphasis
+
+| Style | When to Use | Example |
+|-------|------------|---------|
+| **Bold** (`**text**`) | Key terms, labels in tables, important concepts | `**Installation**:` |
+| *Italic* (`*text*`) | First use of a technical term, book/doc titles | `*frontmatter*` |
+| `Code` (`` `text` ``) | File names, commands, config values, code references | `` `CLAUDE.md` `` |
+
+### Blockquotes for Callouts
+
+Use blockquotes with bold prefixes for important notes:
+
+```markdown
+> **Note**: Custom slash commands have been merged into skills since v2.0.
+
+> **Important**: Never commit API keys or credentials.
+
+> **Tip**: Combine memory with skills for maximum effectiveness.
+```
+
+Supported callout types: **Note**, **Important**, **Tip**, **Warning**.
+
+### Paragraphs
+
+- Keep paragraphs short (2-4 sentences)
+- Add a blank line between paragraphs
+- Lead with the key point, then provide context
+- Explain the "why" not just the "what"
+
+---
+
+## Lists
+
+### Unordered Lists
+
+Use dashes (`-`) with 2-space indentation for nesting:
+
+```markdown
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+    - Deep nested (avoid going deeper than 3 levels)
+- Third item
+```
+
+### Ordered Lists
+
+Use numbered lists for sequential steps, instructions, and ranked items:
+
+```markdown
+1. First step
+2. Second step
+   - Sub-point detail
+   - Another sub-point
+3. Third step
+```
+
+### Descriptive Lists
+
+Use bold labels for key-value style lists:
+
+```markdown
+- **Performance bottlenecks** - identify O(n^2) operations, inefficient loops
+- **Memory leaks** - find unreleased resources, circular references
+- **Algorithm improvements** - suggest better algorithms or data structures
+```
+
+### Rules
+
+- Maintain consistent indentation (2 spaces per level)
+- Add a blank line before and after a list
+- Keep list items parallel in structure (all start with verb, or all are nouns, etc.)
+- Avoid nesting deeper than 3 levels
+
+---
+
+## Tables
+
+### Standard Format
+
+```markdown
+| Column 1 | Column 2 | Column 3 |
+|----------|----------|----------|
+| Data     | Data     | Data     |
+```
+
+### Common Table Patterns
+
+**Feature comparison (3-4 columns):**
+
+```markdown
+| Feature | Invocation | Persistence | Best For |
+|---------|-----------|------------|----------|
+| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts |
+| **Memory** | Auto-loaded | Cross-session | Long-term learning |
+```
+
+**Do's and Don'ts:**
+
+```markdown
+| Do | Don't |
+|----|-------|
+| Use descriptive names | Use vague names |
+| Keep files focused | Overload a single file |
+```
+
+**Quick reference:**
+
+```markdown
+| Aspect | Details |
+|--------|---------|
+| **Purpose** | Generate API documentation |
+| **Scope** | Project-level |
+| **Complexity** | Intermediate |
+```
+
+### Rules
+
+- **Bold table headers** when they are row labels (first column)
+- Align pipes for readability in source (optional but preferred)
+- Keep cell content concise; use links for details
+- Use `code formatting` for commands and file paths inside cells
+
+---
+
+## Code Blocks
+
+### Language Tags
+
+Always specify a language tag for syntax highlighting:
+
+| Language | Tag | Use For |
+|----------|-----|---------|
+| Shell | `bash` | CLI commands, scripts |
+| Python | `python` | Python code |
+| JavaScript | `javascript` | JS code |
+| TypeScript | `typescript` | TS code |
+| JSON | `json` | Configuration files |
+| YAML | `yaml` | Frontmatter, config |
+| Markdown | `markdown` | Markdown examples |
+| SQL | `sql` | Database queries |
+| Plain text | (no tag) | Expected output, directory trees |
+
+### Conventions
+
+```bash
+# Comment explaining what the command does
+claude mcp add notion --transport http https://mcp.notion.com/mcp
+```
+
+- Add a **comment line** before non-obvious commands
+- Make all examples **copy-paste ready**
+- Show **both simple and advanced** versions when relevant
+- Include **expected output** when it aids understanding (use untagged code block)
+
+### Installation Blocks
+
+Use this pattern for installation instructions:
+
+```bash
+# Copy files to your project
+cp 01-slash-commands/*.md .claude/commands/
+```
+
+### Multi-step Workflows
+
+```bash
+# Step 1: Create the directory
+mkdir -p .claude/commands
+
+# Step 2: Copy the templates
+cp 01-slash-commands/*.md .claude/commands/
+
+# Step 3: Verify installation
+ls .claude/commands/
+```
+
+---
+
+## Links and Cross-References
+
+### Internal Links (Relative)
+
+Use relative paths for all internal links:
+
+```markdown
+[Slash Commands](01-slash-commands/)
+[Skills Guide](03-skills/)
+[Memory Architecture](02-memory/#memory-architecture)
+```
+
+From a lesson folder back to root or sibling:
+
+```markdown
+[Back to main guide](../README.md)
+[Related: Skills](../03-skills/)
+```
+
+### External Links (Absolute)
+
+Use full URLs with descriptive anchor text:
+
+```markdown
+[Anthropic's official documentation](https://docs.anthropic.com/en/docs/claude-code)
+```
+
+- Never use "click here" or "this link" as anchor text
+- Use descriptive text that makes sense out of context
+
+### Section Anchors
+
+Link to sections within the same document using GitHub-style anchors:
+
+```markdown
+[Feature Catalog](#-feature-catalog)
+[Best Practices](#best-practices)
+```
+
+### Related Guides Pattern
+
+End lessons with a related guides section:
+
+```markdown
+## Related Guides
+
+- [Slash Commands](../01-slash-commands/) - Quick shortcuts
+- [Memory](../02-memory/) - Persistent context
+- [Skills](../03-skills/) - Reusable capabilities
+```
+
+---
+
+## Diagrams
+
+### Mermaid
+
+Use Mermaid for all diagrams. Supported types:
+
+- `graph TB` / `graph LR` — architecture, hierarchy, flow
+- `sequenceDiagram` — interaction flows
+- `timeline` — chronological sequences
+
+### Style Conventions
+
+Apply consistent colors using style blocks:
+
+```mermaid
+graph TB
+    A["Component A"] --> B["Component B"]
+    B --> C["Component C"]
+
+    style A fill:#e1f5fe,stroke:#333,color:#333
+    style B fill:#fce4ec,stroke:#333,color:#333
+    style C fill:#e8f5e9,stroke:#333,color:#333
+```
+
+**Color palette:**
+
+| Color | Hex | Use For |
+|-------|-----|---------|
+| Light blue | `#e1f5fe` | Primary components, inputs |
+| Light pink | `#fce4ec` | Processing, middleware |
+| Light green | `#e8f5e9` | Outputs, results |
+| Light yellow | `#fff9c4` | Configuration, optional |
+| Light purple | `#f3e5f5` | User-facing, UI |
+
+### Rules
+
+- Use `["Label text"]` for node labels (enables special characters)
+- Use `<br/>` for line breaks within labels
+- Keep diagrams simple (max 10-12 nodes)
+- Add a brief text description below the diagram for accessibility
+- Use top-to-bottom (`TB`) for hierarchies, left-to-right (`LR`) for workflows
+
+---
+
+## Emoji Usage
+
+### Where Emojis Are Used
+
+Emojis are used **sparingly and purposefully** — only in specific contexts:
+
+| Context | Emojis | Example |
+|---------|--------|---------|
+| Root README section headers | Category icons | `## 📚 Learning Path` |
+| Skill level indicators | Colored circles | 🟢 Beginner, 🔵 Intermediate, 🔴 Advanced |
+| Do's and Don'ts | Check/cross marks | ✅ Do this, ❌ Don't do this |
+| Complexity ratings | Stars | ⭐⭐⭐ |
+
+### Standard Emoji Set
+
+| Emoji | Meaning |
+|-------|---------|
+| 📚 | Learning, guides, documentation |
+| ⚡ | Getting started, quick reference |
+| 🎯 | Features, quick reference |
+| 🎓 | Learning paths |
+| 📊 | Statistics, comparisons |
+| 🚀 | Installation, quick commands |
+| 🟢 | Beginner level |
+| 🔵 | Intermediate level |
+| 🔴 | Advanced level |
+| ✅ | Recommended practice |
+| ❌ | Avoid / anti-pattern |
+| ⭐ | Complexity rating unit |
+
+### Rules
+
+- **Never use emojis in body text** or paragraphs
+- **Only use emojis in headers** on the root README (not in lesson READMEs)
+- **Do not add decorative emojis** — every emoji should convey meaning
+- Keep emoji usage consistent with the table above
+
+---
+
+## YAML Frontmatter
+
+### Feature Files (Skills, Commands, Agents)
+
+```yaml
+---
+name: unique-identifier
+description: What this feature does and when to use it
+allowed-tools: Bash, Read, Grep
+---
+```
+
+### Optional Fields
+
+```yaml
+---
+name: my-feature
+description: Brief description
+argument-hint: "[file-path] [options]"
+allowed-tools: Bash, Read, Grep, Write, Edit
+model: opus                        # opus, sonnet, or haiku
+disable-model-invocation: true     # User-only invocation
+user-invocable: false              # Hidden from user menu
+context: fork                      # Run in isolated subagent
+agent: Explore                     # Agent type for context: fork
+---
+```
+
+### Rules
+
+- Place frontmatter at the very top of the file
+- Use **kebab-case** for the `name` field
+- Keep `description` to one sentence
+- Only include fields that are needed
+
+---
+
+## Images and Media
+
+### Logo Pattern
+
+All documents that start with a logo use the `<picture>` element for dark/light mode support:
+
+```html
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
+  <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
+</picture>
+```
+
+### Screenshots
+
+- Store in the relevant lesson folder (e.g., `01-slash-commands/pr-slash-command.png`)
+- Use kebab-case file names
+- Include descriptive alt text
+- Prefer SVG for diagrams, PNG for screenshots
+
+### Rules
+
+- Always provide alt text for images
+- Keep image file sizes reasonable (< 500KB for PNGs)
+- Use relative paths for image references
+- Store images in the same directory as the document that references them, or in `assets/` for shared images
+
+---
+
+## Tone and Voice
+
+### Writing Style
+
+- **Professional but approachable** — technical accuracy without jargon overload
+- **Active voice** — "Create a file" not "A file should be created"
+- **Direct instructions** — "Run this command" not "You might want to run this command"
+- **Beginner-friendly** — assume the reader is new to Claude Code, not new to programming
+
+### Content Principles
+
+| Principle | Example |
+|-----------|---------|
+| **Show, don't tell** | Provide working examples, not abstract descriptions |
+| **Progressive complexity** | Start simple, add depth in later sections |
+| **Explain the "why"** | "Use memory for... because..." not just "Use memory for..." |
+| **Copy-paste ready** | Every code block should work when pasted directly |
+| **Real-world context** | Use practical scenarios, not contrived examples |
+
+### Vocabulary
+
+- Use "Claude Code" (not "Claude CLI" or "the tool")
+- Use "skill" (not "custom command" — legacy term)
+- Use "lesson" or "guide" for the numbered sections
+- Use "example" for individual feature files
+
+---
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): description
+```
+
+### Types
+
+| Type | Use For |
+|------|---------|
+| `feat` | New feature, example, or guide |
+| `fix` | Bug fix, correction, broken link |
+| `docs` | Documentation improvements |
+| `refactor` | Restructuring without changing behavior |
+| `style` | Formatting changes only |
+| `test` | Test additions or changes |
+| `chore` | Build, dependencies, CI |
+
+### Scopes
+
+Use the lesson name or file area as scope:
+
+```
+feat(slash-commands): Add API documentation generator
+docs(memory): Improve personal preferences example
+fix(README): Correct table of contents link
+docs(skills): Add comprehensive code review skill
+```
+
+---
+
+## Document Metadata Footer
+
+Lesson READMEs end with a metadata block:
+
+```markdown
+---
+**Last Updated**: March 2026
+**Claude Code Version**: 2.1+
+**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5
+```
+
+- Use month + year format (e.g., "March 2026")
+- Update the version when features change
+- List all compatible models
+
+---
+
+## Checklist for Authors
+
+Before submitting content, verify:
+
+- [ ] File/folder names use kebab-case
+- [ ] Document starts with H1 title (one per file)
+- [ ] Heading hierarchy is correct (no skipped levels)
+- [ ] All code blocks have language tags
+- [ ] Code examples are copy-paste ready
+- [ ] Internal links use relative paths
+- [ ] External links have descriptive anchor text
+- [ ] Tables are properly formatted
+- [ ] Emojis follow the standard set (if used at all)
+- [ ] Mermaid diagrams use the standard color palette
+- [ ] No sensitive information (API keys, credentials)
+- [ ] YAML frontmatter is valid (if applicable)
+- [ ] Images have alt text
+- [ ] Paragraphs are short and focused
+- [ ] Related guides section links to relevant lessons
+- [ ] Commit message follows conventional commits format