Markdown Tips¶

Advanced Markdown features enabled by PyMdown Extensions.

Keyboard Keys¶

Show keyboard shortcuts:

Press ++ctrl+alt+delete++ to restart.
Use ++cmd+c++ to copy.
Press ++enter++ to submit.

Press Ctrl+Alt+Del to restart. Use Cmd+C to copy.

Emoji¶

Add emoji with shortcodes:

:smile: :rocket: :tada: :fire: :heart:
:snake: :computer: :book: :bulb: :warning:

Full emoji list

Smart Symbols¶

Automatic symbol replacement:

(c) (r) (tm)
c/o +/- -->
!=  =/= 1/4 1st 2nd

© ® ™
℅ ± →
!= ≠ ¼ 1^st 2^nd

Superscript and Subscript¶

H~2~O (subscript)
X^2^ + Y^2^ = Z^2^ (superscript)

H₂O
X² + Y² = Z²

Highlighting¶

Mark important text:

==This is highlighted text==

This is highlighted text

Insertion and Deletion¶

Show edits:

~~Deleted text~~
^^Inserted text^^

~~Deleted text~~
Inserted text

Abbreviations¶

Define abbreviations that show on hover:

The HTML specification is maintained by the W3C.

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

The HTML specification is maintained by the W3C.

(Hover over HTML and W3C to see definitions)

Definition Lists¶

Term 1
:   Definition for term 1

Term 2
:   Definition for term 2
:   Another definition for term 2

Term 1: Definition for term 1
Term 2: Definition for term 2; Another definition for term 2

Footnotes¶

Add footnotes to your content:

Here's a sentence with a footnote[^1].

[^1]: This is the footnote content.

Here's a sentence with a footnote¹.

Content Tabs¶

Create tabbed content:

=== "Python"

    ```python
    def hello():
        print("Hello!")
    ```

=== "JavaScript"

    ```javascript
    function hello() {
        console.log("Hello!");
    }
    ```

=== "Ruby"

    ```ruby
    def hello
        puts "Hello!"
    end
    ```

PythonJavaScriptRuby

def hello():
    print("Hello!")

function hello() {
    console.log("Hello!");
}

def hello
    puts "Hello!"
end

Nested Lists¶

Complex list structures:

1. First item

   This is the first item's content.

   - Nested bullet point
   - Another one

2. Second item

   ```python
   # Code in a list
   print("hello")
   ```

3. Third item

First item

This is the first item's content.

Nested bullet point
Another one
Second item

# Code in a list
print("hello")

Third item

Admonition Types¶

All available admonition types:

!!! note
    Informational note.

!!! abstract
    Summary or abstract.

!!! info
    Additional information.

!!! tip
    Helpful tip.

!!! success
    Success message.

!!! question
    Question or FAQ.

!!! warning
    Warning message.

!!! failure
    Error or failure.

!!! danger
    Danger warning.

!!! bug
    Known bug.

!!! example
    Example content.

!!! quote
    Quotation.

Note

Informational note.

Tip

Helpful tip.

Warning

Warning message.

Danger

Danger warning.

Inline Code with Highlighting¶

Highlight specific parts of inline code:

The function `#!python print("hello")` outputs text.
Run `#!bash ls -la` to list files.

The function print("hello") outputs text.

Math (MathJax/KaTeX)¶

If you've enabled math support, you can write equations:

Inline math:

The formula \(E = mc^2\) is Einstein's famous equation.

Block math:

$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

\[ \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} \]

Attribute Lists¶

Add CSS classes and IDs to elements:

This paragraph has a class. { .special-class }

## Header with ID { #custom-id }

![Image with attributes](image.png){ width="300" }

[Link with title](https://example.com){ target="_blank" }

Grid Cards¶

Create card layouts:

<div class="grid cards" markdown>

- :material-clock-fast: **Quick Setup**

  ---

  Get started in under 5 minutes

- :material-check-bold: **Easy to Use**

  ---

  Simple and intuitive interface

- :material-scale-balance: **Open Source**

  ---

  MIT licensed

- :material-account-group: **Community**

  ---

  Join our growing community

</div>

Buttons¶

Create button-style links:

[Get Started :material-arrow-right:](#){ .md-button }
[Download :material-download:](#){ .md-button .md-button--primary }

Details/Summary¶

Collapsible sections:

<details>
<summary>Click to expand</summary>

Hidden content goes here.

- Can include
- Any markdown
- Elements

</details>

Click to expand

Hidden content goes here. - Can include - Any markdown - Elements

Tables with Complex Content¶

Tables can contain rich content:

| Feature | Basic | Pro |
|---------|-------|-----|
| Storage | 5 GB  | Unlimited |
| Support | Email | 24/7 Phone |
| Price   | Free  | $10/mo |

Critical and Criticmark¶

Show important text:

^^This is inserted^^

~~This is deleted~~

{~~Deleted~>Replaced~~}

{++Added++}

{==Highlighted==}

Progress Bars¶

[=0% "0%"]
[=25% "25%"]
[=50% "50%"]
[=75% "75%"]
[=100% "100%"]

Snippets¶

Include content from other files:

--8<-- "includes/abbreviations.md"

Custom Fences¶

Create custom code blocks:

```mermaid
graph LR
    A[Start] --> B[Process]
    B --> C[End]
```

Using HTML¶

You can mix HTML with Markdown:

<div style="border: 2px solid blue; padding: 1em;">

This is **Markdown** inside HTML.

</div>

<center>
Centered text
</center>

This is **Markdown** inside HTML.

Line Numbers in Code¶

```python linenums="1"
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)
```

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

Code with Title¶

```python title="fibonacci.py"
def fib(n):
    return n if n <= 1 else fib(n-1) + fib(n-2)
```

fibonacci.py

def fib(n):
    return n if n <= 1 else fib(n-1) + fib(n-2)

Icons¶

Use Material Design icons:

:material-account: User Account
:fontawesome-brands-github: GitHub
:octicons-mark-github-16: Octicons

User Account
GitHub

Tips for Using These Features¶

Don't Overdo It

Use these features purposefully. Too many special effects can be distracting.

Check Compatibility

Make sure the extensions you need are enabled in mkdocs.yml.

Mix and Match

Combine features thoughtfully:

Example 1Example 2

With Tabs

Admonitions inside tabs!

Feature	Enabled
Tables
Tabs

Enabling Extensions¶

To use these features, ensure your mkdocs.yml includes:

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - pymdownx.arithmatex
  - pymdownx.betterem
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
  - pymdownx.highlight
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

Learning More¶

Next Steps¶

Code Blocks - Advanced code features
Diagrams - Create visual diagrams
Writing Pages - Back to basics

Experiment and have fun! 🎨

This is the footnote content. ↩