MkDocs Formatting

A comprehensive guide to MkDocs formatting, highlighting its exclusive features. While MkDocs supports standard Markdown, this guide focuses solely on its unique enhancements. For general Markdown syntax, check Markdown Formatting.

⚠️ Admonitions (Notes, Warnings, Tips)

Use !!! for special alert boxes like notes, warnings, and tips.

!!! note
    This is an informational note.

!!! warning
    Be careful with this action!

!!! tip
    Here’s a useful tip for you!

!!! danger
    This is a dangerous operation.

OUTPUT

Note

This is an informational note.

Warning

Be careful with this action!

Tip

Here’s a useful tip for you!

Danger

This is a dangerous operation.

---

📂 Expandable Code Blocks (Collapsible Sections)

Basic Collapsible Code Block

Use ???+ to create expandable sections.

???+ note "Click to Expand"
    ```python
    def greet(name):
        return f"Hello, {name}!"
    ```

OUTPUT

Click to Expand

def greet(name):
    return f"Hello, {name}!"

Collapsible Code Block with Filename

Attach filenames to collapsible sections.

???+ info "View greet.py"
    ```python title="greet.py"
    def greet(name):
        return f"Hello, {name}!"
    ```

OUTPUT

View greet.py

greet.py

def greet(name):
    return f"Hello, {name}!"

Collapsible Code Block with Explanation

Combine text and collapsible code blocks for better explanation.

???+ warning "See Code with Explanation"
    Here's a simple Python function:

    ```python
    def square(num):
        return num * num
    ```

    This function takes a number and returns its square.

OUTPUT

See Code with Explanation

Here's a simple Python function:

def square(num):
    return num * num

This function takes a number and returns its square.

---

💻 Code Blocks

With Filename

Label the code block with a filename.

    ```python title="greet.py"
    def greet(name):
        return f"Hello, {name}!"
    ```

OUTPUT

greet.py

def greet(name):
    return f"Hello, {name}!"

With Line Numbers

Enable line numbers for better readability.

    ```python linenums="1"
    def greet(name):
        return f"Hello, {name}!"
    ```

OUTPUT

def greet(name):
    return f"Hello, {name}!"

With Highlighted Lines

Highlight specific lines in the code block.

    ```python hl_lines="2 4 6-8"
    def greet(name):
        message = f"Hello, {name}!" 
        print(message)  
        return message

    def farewell(name):
        message = f"Goodbye, {name}!" 
        print(message)
        return message  
    ```

OUTPUT

def greet(name):
    message = f"Hello, {name}!"  
    print(message)  
    return message

def farewell(name):
    message = f"Goodbye, {name}!"
    print(message)
    return message  

With Line Numbers and Highlighted Lines

    ```python linenums="1" hl_lines="2"
    def greet(name):
        message = f"Hello, {name}!"  # Highlighted
        return message
    ```

OUTPUT

def greet(name):
    message = f"Hello, {name}!"  # Highlighted
    return message

---

🏷️ Code Annotation

    ```python
    def greet(name):  # Function definition
        message = f"Hello, {name}!"  # (1)!  
        return message # (2)!
    ```
    { .annotate }

    1. Formats a greeting message using f-string.  
    2. Returns the formatted message. 


    Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
    { .annotate }

    1.  :man_raising_hand: I'm an annotation! I can contain `code`, __formatted
        text__, images, ... basically anything that can be expressed in Markdown.

OUTPUT

def greet(name):  # Function definition
    message = f"Hello, {name}!"  # (1)!  
    return message # (2)!

1. Formats a greeting message using f-string.
2. Returns the formatted message.

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

1. I'm an annotation! I can contain code, formatted text, images, ... basically anything that can be expressed in Markdown.

---