### Conventional Commit Examples

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/CONTRIBUTING.md

Examples demonstrating the correct format for different commit types.

```bash
git commit -m "fix(renderer): handle empty boundary labels"
```

```bash
git commit -m "docs(readme): add minimal usage example"
```

```bash
git commit -m "refactor(core): simplify relationship rendering"
```

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

### Install D2 CLI (Install Script)

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Installs the D2 CLI using the official installation script.

```bash
curl -fsSL https://d2lang.com/install.sh | sh -s --
```

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

### Install PlantUML and Graphviz on Ubuntu/Debian

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Install PlantUML and Graphviz using apt on Ubuntu/Debian for local rendering.

```bash
sudo apt install plantuml graphviz
```

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

### Install c4-diagrams using uv

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Use this command to install the base c4-diagrams package with uv.

```bash
uv add c4-diagrams
```

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

### Install c4-diagrams with watch extra using uv

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Install the 'watch' extra with uv to enable CLI watch mode for rendering.

```bash
uv add "c4-diagrams[watch]"
```

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

### Install Project Dependencies

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/CONTRIBUTING.md

Install all project dependencies, including extras, using uv. This command ensures all necessary packages for development are available.

```bash
uv sync --all-extras
```

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

### Verify PlantUML and Graphviz installation

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Verify the installed versions of PlantUML and Graphviz executables.

```bash
plantuml -version
dot -V
```

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

### Install PlantUML and Graphviz on macOS

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Install PlantUML and Graphviz using Homebrew on macOS for local rendering.

```bash
brew install plantuml graphviz
```

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

### Install D2 CLI (macOS Homebrew)

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Installs the D2 CLI using Homebrew on macOS.

```bash
brew install d2
```

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

### Install c4-diagrams with converters extra using uv

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Install the 'converters' extra with uv to enable JSON conversion features and CLI JSON loading.

```bash
uv add c4-diagrams[converters]
```

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

### Portable Core Diagram Example

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/concepts/portable-core-and-extensions.md

This example demonstrates creating a diagram using only portable C4 elements and relationships, suitable for rendering by multiple backends like PlantUML, Mermaid, or D2.

```python
from c4 import Person, Rel, System, SystemContextDiagram


with SystemContextDiagram("Order Processing") as diagram:
    customer = Person("Customer", "Places orders")
    order_system = System("Order System", "Processes customer orders")

    customer >> Rel("Places orders using") >> order_system


plantuml_source = diagram.as_plantuml()
mermaid_source = diagram.as_mermaid()
d2_source = diagram.as_d2()
```

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

### Install Pre-commit Hooks

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/CONTRIBUTING.md

Install pre-commit hooks to automatically run formatters and linters before each commit. This helps maintain code quality and consistency.

```bash
uv run pre-commit install
```

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

### Render diagrams with different backends

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Command-line examples for rendering diagrams using PlantUML, Mermaid, or D2 backends.

```bash
c4 render diagram.py --plantuml
c4 render diagram.py --mermaid
c4 render diagram.py --d2
```

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

### Install c4-diagrams

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/README.md

Install the c4-diagrams package using pip. Requires Python 3.10 or higher.

```bash
pip install c4-diagrams
```

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

### Regenerate documentation artifacts

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/CONTRIBUTING.md

Run this command to regenerate checked-in example artifacts from source files.

```bash
make generate-docs-artifacts
```

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

### PlantUML Local Include Example

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/plantuml/limitations.md

Demonstrates how to use the RELATIVE_INCLUDE PlantUML variable to point to a local C4-PlantUML checkout for reproducible builds.

```shell
plantuml -DRELATIVE_INCLUDE=/path/to/C4-PlantUML diagram.puml
```

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

### Install Mermaid CLI

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Installs the global Mermaid CLI package. Ensure you are using version 11.4.0 or higher.

```bash
npm install -g @mermaid-js/mermaid-cli@11.4.0
```

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

### Advanced SystemContextDiagram JSON Example

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/converters/json/specs/core.system_context_diagram.md

Illustrates a more complex SystemContextDiagram with additional configurations. Use this example to explore advanced features and relationships.

```json
--8<-- "assets/examples/json/core/system-context-diagram.advanced.json"
```

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

### D2 Deployment Diagram

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/examples/index.md

Renders a deployment diagram using D2. This example uses default backend rendering.

```d2
![D2 deployment example](../assets/examples/d2/common-deployment-diagram.png)
```

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

### Install c4-diagrams with converters extra using pip

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Install the 'converters' extra with pip to enable JSON conversion features and CLI JSON loading.

```bash
pip install c4-diagrams[converters]
```

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

### Minimal SystemContextDiagram JSON Example

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/converters/json/specs/core.system_context_diagram.md

Provides a basic structure for a SystemContextDiagram. This example is useful for understanding the essential fields required for a diagram.

```json
--8<-- "assets/examples/json/core/system-context-diagram.minimal.json"
```

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

### System Context Diagram Example

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/README.md

Defines a system context diagram for the Acme Shop Platform using c4-diagrams Python DSL. This example shows how to define people, systems, and relationships within an enterprise boundary.

```python
from c4 import (
    EnterpriseBoundary,
    Person,
    System,
    SystemContextDiagram,
    SystemExt,
)
from c4.contrib.plantuml import RelDown, RelRight


with SystemContextDiagram("Acme Shop Platform") as diagram:
    user = Person(
        "Customer",
        "A registered customer who browses products and places orders.",
    )

    with EnterpriseBoundary("Acme Corp"):
        web_app = System(
            "Web Application",
            "Customer-facing website for browsing products and placing orders.",
        )

        api_backend = System(
            "Backend API",
            "Handles authentication, order processing, and business logic.",
        )

    email_provider = SystemExt(
        "Email Provider",
        "Delivers transactional emails.",
    )

    user >> RelRight("Uses") >> web_app
    web_app >> RelRight("Calls API") >> api_backend
    api_backend >> RelDown("Sends emails via") >> email_provider

```

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

### Mermaid Deployment Diagram

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/examples/index.md

Renders a deployment diagram using Mermaid. This example uses default backend rendering.

```mermaid
![Mermaid deployment example](../assets/examples/mermaid/common-deployment-diagram.png)
```

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

### PlantUML Deployment Diagram

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/examples/index.md

Renders a deployment diagram using PlantUML. This example uses default backend rendering.

```plantuml
![PlantUML deployment example](../assets/examples/plantuml/common-deployment-diagram.png)
```

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

### Python System Landscape Diagram

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/examples/index.md

Generates a system landscape diagram using Python. This example uses default backend rendering.

```python
--8<-- "assets/examples/python/common/common-system-landscape-diagram.py"
```

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

### Python System Context Diagram

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/examples/index.md

Generates a system context diagram using Python. This example uses default backend rendering.

```python
--8<-- "assets/examples/python/common/common-system-context-diagram.py"
```

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

### D2 System Context Diagram

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/examples/index.md

Renders a system context diagram using D2. This example uses default backend rendering.

```d2
![D2 system context example](../assets/examples/d2/common-system-context-diagram.png)
```

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

### Initialize LocalPlantUMLBackend using a JAR file

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/plantuml/renderers.md

Sets up LocalPlantUMLBackend to execute PlantUML via a specified JAR file and Java binary.

```python
from pathlib import Path

backend = LocalPlantUMLBackend(
    plantuml_jar=Path("/opt/plantuml/plantuml.jar"),
    java_bin="java",
)
```

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

### Install Watch Mode Dependency

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/cli.md

Installs the optional dependency for watch mode, which enables automatic re-rendering when files change.

```shell
pip install "c4-diagrams[watch]"
```

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

### Initialize RemotePlantUMLBackend with default settings

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/plantuml/renderers.md

Creates a RemotePlantUMLBackend instance that connects to the default PlantUML server URL.

```python
from c4.renderers.plantuml import (
    PlantUMLRenderer,
    RemotePlantUMLBackend,
)

backend = RemotePlantUMLBackend()

renderer = PlantUMLRenderer(backend=backend)
```

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

### Initialize LocalPlantUMLBackend using system binary

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/plantuml/renderers.md

Instantiates LocalPlantUMLBackend to use the system's plantuml binary or JAR. It attempts to find 'plantuml' in PATH, then checks PLANTUML_JAR environment variable.

```python
from c4.renderers.plantuml import PlantUMLRenderer, LocalPlantUMLBackend

backend = LocalPlantUMLBackend()

renderer = PlantUMLRenderer(backend=backend)
```

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

### Initialize D2Renderer with Options

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/d2/options.md

Create a D2Renderer instance and pass D2RenderOptions directly to its constructor for rendering.

```python
from c4.renderers import D2Renderer

renderer = D2Renderer(render_options=options)
```

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

### Initialize LocalPlantUMLBackend with a specific binary path

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/plantuml/renderers.md

Configures LocalPlantUMLBackend to use a PlantUML executable located at a specified path.

```python
backend = LocalPlantUMLBackend(
    plantuml_bin="/usr/local/bin/plantuml",
)
```

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

### Render Diagram to D2 Source using Convenience Method

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/d2/renderers.md

Shows the convenience method `as_d2()` on a Diagram object for generating D2 source code without explicitly creating a renderer.

```python
diagram.as_d2()
```

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

### Minimal DynamicDiagram JSON

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/converters/json/specs/core.dynamic_diagram.md

A basic example of a DynamicDiagram JSON configuration.

```json
--8<-- "assets/examples/json/core/dynamic-diagram.minimal.json"
```

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

### Configure LocalMermaidBackend with System Binary

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/mermaid/renderers.md

Instantiate LocalMermaidBackend to use the 'mmdc' command-line tool for rendering. This backend is suitable for offline rendering when the Mermaid CLI is installed.

```python
from c4.renderers import MermaidRenderer, LocalMermaidBackend

backend = LocalMermaidBackend()

renderer = MermaidRenderer(backend=backend)
```

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

### Verify D2 CLI Version

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Checks if the D2 executable is installed and accessible.

```bash
d2 version
```

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

### Configure D2Renderer with Render Options

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/d2/renderers.md

Shows how to initialize a D2Renderer with specific D2 render options, such as direction and theme, to customize the generated D2 source.

```python
from c4.renderers import D2RenderOptions

renderer = D2Renderer(
    render_options=D2RenderOptions(direction="down", theme=300),
)

source = renderer.render(diagram)
```

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

### Verify Mermaid CLI Version

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/installation.md

Checks if the Mermaid CLI executable is installed and accessible.

```bash
mmdc --version
```

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

### Pass Render Options via Convenience Method

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/d2/renderers.md

Illustrates how to pass D2 render options, such as direction and theme, when using the `as_d2()` convenience method on a Diagram object.

```python
from c4.renderers import D2RenderOptions

source = diagram.as_d2(
    render_options=D2RenderOptions(direction="down", theme=300),
)
```

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

### Advanced DynamicDiagram JSON

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/converters/json/specs/core.dynamic_diagram.md

A more complex example of a DynamicDiagram JSON configuration with advanced features.

```json
--8<-- "assets/examples/json/core/dynamic-diagram.advanced.json"
```

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

### Minimal ContainerDiagram JSON

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/converters/json/specs/core.container_diagram.md

A basic example of a ContainerDiagram specification. This is useful for simple diagrams with few elements.

```json
--8<-- "assets/examples/json/core/container-diagram.minimal.json"
```

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

### Minimal DeploymentDiagram JSON

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/converters/json/specs/core.deployment_diagram.md

A basic example of a DeploymentDiagram JSON specification. This is useful for simple diagrams with few elements.

```json
--8<-- "assets/examples/json/core/deployment-diagram.minimal.json"
```

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

### PlantUML Enhanced Deployment Diagram Example

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/diagrams/deployment.md

This snippet utilizes PlantUML-specific extensions, node variants, and layout helpers for a more detailed deployment diagram. It requires the PlantUML rendering backend. The code is included via an asset file.

```python
--8<-- "assets/examples/plantuml/deployment-diagram.py"
```

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

### Dynamic Indexes Example

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/plantuml/dynamic-indexes.md

Demonstrates the usage of Index, LastIndex, SetIndex, increment, and set_index helpers for dynamic relationship ordering in PlantUML diagrams. These indexes are specific to the PlantUML renderer.

```python
from c4 import Container, DynamicDiagram, Person, Rel
from c4.contrib.plantuml import Index, LastIndex, RelR, SetIndex, increment, set_index


with DynamicDiagram("Order flow") as diagram:
    customer = Person("Customer")
    web = Container("Web App")
    api = Container("Orders API")
    payments = Container("Payments")

    customer >> Rel("Places order", plantuml={"index": Index()}) >> web
    web >> Rel("POST /orders", plantuml={"index": Index()}) >> api
    api >> RelR("Authorize payment", plantuml={"index": LastIndex()}) >> payments

    increment()
    api >> Rel("Create order", plantuml={"index": Index() - 1}) >> web

    set_index(10)
    web >> Rel("Send receipt", plantuml={"index": SetIndex(12) - 1}) >> customer
```

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

### Run unit tests

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/CONTRIBUTING.md

Execute this command to run the project's unit tests locally.

```bash
make test
```

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

### D2 CLI Options

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/cli.md

Configure the D2 executable path and layout engine for diagram rendering.

```shell
--d2-bin <path or command>
--d2-layout <dagre | elk>
```

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

### Render Diagram using Convenience Method

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/plantuml/renderers.md

Utilize the as_plantuml() convenience method on a diagram object to directly obtain its PlantUML source code.

```python
diagram.as_plantuml()
```

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

### D2 Dynamic Diagram

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/examples/index.md

Renders a dynamic diagram using D2. This example uses default backend rendering.

```d2
![D2 dynamic example](../assets/examples/d2/common-dynamic-diagram.png)
```

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

### Initialize RemotePlantUMLBackend with custom server and timeout

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/plantuml/renderers.md

Configures RemotePlantUMLBackend to use a specific PlantUML server URL and sets a custom rendering timeout.

```python
backend = RemotePlantUMLBackend(
    server_url="https://kroki.io/plantuml",
    timeout_seconds=10,
)
```

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

### Mermaid Dynamic Diagram

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/examples/index.md

Renders a dynamic diagram using Mermaid. This example uses default backend rendering.

```mermaid
![Mermaid dynamic example](../assets/examples/mermaid/common-dynamic-diagram.png)
```

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

### Save Diagram as D2 File using Convenience Method

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/d2/renderers.md

Demonstrates the convenience method `save_as_d2()` on a Diagram object for directly saving the D2 source code to a specified file.

```python
diagram.save_as_d2("diagram.d2")
```

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

### PlantUML Dynamic Diagram

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/examples/index.md

Renders a dynamic diagram using PlantUML. This example uses default backend rendering.

```plantuml
![PlantUML dynamic example](../assets/examples/plantuml/common-dynamic-diagram.png)
```

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

### Creating Reusable Element Factories with Properties

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/properties.md

Illustrates how to create a reusable element factory using `with_properties` and `functools.partial`. Any element created by this factory will automatically include the specified properties.

```python
from functools import partial

from c4 import Container, with_properties


PlatformContainer = with_properties(
    partial(Container, description="Owned by the platform team."),
    ("Team", "Platform"),
    ("Support", "24/7"),
)

app = PlatformContainer(label="App Service")
worker = PlatformContainer(label="Worker Service")
```

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

### Python Dynamic Diagram

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/examples/index.md

Generates a dynamic diagram using Python. This example uses default backend rendering.

```python
--8<-- "assets/examples/python/common/common-dynamic-diagram.py"
```

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

### Initialize LocalPlantUMLBackend with custom arguments

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/renderers/plantuml/renderers.md

Provides custom arguments for both the PlantUML executable and the Java runtime when using LocalPlantUMLBackend.

```python
backend = LocalPlantUMLBackend(
    plantuml_args=["-DPLANTUML_LIMIT_SIZE=8192"],
    java_args=["-Xmx1024m"],
)
```

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

### D2 Component Diagram

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/examples/index.md

Renders a component diagram using D2. This example uses default backend rendering.

```d2
![D2 component example](../assets/examples/d2/common-component-diagram.png)
```

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

### Mermaid Component Diagram

Source: https://github.com/sidorov-as/c4-diagrams/blob/main/docs/examples/index.md

Renders a component diagram using Mermaid. This example uses default backend rendering.

```mermaid
![Mermaid component example](../assets/examples/mermaid/common-component-diagram.png)
```