mkdocs-shadcn

If you are currently using mkdocs-material, consider the following before migrating:

• Do not migrate if your documentation relies heavily on the specific features, plugins, or extensions provided by mkdocs-material, as it is a highly mature and feature-rich theme.
• Consider migrating if your documentation has minimal extension/plugin dependencies, or if you are starting a brand new project and want the shadcn aesthetic.

You cannot use fenced_code blocks inside an admonition because fenced code blocks are only supported at the document root level.

However, you can nest codehilite blocks inside an admonition. When doing so, ensure the code block is properly indented relative to the admonition marker.

!!! note "Admonition + Code"
    You may face the limits of `codehilite` however.

        :::python
        def fibonacci(n):
            a, b = 0, 1
            for _ in range(n):
                yield a
                a, b = b, a + b

        for num in fibonacci(10):
            print(num)

The plugin uses a two-step process: labeling and referencing.

1. Labeling

Place a label inline where you want the number to appear using the syntax {#prefix:unique-id}. This is replaced by a <span> containing the mapped prefix and the current number.

2. Referencing

To create a clickable link to a labeled element, use the syntax @prefix:unique-id. This creates an <a> tag that links to the element's canonical URL and ID.

Tip: Using a capitalized prefix (e.g., @Prefix:unique-id) will result in a capitalized mapped name in the rendered output.

{#fig:mountain}

@Fig:mountain is awesome!

Standard <input type="range"> elements are rendered as styled sliders.

To create a rich UI for a slider, wrap it in a <fieldset>. This allows you to include a <label>, a hint using <small>, and a live value display using <output>. To make the <output> update dynamically, you must provide an oninput handler to sync the element's value with the output text.

<fieldset>
    <label for="slider">Slider</label>
    <output for="slider">5</output>
    <input id="slider" type="range" min="0" max="10" value="5" step="0.1" oninput="document.querySelector(`output[for='${event.target.id}']`).textContent = event.target.value;"/>
    <small>Choose it carefully</small>
</fieldset>

To use the Hover Card extension in your MkDocs project, add shadcn.extensions.hover_card to the markdown_extensions list in your mkdocs.yml configuration file.

# mkdocs.yml

markdown_extensions:
  - shadcn.extensions.hover_card

If the attr_list extension is enabled, you can add CSS classes or IDs to a code block by placing them inside curly braces {} after the language name.

Warning: If codehilite is enabled, attr_list key/value attributes are not supported; codehilite expects Pygments HTML formatter options instead.

def fibonacci(n):
    a, b = 0, 1
    for _ in range(n):
        yield a
        a, b = b, a + b

for num in fibonacci(10):
    print(num)

To use custom HTML attributes on Markdown elements, you must enable the attr_list extension in your mkdocs.yml configuration file under the markdown_extensions key.

# mkdocs.yml

markdown_extensions:
  - attr_list

Once the extension is enabled, you can apply syntax highlighting to code blocks using either the colon syntax or standard backticks. Ensure you specify the language (e.g., python) to trigger the correct highlighting.

### Colon Syntax
:::python
import numpy as np
:::

### Backticks Syntax
```python
import numpy as np

You can add footnotes to your documentation using standard Markdown footnote syntax. This allows you to provide supplemental information or references that are linked to specific points in your text.

To use a footnote:

1. Place a label in the text using the [^label] syntax.
2. Define the footnote content at the bottom of the document (or anywhere in the body) using [^label]: content.

Labels can consist of alphanumeric characters and common symbols like @#$%.

Footnotes[^1] have a label[^@#$%] and the footnote's content.

[^1]: This is a footnote content.
[^@#$%]: A footnote on the label: "@#$%".

You can define page-specific metadata using YAML front-matter at the top of your Markdown files. This allows you to customize the title, subtitle (summary), and SEO attributes for individual pages.

title: My Page Title
summary: This is the subtitle or summary text