Skip to content

Markdown Syntax Guide

This guide provides examples of the special Markdown syntax enabled for this documentation site. Using these features will help create rich, readable, and consistent documentation.

Code Blocks (pymdownx.superfences)

The superfences extension enhances standard code blocks. It allows you to nest code blocks within other elements, like lists, and provides syntax highlighting.

Basic Code Block

To create a code block, wrap your code in triple backticks, and specify the language for syntax highlighting.

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

Renders as: 

def hello_world():
    print("Hello, world!")

Nested Code Block

You can nest code blocks inside lists, which is not possible with standard Markdown.

1.  First, import the library:
    ```python
    import os
    ```
2.  Then, use the library:
    ```python
    print(os.getcwd())
    ```

Renders as: 1. First, import the library: 

import os
2. Then, use the library: 
print(os.getcwd())

Tabbed Content (pymdownx.tabbed)

You can create tabbed content to show different versions of information. This is especially useful for showing examples for different environments or programming languages.

=== "Staging"
    This content is for the **Staging** environment.
    ```json
    { "env": "staging" }
    ```

=== "Production"
    This content is for the **Production** environment.
    ```json
    { "env": "production" }
    ```

Renders as:

This content is for the Staging environment. 

{ "env": "staging" }

This content is for the Production environment. 

{ "env": "production" }

Admonitions

Admonitions are call-out boxes that are perfect for highlighting important information.

Syntax

!!! <type> "<title>"
    Content goes here.
<type> can be note, tip, warning, danger, etc. The title is optional.

Examples

!!! note
    This is a simple note.

!!! tip "Here's a helpful tip"
    You can add a title to your admonition.

!!! warning "Proceed with caution"
    This action might have unintended consequences.

!!! danger "Security Alert"
    This is a critical warning. Do not ignore it.

Renders as:

Note

This is a simple note.

Here's a helpful tip

You can add a title to your admonition.

Proceed with caution

This action might have unintended consequences.

Security Alert

This is a critical warning. Do not ignore it.

Diagrams with Mermaid

You can create diagrams directly in your markdown files using the Mermaid syntax. This is excellent for visualizing architecture, workflows, and code structure.

To create a diagram, use a mermaid code block:

```mermaid
graph TD;
    A-->B;
```

Flowchart Example

Flowcharts are ideal for representing workflows or decision logic.

```mermaid
graph TD
    A[Start] --> B{Is it working?};
    B -- Yes --> C[Great!];
    B -- No --> D[Check Logs];
    D --> E[Fix Bug];
    E --> B;
    C --> F[End];
```

Renders as: 

graph TD
    A[Start] --> B{Is it working?};
    B -- Yes --> C[Great!];
    B -- No --> D[Check Logs];
    D --> E[Fix Bug];
    E --> B;
    C --> F[End];

Sequence Diagram Example

Sequence diagrams are perfect for showing how services or components interact over time.

```mermaid
sequenceDiagram
    participant User
    participant ProfileService as Profile Svc
    participant MatchingService as Matching Svc

    User->>ProfileService: GET /api/profile/recommendations
    ProfileService->>MatchingService: FindMatches(user_id)
    MatchingService-->>ProfileService: Return Matches
    ProfileService-->>User: Return Recommendations
```

Renders as: 

sequenceDiagram
    participant User
    participant ProfileService as Profile Svc
    participant MatchingService as Matching Svc

    User->>ProfileService: GET /api/profile/recommendations
    ProfileService->>MatchingService: FindMatches(user_id)
    MatchingService-->>ProfileService: Return Matches
    ProfileService-->>User: Return Recommendations

Component Diagram (C4 Model) Example

You can create simplified C4 model diagrams to show architectural components.

```mermaid
C4Component
    title Component diagram for the Matching Domain

    Container(spa, "Single-Page App", "JavaScript", "The main user interface")
    Container(api, "API Gateway", "Spring Boot", "Exposes the platform's API")

    ContainerDb(db, "Matching Database", "PostgreSQL", "Stores user profiles and match data")

    Component(m_service, "Matching Service", "Python", "Core matching logic")
    Component(p_service, "Profile Service", "Go", "Manages user profiles")

    Rel(spa, api, "Uses", "HTTPS/JSON")
    Rel(api, m_service, "Delegates to", "gRPC")
    Rel(api, p_service, "Delegates to", "gRPC")
    Rel(m_service, db, "Reads from / Writes to", "SQL")
    Rel(p_service, db, "Reads from / Writes to", "SQL")
```

Renders as: 

C4Component
    title Component diagram for the Matching Domain

    Container(spa, "Single-Page App", "JavaScript", "The main user interface")
    Container(api, "API Gateway", "Spring Boot", "Exposes the platform's API")

    ContainerDb(db, "Matching Database", "PostgreSQL", "Stores user profiles and match data")

    Component(m_service, "Matching Service", "Python", "Core matching logic")
    Component(p_service, "Profile Service", "Go", "Manages user profiles")

    Rel(spa, api, "Uses", "HTTPS/JSON")
    Rel(api, m_service, "Delegates to", "gRPC")
    Rel(api, p_service, "Delegates to", "gRPC")
    Rel(m_service, db, "Reads from / Writes to", "SQL")
    Rel(p_service, db, "Reads from / Writes to", "SQL")

Class Diagram Example

Class diagrams help document the structure of your code.

```mermaid
classDiagram
    class MatchingService {
        -matchRepository: IMatchRepository
        +findMatches(userId): Match[]
    }
    class IMatchRepository {
        <<interface>>
        +getPotentialMatches(userId): User[]
        +saveMatch(match): void
    }
    class PostgresMatchRepository {
        +getPotentialMatches(userId): User[]
        +saveMatch(match): void
    }
    MatchingService --|> IMatchRepository
    IMatchRepository <|.. PostgresMatchRepository
```

Renders as: 

classDiagram
    class MatchingService {
        -matchRepository: IMatchRepository
        +findMatches(userId): Match[]
    }
    class IMatchRepository {
        <<interface>>
        +getPotentialMatches(userId): User[]
        +saveMatch(match): void
    }
    class PostgresMatchRepository {
        +getPotentialMatches(userId): User[]
        +saveMatch(match): void
    }
    MatchingService --|> IMatchRepository
    IMatchRepository <|.. PostgresMatchRepository

This extension automatically generates a table of contents on the right side of the page for any page with at least two headings.

The permalink option adds a clickable anchor link (¶) next to each heading when you hover over it. This allows you to get a direct link to any section of a page, making it easy to share references with others. Just hover over a heading on this page to see it in action!