Documentation Style Guide¶

This guide outlines the standards and best practices for writing documentation for EgyGeeks projects.

Code Blocks¶

Basic Syntax¶

Always specify the language for syntax highlighting:

```python
def hello_world():
    print("Hello, World!")
```

Supported Languages¶

Common languages we use: - python - Python code - javascript or js - JavaScript - typescript or ts - TypeScript - bash or sh - Shell scripts - yaml - YAML configuration files - json - JSON data - sql - SQL queries - go - Go code - html - HTML markup - css - CSS stylesheets - dockerfile - Dockerfiles - nginx - Nginx configuration

Adding Titles¶

Use title to show the filename or description:

```python title="app.py"
def main():
    pass
```

When to use titles: - Always add titles to show actual filenames - For configuration files (e.g., title="mkdocs.yml") - For scripts (e.g., title="deploy.sh") - For code examples that represent complete files

Line Numbers¶

Add line numbers with linenums="1":

```python linenums="1"
def bubble_sort(items):
    for i in range(len(items)):
        # sorting logic
    return items
```

When to use line numbers: - For longer code examples (>5 lines) - When discussing specific line numbers in the text - For complete functions or classes - For configuration files

Highlighting Lines¶

Emphasize important lines with hl_lines:

```python linenums="1" hl_lines="2 3"
def connect_db():
    conn = create_connection()  # Important
    conn.set_timeout(30)        # Important
    return conn
```

You can highlight ranges too:

```python hl_lines="3-5"
# code here
```

When to highlight lines: - To draw attention to important changes - To show the specific lines being discussed - To highlight security-critical code - To show configuration that needs customization

Code Annotations¶

Add explanatory notes using numbered markers:

```python linenums="1"
def api_call(url, token): # (1)!
    headers = {
        "Authorization": f"Bearer {token}", # (2)!
        "Content-Type": "application/json"
    }
    return requests.get(url, headers=headers, timeout=30) # (3)!
```

1. Main API function that handles authenticated requests
2. Authentication header with bearer token
3. 30-second timeout prevents hanging requests

Best practices for annotations: - Use (1)! format (with exclamation) to hide comment markers - Place annotations after the code block - Keep explanations concise but informative - Number them sequentially

Inline Code¶

Use backticks for inline code references:

The `print()` function outputs to the console.

For syntax-highlighted inline code:

Use `#!python range(10)` to create a sequence.
Call `#!javascript console.log()` for debugging.

Complete Example¶

Here's a code block using all features:

```python title="database.py" linenums="1" hl_lines="8-10"
import psycopg2
from typing import Optional

class Database:
    """Database connection handler."""

    def __init__(self, connection_string: str): # (1)!
        self.conn = psycopg2.connect(connection_string)
        self.cursor = self.conn.cursor()
        self._setup_connection() # (2)!

    def _setup_connection(self):
        """Configure connection parameters."""
        self.cursor.execute("SET timezone TO 'UTC'")
        self.conn.commit()

    def close(self): # (3)!
        self.cursor.close()
        self.conn.close()
```

1. Initialize database connection with connection string
2. Setup method configures timezone and other parameters
3. Always close connections to prevent resource leaks

Admonitions¶

Use admonitions to highlight important information:

Note¶

!!! note
    This is a general note with useful information.

Tip¶

!!! tip "Pro Tip"
    Use custom titles to make tips more specific!

Warning¶

!!! warning
    This warns users about potential issues.

Danger¶

!!! danger "Security Risk"
    Never commit API keys or secrets to version control!

Info¶

!!! info
    Additional context or information.

Example¶

!!! example
    Here's how to use this feature:

    ```python
    result = my_function()
    ```

Collapsible Admonitions¶

Use ??? for collapsed-by-default admonitions:

??? note "Click to expand"
    This content is hidden by default.

Use ???+ for expanded-by-default but collapsible:

???+ tip "Additional Details"
    This is expanded but can be collapsed.

Content Tabs¶

Group related content with tabs:

=== "Python"

    ```python
    print("Hello, World!")
    ```

=== "JavaScript"

    ```javascript
    console.log("Hello, World!");
    ```

=== "Go"

    ```go
    fmt.Println("Hello, World!")
    ```

When to use tabs: - Showing the same example in multiple languages - Comparing different approaches - OS-specific instructions (Linux/macOS/Windows)

Task Lists¶

Create interactive checklists:

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

Tables¶

Create clear, formatted tables:

| Feature | Status | Notes |
|---------|--------|-------|
| Authentication | ✅ Done | OAuth2 supported |
| Caching | 🚧 In Progress | Redis integration |
| Logging | ✅ Done | Structured logging |

Links¶

Internal Links¶

Link to other documentation pages:

See the [Server Overview](../server/overview.md) for details.

External Links¶

Visit [our GitHub](https://github.com/egygeeks) for source code.

Reference Links¶

For repeated links:

Check out [Material for MkDocs][mkdocs-material] documentation.

[mkdocs-material]: https://squidfunk.github.io/mkdocs-material/

Images¶

Add images with captions:

![Architecture Diagram](../images/architecture.png)
*Figure 1: System Architecture Overview*

Keyboard Keys¶

Show keyboard shortcuts:

Press ++ctrl+c++ to copy.
Use ++cmd+v++ to paste on macOS.

Abbreviations¶

Define abbreviations in your content:

The HTML specification is maintained by W3C.

*[HTML]: Hypertext Markup Language
*[W3C]: World Wide Web Consortium

Common abbreviations are auto-included from includes/abbreviations.md.

Formatting Best Practices¶

Headers¶

Use # for page title (only one per page)
Use ## for main sections
Use ### for subsections
Use #### for sub-subsections (rarely needed)

Lists¶

Unordered lists:

- First item
- Second item
    - Nested item
    - Another nested item
- Third item

Ordered lists:

1. First step
2. Second step
3. Third step

Emphasis¶

*Italic text* or _italic text_
**Bold text** or __bold text__
***Bold and italic*** or ___bold and italic___
~~Strikethrough~~
==Highlighted text==

Blockquotes¶

> This is a blockquote.
> It can span multiple lines.
>
> And include multiple paragraphs.

File Organization¶

Naming Conventions¶

Use lowercase with hyphens: api-reference.md
Be descriptive: docker-deployment-guide.md
Avoid special characters except hyphens

Front Matter¶

Add metadata at the top of files:

---
title: Custom Page Title
description: Brief description for SEO
tags:
  - api
  - authentication
  - security
---

# Page Content

Writing Style¶

Voice and Tone¶

Use clear, concise language
Write in second person ("you") when addressing readers
Use active voice over passive voice
Be helpful and friendly but professional

Code Examples¶

Always test code examples before documenting
Include error handling where relevant
Add comments for complex logic
Show complete, working examples when possible

Security¶

Never include real API keys, passwords, or secrets
Use placeholders: YOUR_API_KEY, <your-token>, etc.
Highlight security best practices
Warn about common security pitfalls

Mermaid Diagrams¶

Create diagrams with Mermaid:

Flow Diagram¶

```mermaid
graph LR
    A[Client] --> B[API Gateway]
    B --> C[Service 1]
    B --> D[Service 2]
    C --> E[Database]
    D --> E

### Sequence Diagram

```markdown
```mermaid
sequenceDiagram
    User->>API: Request
    API->>Database: Query
    Database->>API: Result
    API->>User: Response

```

Quick Reference¶

Element	Syntax
Code block with title	```python title="app.py"
Line numbers	```python linenums="1"
Highlight lines	```python hl_lines="2 3"
Inline code	`code`
Syntax inline	`#!python code`
Note	`!!! note`
Warning	`!!! warning`
Tab group	`=== "Tab Name"`
Task list	`- [ ] Task`
Keyboard	`++ctrl+c++`
Abbreviation	`*[HTML]: Hypertext Markup Language`

Examples¶

For more examples, see:

Remember: Good documentation helps your teammates understand and use our tools effectively. Take time to make it clear, accurate, and helpful!