Style Guide

This guide ensures consistency across all tomes within the Tech Grimoire.

General Principles

Writing Style

Write in clear, concise language
Use active voice
Maintain technical accuracy while being accessible
Keep the magical theme subtle but present
Target an informed technical audience

Document Structure

Start with a clear introduction
Use hierarchical headings (H1 → H4)
Include a table of contents for longer articles
End with related links and references
Add tags for cross-referencing

Formatting

Headers

# Main Title (H1) - One per page
## Major Sections (H2)
### Subsections (H3)
#### Detailed Points (H4)

Code Blocks

Use triple backticks with language specification

```python
def example():
    return "Hello, World!"

- Use single backticks for inline code: `variable_name`

### Lists
- Use hyphen (-) for unordered lists
- Use numbers (1.) for ordered lists
- Maintain consistent indentation for nested lists
  - Two spaces for each nesting level
  - Keep lists parallel in structure

### Tables
- Use standard markdown tables
- Include header row
- Align columns meaningfully
- Example:
```markdown
| Command | Description | Example |
|---------|-------------|---------|
| `ls`    | List files  | `ls -la`|

Links and References

Use descriptive link text: Configuration Guide
Prefer relative paths for internal links
Include reference sections for external resources

Special Elements

Notes and Warnings

> **Note:** Important information that readers should know

> **Warning:** Critical information about risks or potential issues

Terminal Commands

```bash
# Command with explanation
command --flag argument  # What this does


### Diagrams
- Use Mermaid for diagrams
- Include both diagram code and description
- Example:
```markdown
```mermaid
graph TD
    A[Start] --> B[End]


## Content Organization

### File Names
- Use lowercase
- Replace spaces with hyphens
- Be descriptive but concise
- Example: `docker-container-optimization.md`

### Directory Structure
- Group related content in directories
- Use clear, descriptive directory names
- Maximum of 3 levels deep
- Include README.md in each directory

### Tags
- Use lowercase for tags
- Separate multi-word tags with hyphens
- Example: `#machine-learning #neural-networks`

## Images and Media
- Store in designated `/assets` directory
- Use descriptive file names
- Include alt text for accessibility
- Optimize for web viewing
- Maximum width: 800px

## Version Notes
- Include last updated date
- Note major changes
- Reference related tickets/issues