### Run Demo App Locally

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/README.md

Set up and run the demo application locally. This involves creating a virtual environment, installing dependencies, and serving the MkDocs site.

```bash
cd docs
python3 -m venv .venv
source .venv/bin/activate
pip install mkdocs-material mkdocs-d2-plugin
mkdocs serve
```

--------------------------------

### Install mkdocs-d2-plugin

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/index.md

Install the plugin using pip. This command installs the necessary package for the plugin.

```bash
pip install mkdocs-d2-plugin
```

--------------------------------

### Fenced Code Block Example: Target Rendering

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/configuration.md

Example showing how to render a specific target from multiple scenarios defined within a D2 diagram, using fenced code block configuration.

```d2
scenarios: {
    main: {
        Bob -> Alice
    }

    alternative: {
        Alice -> Bob
    }
}
```

--------------------------------

### External D2 File with Layout and Theme Overrides

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Customize the rendering of external D2 diagrams using the `attr_list` syntax `{key=value}`. This example overrides the theme and layout engine.

```markdown
![Cloud architecture](cloud.d2){theme=101 layout=elk}
```

--------------------------------

### Fenced Code Block with Custom Options

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Customize diagram rendering using key-value pairs on the opening fence line. Quotes around values are mandatory. This example sets padding, scale, and alt text.

```markdown
```d2 pad="20" scale="0.7" alt="Alice and John sequence diagram"
shape: sequence_diagram
Alice -> John: Hello John, how are you?
Alice -> John.ack: John, can you hear me?
John.ack -> Alice: Hi Alice, I can hear you!
John -> Alice: I feel great!
```
```

--------------------------------

### Link to D2 Diagram in Different Directory

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/usage.md

When the D2 diagram file is not in the same directory as the markdown file, use a relative path to link to it. This example shows linking from 'usage.md' to 'flow.d2'.

```markdown
![Diagram](../flow.d2)
```

--------------------------------

### Run Demo App with Docker

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/README.md

Build and run the demo application using Docker. This command maps the local docs directory to the container and exposes the necessary port.

```bash
cd docs
docker build --tag mkdocs-d2-plugin:latest .
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs mkdocs-d2-plugin:latest
```

--------------------------------

### Running MkDocs D2 Plugin Demo Locally

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Instructions for running the demo MkDocs site locally using a virtual environment or Docker. This allows testing all plugin features in a live environment.

```bash
# Run locally with a virtual environment
cd docs
python3 -m venv .venv
source .venv/bin/activate
pip install mkdocs-material mkdocs-d2-plugin
mkdocs serve
# Site available at http://127.0.0.1:8000

# Run with Docker
cd docs
docker build --tag mkdocs-d2-plugin:latest .
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs mkdocs-d2-plugin:latest
```

--------------------------------

### Full mkdocs.yml Configuration Options

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Configure all available d2 plugin options in mkdocs.yml. Options not listed use their defaults. 'executable', 'cache', and 'cache_dir' are plugin-level only.

```yaml
plugins:
  - d2:
      executable: d2          # Path or name of the d2 binary (default: "d2")
      cache: true             # Enable disk-based render cache (default: true)
      cache_dir: .cache/plugin/d2  # Cache directory (default: ".cache/plugin/d2")
      layout: dagre           # Layout engine: dagre, elk (default: "dagre")
      theme: 0                # D2 theme ID for light mode (default: 0)
      dark_theme: -1          # D2 theme ID for dark mode; -1 = disabled (default: -1)
      sketch: false           # Sketch/hand-drawn rendering style (default: false)
      pad: 100                # Padding in pixels around the diagram (default: 100)
      scale: -1.0             # Scale factor; -1.0 = auto-fit (default: -1.0)
      force_appendix: false   # Force appendix rendering (default: false)
      target: "''"            # Render only the named scenario target (default: "''")
```

--------------------------------

### D2 Import Syntax for Diagrams

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Demonstrates how to use D2's `@import` syntax to split diagram definitions across multiple files. Ensure the main `.d2` file is touched to force re-renders when imported files change.

```d2
# importer.d2
a: @imported
a -> b

# imported.d2
x: {
    shape: circle
}
```

```markdown
<!-- In a Markdown file — renders the composed diagram -->
![Diagram with import](importer.d2){pad="20" scale="1"}
```

--------------------------------

### Global Light/Dark Mode Configuration

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Configure MkDocs to render diagrams in both light and dark modes globally using the `d2` plugin in `mkdocs.yml`. This enables dual-rendering and applies theme IDs for each mode.

```yaml
# mkdocs.yml — enable light/dark switching globally
plugins:
  - d2:
      theme: 3          # light mode theme ID
      sketch: true
      dark_theme: 200   # dark mode theme ID; enables dual-render
```

--------------------------------

### Global Plugin Configuration

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/configuration.md

Configure the d2 plugin globally in your mkdocs.yml file. This applies to all diagrams unless overridden locally. Ensure the `executable` path is correct for your system.

```yaml
plugins:
  - d2:
      executable: d2 # path to d2 executable
      cache: True
      cache_dir: .config/plugin/d2
      layout: dagre
      theme: 0
      dark_theme: -1
      sketch: False
      pad: 100
      scale: -1.0
      force_appendix: False
      target: "''"
```

--------------------------------

### Image Tag Configuration

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/configuration.md

Configure diagram rendering using image tags and the `attr_list` extension. Quotes around values are optional, but whitespace before the opening brace is not allowed.

```markdown
![Diagram](diagram.d2){sketch="True" pad="30"}
```

```markdown
![Cloud](cloud.d2){theme=101 layout=elk}
```

```markdown
![Cloud](cloud.d2){theme=101 layout=elk pad=20 scale=0.8}
```

--------------------------------

### Layout Engine and Extra Options

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Specify a D2 layout engine (e.g., 'elk') and pass engine-specific options using underscore-separated names in Markdown. The plugin converts these to hyphenated CLI arguments.

```markdown
<!-- Use ELK layout with an engine-specific option (elk_nodeSelfLoop) -->
```d2 layout="elk" elk_nodeSelfLoop="10"
self -> other
```
```

```yaml
# mkdocs.yml — set ELK as the global layout engine
plugins:
  - d2:
      layout: elk
```

--------------------------------

### External D2 File with Dark Theme Override

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Specify a `dark_theme` for external D2 diagrams to enable light/dark mode switching. Use `attr_list` syntax for options.

```markdown
![Cloud architecture](cloud.d2){dark_theme="201" pad="20" scale="0.8"}
```

--------------------------------

### External D2 File with Padding and Scale

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Adjust the padding and scale of external D2 diagrams using `attr_list` syntax. Ensure no space before the opening brace.

```markdown
![Cloud architecture](cloud.d2){theme=101 layout=elk pad=20 scale=0.8}
```

--------------------------------

### Configure mkdocs.yml for d2 plugin

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/index.md

Add the d2 plugin to your mkdocs.yml configuration file. This enables the plugin's functionality within your MkDocs project.

```yaml
plugins:
  - d2
```

--------------------------------

### Conceptual Render Cache Key Construction

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Illustrates how the internal `render` function constructs cache keys for D2 diagrams using SHA-1 hashing of source content and render options. This is used for efficient caching of SVG output.

```python
# Conceptual illustration of the render cache key construction
import hashlib

# For inline source (bytes)
source_hex = source_bytes.hex()          # e.g. "426f62202d3e20416c696365"
key_parts  = source_hex + "." + "--layout=dagre" + "." + "--theme=0"
cache_key  = hashlib.sha1(key_parts.encode()).digest()

# For file source (Path)
key_parts  = f"{path}_{path.stat().st_mtime}" + "." + "--layout=dagre"
cache_key  = hashlib.sha1(key_parts.encode()).digest()

# Cache miss → invoke d2 CLI
# subprocess.run(["d2", "--layout=dagre", "--theme=0", "-", "-"], input=source_bytes, capture_output=True)

# Cache hit → return cached SVG string directly
svg_string = cache[cache_key].decode()
```

--------------------------------

### Link to D2 Diagram in Markdown

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/README.md

Alternatively, link to a D2 diagram file using standard Markdown image syntax.

```markdown
![Diagram](diagram.d2)
```

--------------------------------

### Local Configuration for D2 Options

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/configuration.md

Override specific D2 options locally using a bash-like syntax within fenced code blocks. Note the use of underscores instead of hyphens for option names.

```markdown
```d2 elk_nodeSelfLoop="10"
self -> other
```
```

--------------------------------

### Fenced Code Block Configuration

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/configuration.md

Configure diagram rendering directly within fenced code blocks using key="value" pairs. Quotes around values are mandatory. The `render="False"` option disables diagram rendering.

```markdown
```d2 pad="20" scale="0.8"
Bob -> Alice
```
```

```markdown
```d2 render="False"
Bob -> Alice
```
```

```markdown
```d2 target="alternative"
scenarios: {
    main: {
        Bob -> Alice
    }

    alternative: {
        Alice -> Bob
    }
}
```
```

--------------------------------

### Apply Dark Theme with Padding and Scaling

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/configuration.md

Customize the D2 diagram's appearance further by applying a dark theme along with padding and scaling attributes. This allows for fine-tuning the visual presentation.

```markdown
![Cloud](cloud.d2){dark_theme="201" pad="20" scale="0.8"}
```

--------------------------------

### Reference External D2 File

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Include diagrams from external `.d2` files using standard Markdown image syntax. Only local `.d2` files are processed.

```markdown
![Flow diagram](../flow.d2)
```

--------------------------------

### Include D2 Diagrams with Imports

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/usage.md

Diagrams included via image tags support D2's import feature. This allows you to modularize your diagrams. Ensure the paths are correct relative to the main diagram file.

```d2
a: @imported
a -> b
```

```d2
x: {
    shape: circle
}
```

```markdown
![Diagram](../importer.d2)
```

--------------------------------

### Basic Sequence Diagram Definition

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Define a sequence diagram using D2 syntax within a fenced code block.

```d2
shape: sequence_diagram

mkdocs: MkDocs { link: https://www.mkdocs.org }
plugin: mkdocs-d2-plugin { link: https://github.com/landmaj/mkdocs-d2-plugin }
d2: D2 { link: https://d2lang.com }

mkdocs -> mkdocs: build/serve
mkdocs -> plugin: diagram definition
subprocess: {
    plugin -> d2.sub: compile
    d2.sub -> plugin: svg
}
plugin -> mkdocs: svg
```

--------------------------------

### Image Tag with Attributes

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/usage.md

You can add attributes like 'pad' and 'scale' directly to the image tag for controlling the rendered diagram's appearance. These attributes are passed to the D2 renderer.

```markdown
![Diagram with import](importer.d2){pad="20" scale="1"}
```

--------------------------------

### Accessibility with Alt Text in Image Tag

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/usage.md

Provide accessibility by setting the alt text in the image tag. This text will be used by screen readers and for SEO purposes.

```xml
<svg aria-label="ALT TEXT" role="img">
```

```markdown
![ALT TEXT](diagram.d2)
```

--------------------------------

### Render Specific Target in Fenced Code Block

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Use the `target` option to render only a specific named scenario within a D2 diagram that defines multiple scenarios.

```markdown
```d2 target="alternative"
scenarios: {
    main: {
        Bob -> Alice
    }
    alternative: {
        Alice -> Bob
    }
}
```
```

--------------------------------

### Apply Dark Theme to D2 Diagram

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/configuration.md

Use the `dark_theme` attribute to specify a dark theme for the D2 diagram. This is useful for matching the diagram's appearance to the website's theme.

```markdown
![Cloud](cloud.d2){dark_theme="201"}
```

--------------------------------

### CSS for Custom Color Schemes

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/configuration.md

Add these CSS selectors to your MkDocs Material theme configuration when using custom color schemes to manage light/dark mode rendering of D2 diagrams.

```css
[data-md-color-scheme="custom-light"] div.d2-dark {
    display: none; /* Hide light images in light mode */
}

[data-md-color-scheme="custom-dark"] div.d2-light {
    display: none; /* Hide light images in dark mode */
}
```

--------------------------------

### Per-Diagram Light/Dark Mode Override

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Override global light/dark mode settings for individual diagrams using attributes in the Markdown image tag. Set `dark_theme` to a specific theme ID or `-1` to disable dark mode for that diagram.

```markdown
<!-- Per-diagram dark theme override -->
![Cloud](cloud.d2){dark_theme="201"}

<!-- Disable dark theme for a specific diagram even when set globally -->
![Cloud](cloud.d2){dark_theme="-1"}
```

--------------------------------

### Basic Sequence Diagram in Fenced Code Block

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Embed a D2 sequence diagram using a fenced code block with the 'd2' language identifier. The diagram will be rendered as an inline SVG.

```markdown
```d2
shape: sequence_diagram
Alice -> John: Hello John, how are you?
Alice -> John.ack: John, can you hear me?
John.ack -> Alice: Hi Alice, I can hear you!
John -> Alice: I feel great!
```
```

--------------------------------

### Custom MkDocs Material Color Scheme CSS

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Add custom CSS to your MkDocs Material theme to correctly hide the appropriate SVG variant (light or dark) based on the active color scheme. This ensures only the correct mode's SVG is displayed.

```css
/* Required addition for custom MkDocs Material color schemes */
[data-md-color-scheme="custom-light"] div.d2-dark {
    display: none; /* Hide dark SVG in light mode */
}

[data-md-color-scheme="custom-dark"] div.d2-light {
    display: none; /* Hide light SVG in dark mode */
}
```

--------------------------------

### Disable Rendering of Fenced Code Block

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Prevent a D2 code block from rendering as SVG by setting `render="False"`. The raw D2 source will be displayed as a code block instead.

```markdown
```d2 render="False"
Bob -> Alice
```
```

--------------------------------

### Accessibility with Alt Attribute in Fenced Code Block

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/docs/docs/guide/usage.md

Alternatively, specify accessibility alt text using the 'alt' attribute directly within the D2 fenced code block. If no 'alt' attribute is provided, the default value 'Diagram' is used.

```d2
shape: sequence_diagram
A -> B: C
```

--------------------------------

### Accessibility Attributes for Diagrams

Source: https://context7.com/landmaj/mkdocs-d2-plugin/llms.txt

Generated SVGs automatically include `role="img"` and `aria-label` attributes for accessibility. The `aria-label` is derived from the Markdown alt text or the `alt` option in fenced blocks.

```markdown
<!-- Image tag: alt text becomes aria-label -->
![Architecture overview of the payment service](payment.d2)

<!-- Fenced block: explicit alt attribute -->
```d2 alt="Architecture overview of the payment service"
payment -> db: query
db -> payment: result
```

<!-- Fenced block without alt: defaults to "Diagram" -->
```d2
Bob -> Alice
```
```

```xml
<!-- Resulting SVG output (aria attributes injected automatically) -->
<svg role="img" aria-label="Architecture overview of the payment service">
  ...
</svg>
```

--------------------------------

### Embed D2 Diagram in Markdown

Source: https://github.com/landmaj/mkdocs-d2-plugin/blob/master/README.md

Embed D2 diagrams using a fenced code block with the 'd2' language specifier in your Markdown files.

```d2
shape: sequence_diagram
Alice -> John: Hello John, how are you?
Alice -> John.ack: John, can you hear me?
John.ack -> Alice: Hi Alice, I can hear you!
John -> Alice: I feel great!
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.