unifi-network-maps 1.3.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

unifi_network_maps/render/lldp_md.py

@@ -0,0 +1,275 @@
+"""Render LLDP data as Markdown tables."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from ..model.lldp import LLDPEntry, local_port_label
+from ..model.topology import Device, build_client_port_map, build_device_index, build_port_map
+from .device_ports_md import render_device_port_details
+
+
+def _normalize_mac(value: str) -> str:
+    return value.strip().lower()
+
+
+def _client_field(client: object, name: str) -> object | None:
+    if isinstance(client, dict):
+        return client.get(name)
+    return getattr(client, name, None)
+
+
+def _client_display_name(client: object) -> str | None:
+    for key in ("name", "hostname", "mac"):
+        value = _client_field(client, key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _client_uplink_mac(client: object) -> str | None:
+    for key in ("ap_mac", "sw_mac", "uplink_mac", "uplink_device_mac", "last_uplink_mac"):
+        value = _client_field(client, key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    for key in ("uplink", "last_uplink"):
+        nested = _client_field(client, key)
+        if isinstance(nested, dict):
+            value = nested.get("uplink_mac") or nested.get("uplink_device_mac")
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+    return None
+
+
+def _client_uplink_port(client: object) -> int | None:
+    for key in ("uplink_remote_port", "sw_port", "ap_port"):
+        value = _client_field(client, key)
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str) and value.isdigit():
+            return int(value)
+    for key in ("uplink", "last_uplink"):
+        nested = _client_field(client, key)
+        if isinstance(nested, dict):
+            value = nested.get("uplink_remote_port")
+            if isinstance(value, int):
+                return value
+            if isinstance(value, str) and value.isdigit():
+                return int(value)
+    return None
+
+
+def _client_is_wired(client: object) -> bool:
+    return bool(_client_field(client, "is_wired"))
+
+
+def _client_matches_mode(client: object, mode: str) -> bool:
+    wired = _client_is_wired(client)
+    if mode == "all":
+        return True
+    if mode == "wireless":
+        return not wired
+    return wired
+
+
+def _lldp_sort_key(entry: LLDPEntry) -> tuple[int, str, str]:
+    port_label = local_port_label(entry) or ""
+    port_number = "".join(ch for ch in port_label if ch.isdigit())
+    return (int(port_number or 0), port_label, entry.port_id)
+
+
+def _device_header_lines(device: Device) -> list[str]:
+    return [f"## {device.name}"]
+
+
+def _port_summary(device: Device) -> str:
+    ports = [port for port in device.port_table if port.port_idx is not None]
+    if not ports:
+        return "-"
+    total_ports = len(ports)
+    poe_capable = sum(1 for port in ports if port.port_poe or port.poe_enable)
+    poe_active = sum(1 for port in ports if device.poe_ports.get(port.port_idx or -1))
+    total_power = sum(port.poe_power or 0.0 for port in ports)
+    summary = f"Total {total_ports}, PoE {poe_capable} (active {poe_active})"
+    if total_power > 0:
+        summary = f"{summary}, {total_power:.2f}W"
+    return summary
+
+
+def _poe_summary(device: Device) -> str:
+    ports = [port for port in device.port_table if port.port_idx is not None]
+    if not ports:
+        return "-"
+    poe_capable = sum(1 for port in ports if port.port_poe or port.poe_enable)
+    poe_active = sum(1 for port in ports if (port.poe_power or 0.0) > 0 or port.poe_good)
+    total_power = sum(port.poe_power or 0.0 for port in ports)
+    summary = f"{poe_capable} capable, {poe_active} active"
+    if total_power > 0:
+        summary = f"{summary}, {total_power:.2f}W"
+    return summary
+
+
+def _uplink_summary(device: Device) -> str:
+    uplink = device.uplink or device.last_uplink
+    if not uplink:
+        return "-"
+    name = uplink.name or uplink.mac or "Unknown"
+    if uplink.port is not None:
+        return f"{name} (Port {uplink.port})"
+    return name
+
+
+def _client_summary(
+    device: Device, client_rows: dict[str, list[tuple[str, str | None]]]
+) -> tuple[str, str]:
+    rows = client_rows.get(device.name)
+    if rows is None:
+        return "-", "-"
+    count = len(rows)
+    names = [name for name, _port in rows]
+    sample = ", ".join(names[:3])
+    if len(names) > 3:
+        sample = f"{sample}, ..."
+    return str(count), sample or "-"
+
+
+def _details_table_lines(
+    device: Device,
+    client_rows: dict[str, list[tuple[str, str | None]]],
+    client_mode: str,
+) -> list[str]:
+    wired_count, client_sample = _client_summary(device, client_rows)
+    client_label = f"Clients ({client_mode})"
+    lines = [
+        "### Details",
+        "",
+        "| Field | Value |",
+        "| --- | --- |",
+        f"| Model | {_escape_cell(device.model_name or device.type or '-')} |",
+        f"| Type | {_escape_cell(device.type or '-')} |",
+        f"| IP | {_escape_cell(device.ip or '-')} |",
+        f"| MAC | {_escape_cell(device.mac or '-')} |",
+        f"| Firmware | {_escape_cell(device.version or '-')} |",
+        f"| Uplink | {_escape_cell(_uplink_summary(device))} |",
+        f"| Ports | {_escape_cell(_port_summary(device))} |",
+        f"| PoE | {_escape_cell(_poe_summary(device))} |",
+        f"| {client_label} | {_escape_cell(wired_count)} |",
+        f"| Client examples | {_escape_cell(client_sample)} |",
+        "",
+    ]
+    return lines
+
+
+def _lldp_rows(
+    entries: Iterable[LLDPEntry],
+    device_index: dict[str, str],
+) -> list[list[str]]:
+    rows: list[list[str]] = []
+    for entry in sorted(entries, key=_lldp_sort_key):
+        local_label = local_port_label(entry) or "?"
+        peer_name = device_index.get(_normalize_mac(entry.chassis_id), "")
+        peer_port = entry.port_id or "?"
+        port_desc = entry.port_desc or ""
+        rows.append(
+            [
+                local_label,
+                peer_name or "-",
+                peer_port,
+                entry.chassis_id,
+                port_desc or "-",
+            ]
+        )
+    return rows
+
+
+def _escape_cell(value: str) -> str:
+    return value.replace("|", "\\|")
+
+
+def _client_rows(
+    clients: Iterable[object],
+    device_index: dict[str, str],
+    *,
+    include_ports: bool,
+    client_mode: str,
+) -> dict[str, list[tuple[str, str | None]]]:
+    rows_by_device: dict[str, list[tuple[str, str | None]]] = {}
+    for client in clients:
+        if not _client_matches_mode(client, client_mode):
+            continue
+        name = _client_display_name(client)
+        uplink_mac = _client_uplink_mac(client)
+        if not name or not uplink_mac:
+            continue
+        device_name = device_index.get(_normalize_mac(uplink_mac))
+        if not device_name:
+            continue
+        port_label = None
+        if include_ports:
+            uplink_port = _client_uplink_port(client)
+            if uplink_port is not None:
+                port_label = f"Port {uplink_port}"
+        rows_by_device.setdefault(device_name, []).append((name, port_label))
+    return rows_by_device
+
+
+def render_lldp_md(
+    devices: list[Device],
+    *,
+    clients: Iterable[object] | None = None,
+    include_ports: bool = False,
+    show_clients: bool = False,
+    client_mode: str = "wired",
+) -> str:
+    device_index = build_device_index(devices)
+    port_map = {}
+    client_port_map = None
+    client_rows = (
+        _client_rows(clients, device_index, include_ports=include_ports, client_mode=client_mode)
+        if clients
+        else {}
+    )
+    if include_ports:
+        port_map = build_port_map(devices, only_unifi=False)
+        if clients and show_clients:
+            client_port_map = build_client_port_map(devices, clients, client_mode=client_mode)
+    lines: list[str] = ["# LLDP Neighbors", ""]
+    for device in sorted(devices, key=lambda item: item.name.lower()):
+        lines.extend(_device_header_lines(device))
+        lines.append("")
+        lines.extend(_details_table_lines(device, client_rows, client_mode))
+        if include_ports:
+            lines.append("### Ports")
+            lines.append("")
+            lines.append(
+                render_device_port_details(device, port_map, client_ports=client_port_map).strip()
+            )
+        if device.lldp_info:
+            lines.append("")
+            lines.append(
+                "| Local Port | Neighbor | Neighbor Port | Chassis ID | Port Description |"
+            )
+            lines.append("| --- | --- | --- | --- | --- |")
+            for row in _lldp_rows(device.lldp_info, device_index):
+                lines.append("| " + " | ".join(_escape_cell(cell) for cell in row) + " |")
+            lines.append("")
+        else:
+            lines.append("_No LLDP neighbors._")
+            lines.append("")
+        rows = client_rows.get(device.name)
+        if rows and show_clients:
+            lines.append("")
+            lines.append("### Clients")
+            if include_ports:
+                lines.append("")
+                lines.append("| Client | Port |")
+                lines.append("| --- | --- |")
+                for client_name, port_label in rows:
+                    lines.append(
+                        f"| {_escape_cell(client_name)} | {_escape_cell(port_label or '-')} |"
+                    )
+            else:
+                for client_name, _port_label in rows:
+                    lines.append(f"- {_escape_cell(client_name)}")
+            lines.append("")
+    return "\n".join(lines).rstrip() + "\n"

unifi_network_maps/render/mermaid.py

@@ -71,6 +71,7 @@ def render_mermaid(
     id_map = _build_id_map(edge_list, group_nodes)
     lines = [f"graph {direction}"]
     poe_links: list[int] = []
+    wireless_links: list[int] = []
     link_index = 0
     if groups:
         ordered = group_order or list(groups.keys())
@@ -99,6 +100,8 @@ def render_mermaid(
             lines.append(f"  {left} --- {right};")
         if edge.poe:
             poe_links.append(link_index)
+        if edge.wireless:
+            wireless_links.append(link_index)
         link_index += 1
     if node_types:
         class_map = {
@@ -121,11 +124,24 @@ def render_mermaid(
             f"{index} stroke:{theme.poe_link},stroke-width:{theme.poe_link_width}px,"
             f"arrowhead:{theme.poe_link_arrow};"
         )
+    for index in wireless_links:
+        lines.append(f"  linkStyle {index} stroke-dasharray: 5 4;")
     return "\n".join(lines) + "\n"
 
 
-def render_legend(theme: MermaidTheme = DEFAULT_THEME) -> str:
+def render_legend(theme: MermaidTheme = DEFAULT_THEME, *, legend_scale: float = 1.0) -> str:
+    scale = legend_scale if legend_scale > 0 else 1.0
+    legend_font_size = max(7, round(10 * scale))
+    poe_link_width = max(1, round(theme.poe_link_width * scale))
+    standard_link_width = max(1, round(theme.standard_link_width * scale))
+    node_spacing = max(10, round(50 * scale))
+    rank_spacing = max(10, round(50 * scale))
+    node_padding = max(4, round(12 * scale))
     lines = [
+        "%%{init: {"
+        f'"flowchart": {{"nodeSpacing": {node_spacing}, "rankSpacing": {rank_spacing}}}, '
+        f'"themeVariables": {{"fontSize": "{legend_font_size}px", "nodePadding": {node_padding}}}'
+        "}}%%",
         "graph TB",
         '  subgraph legend["Legend"];',
         '    legend_gateway["Gateway"];',
@@ -153,14 +169,62 @@ def render_legend(theme: MermaidTheme = DEFAULT_THEME) -> str:
         "  class legend_no_poe_b node_legend;",
     ]
     lines.extend(class_defs(theme))
+    lines.append(f"  classDef node_legend font-size:{legend_font_size}px;")
     lines.append(
         "  linkStyle 0 "
-        f"stroke:{theme.poe_link},stroke-width:{theme.poe_link_width}px,"
+        f"stroke:{theme.poe_link},stroke-width:{poe_link_width}px,"
         f"arrowhead:{theme.poe_link_arrow};"
     )
     lines.append(
         "  linkStyle 1 "
-        f"stroke:{theme.standard_link},stroke-width:{theme.standard_link_width}px,"
+        f"stroke:{theme.standard_link},stroke-width:{standard_link_width}px,"
         f"arrowhead:{theme.standard_link_arrow};"
     )
     return "\n".join(lines) + "\n"
+
+
+def render_legend_compact(theme: MermaidTheme = DEFAULT_THEME) -> str:
+    def swatch(fill: str, stroke: str, label: str) -> str:
+        return (
+            f'<span style="display:inline-block;width:12px;height:12px;'
+            f"background:{fill};border:1px solid {stroke};border-radius:2px;"
+            f'margin-right:6px;"></span>{label}'
+        )
+
+    def line_sample(
+        color: str,
+        width: int,
+        *,
+        dashed: bool = False,
+        label: str = "",
+        bolt: bool = False,
+    ) -> str:
+        dash = ' stroke-dasharray="5 4"' if dashed else ""
+        bolt_suffix = " ⚡" if bolt else ""
+        return (
+            f'<span style="display:inline-flex;align-items:center;gap:6px;">'
+            f'<svg width="42" height="10" viewBox="0 0 42 10" '
+            f'xmlns="http://www.w3.org/2000/svg" aria-hidden="true">'
+            f'<line x1="2" y1="5" x2="40" y2="5" stroke="{color}" '
+            f'stroke-width="{max(1, width)}"{dash} />'
+            f"</svg>{label}{bolt_suffix}</span>"
+        )
+
+    rows = [
+        swatch(theme.node_gateway[0], theme.node_gateway[1], "Gateway"),
+        swatch(theme.node_switch[0], theme.node_switch[1], "Switch"),
+        swatch(theme.node_ap[0], theme.node_ap[1], "AP"),
+        swatch(theme.node_client[0], theme.node_client[1], "Client"),
+        swatch(theme.node_other[0], theme.node_other[1], "Other"),
+        line_sample(theme.poe_link, theme.poe_link_width, label="PoE", bolt=True),
+        line_sample(theme.standard_link, theme.standard_link_width, label="Link"),
+        line_sample(theme.standard_link, theme.standard_link_width, dashed=True, label="Wireless"),
+    ]
+    lines = [
+        '<table class="unifi-legend-table">',
+        "<tbody>",
+    ]
+    lines.extend(f"  <tr><td>{style}</td></tr>" for style in rows)
+    lines.append("</tbody>")
+    lines.append("</table>")
+    return "\n".join(lines) + "\n"

unifi_network_maps/render/svg.py

@@ -194,8 +194,16 @@ def _iso_front_text_position(
     normal_x /= normal_len
     normal_y /= normal_len
     inset = tile_height * 0.27
-    text_x = edge_mid_x + normal_x * inset - tile_width * 0.16
-    text_y = edge_mid_y + normal_y * inset + tile_height * 0.02
+    text_x = edge_mid_x + normal_x * inset + tile_width * 0.02
+    text_y = edge_mid_y + normal_y * inset + tile_height * 0.33
+    edge_dx = left_edge_bottom[0] - left_edge_top[0]
+    edge_dy = left_edge_bottom[1] - left_edge_top[1]
+    edge_len = math.hypot(edge_dx, edge_dy) or 1.0
+    edge_dx /= edge_len
+    edge_dy /= edge_len
+    slide = tile_height * 0.32
+    text_x += edge_dx * slide
+    text_y += edge_dy * slide
     name_edge_left = top_points[3]
     name_edge_right = top_points[2]
     angle = math.degrees(
@@ -293,7 +301,7 @@ def _label_metrics(
 
 
 def _load_icons() -> dict[str, str]:
-    base = Path(__file__).resolve().parent / "assets" / "icons"
+    base = Path(__file__).resolve().parents[1] / "assets" / "icons"
     icons: dict[str, str] = {}
     for node_type, filename in _ICON_FILES.items():
         path = base / filename
@@ -306,7 +314,7 @@ def _load_icons() -> dict[str, str]:
 
 
 def _load_isometric_icons() -> dict[str, str]:
-    base = Path(__file__).resolve().parent / "assets" / "icons" / "isometric"
+    base = Path(__file__).resolve().parents[1] / "assets" / "icons" / "isometric"
     icons: dict[str, str] = {}
     for node_type, filename in _ISO_ICON_FILES.items():
         path = base / filename
@@ -450,7 +458,10 @@ def render_svg(
         color = "url(#link-poe)" if edge.poe else "url(#link-standard)"
         width_px = 2 if edge.poe else 1
         path = f"M {src_cx} {src_bottom} L {src_cx} {mid_y} L {dst_cx} {mid_y} L {dst_cx} {dst_top}"
-        lines.append(f'<path d="{path}" stroke="{color}" stroke-width="{width_px}" fill="none"/>')
+        dash = ' stroke-dasharray="6 4"' if edge.wireless else ""
+        lines.append(
+            f'<path d="{path}" stroke="{color}" stroke-width="{width_px}" fill="none"{dash}/>'
+        )
         if edge.poe:
             icon_x = dst_cx
             icon_y = dst_top - 6
@@ -677,9 +688,10 @@ def render_svg_isometric(
                 f"L {dst_cx} {dst_cy}",
             ]
         path = " ".join(path_cmds)
+        dash = ' stroke-dasharray="8 6"' if edge.wireless else ""
         lines.append(
             f'<path d="{path}" stroke="{color}" stroke-width="{width_px}" '
-            f'fill="none" stroke-linecap="round" stroke-linejoin="round"/>'
+            f'fill="none" stroke-linecap="round" stroke-linejoin="round"{dash}/>'
         )
         if edge.poe:
             icon_x = dst_cx

{unifi_network_maps-1.3.0.dist-info → unifi_network_maps-1.4.0.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.3.0
+Version: 1.4.0
 Summary: Dynamic UniFi -> network maps in mermaid or svg
 Author: Merlijn
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/merlijntishauser/unifi-network-maps
 Project-URL: Repository, https://github.com/merlijntishauser/unifi-network-maps
 Project-URL: Issues, https://github.com/merlijntishauser/unifi-network-maps/issues
@@ -11,27 +11,24 @@ Project-URL: Changelog, https://github.com/merlijntishauser/unifi-network-maps/b
 Keywords: unifi,mermaid,network,topology,diagram,svg
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: System Administrators
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Documentation
 Classifier: Topic :: System :: Networking
-Requires-Python: >=3.10
+Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-License-File: LICENSES.md
-Requires-Dist: unifi-controller-api
-Requires-Dist: python-dotenv
-Requires-Dist: PyYAML
+Requires-Dist: unifi-controller-api==0.3.2
+Requires-Dist: python-dotenv==1.2.1
+Requires-Dist: PyYAML==6.0.3
 Provides-Extra: dev
-Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
+Requires-Dist: Faker==40.1.0; extra == "dev"
+Requires-Dist: pre-commit==4.5.1; extra == "dev"
+Requires-Dist: pytest==9.0.2; extra == "dev"
+Requires-Dist: pytest-cov==7.0.0; extra == "dev"
+Requires-Dist: ruff==0.14.10; extra == "dev"
 Dynamic: license-file
 
 # unifi-network-maps
@@ -40,13 +37,14 @@ Dynamic UniFi -> Mermaid network maps generated from LLDP topology.
 
 ## Setup
 
-- Python >= 3.10
+- Python >= 3.13
 - Virtualenv required
 
 ```bash
 python -m venv .venv
 source .venv/bin/activate
-pip install -e .
+pip install -r requirements-build.txt
+pip install -e . -c constraints.txt
 ```
 
 Local install (non-editable):
@@ -103,12 +101,24 @@ Isometric SVG output:
 
 ```bash
 unifi-network-maps --format svg-iso --output ./network.svg
+
+# Single-page MkDocs output (ports included, no clients)
+unifi-network-maps --format mkdocs --output ./docs/unifi-network.md
+
+# MkDocs output (map + legend + gateway/switch port tables)
+unifi-network-maps --format mkdocs --output ./docs/unifi-network.md
+
+# Include wired clients in the port tables
+unifi-network-maps --format mkdocs --include-clients --output ./docs/unifi-network.md
 ```
 
 SVG size overrides:
 
 ```bash
 unifi-network-maps --format svg --svg-width 1400 --svg-height 900 --output ./network.svg
+
+# LLDP tables for troubleshooting
+unifi-network-maps --format lldp-md --output ./lldp.md
 ```
 
 Legend only:
@@ -117,12 +127,61 @@ Legend only:
 unifi-network-maps --legend-only --stdout
 ```
 
+## Examples (mock data)
+
+These examples are generated from `examples/mock_data.json` (safe, anonymized fixture).
+Mock generation requires dev dependencies (`pip install -r requirements-dev.txt -c constraints.txt`).
+Regenerate the fixture + SVG with `make mock-data`.
+
+Generate mock data (dev-only, uses Faker):
+
+```bash
+unifi-network-maps --generate-mock examples/mock_data.json --mock-seed 1337
+```
+
+Generate the isometric SVG:
+
+```bash
+unifi-network-maps --mock-data examples/mock_data.json \
+  --include-ports --include-clients --format svg-iso \
+  --output examples/output/network_ports_clients_iso.svg
+```
+
+![Isometric network example](examples/output/network_ports_clients_iso.svg)
+
+Mermaid example with ports:
+
+```mermaid
+graph TB
+  core_switch["Core Switch"] ---|"Core Switch: Port 7 (AP Attic) <-> AP Attic: Port 1 (Core Switch)"| ap_attic["AP Attic"];
+  core_switch["Core Switch"] ---|"Core Switch: Port 3 (AP Living Room) <-> AP Living Room: Port 1 (Core Switch)"| ap_living_room["AP Living Room"];
+  cloud_gateway["Cloud Gateway"] ---|"Cloud Gateway: Port 9 (Core Switch) <-> Core Switch: Port 1 (Cloud Gateway)"| core_switch["Core Switch"];
+  class cloud_gateway node_gateway;
+  class core_switch node_switch;
+  class ap_living_room node_ap;
+  class ap_attic node_ap;
+  classDef node_gateway fill:#ffe3b3,stroke:#d98300,stroke-width:1px;
+  classDef node_switch fill:#d6ecff,stroke:#3a7bd5,stroke-width:1px;
+  classDef node_ap fill:#d7f5e7,stroke:#27ae60,stroke-width:1px;
+  classDef node_client fill:#f2e5ff,stroke:#7f3fbf,stroke-width:1px;
+  classDef node_other fill:#eeeeee,stroke:#8f8f8f,stroke-width:1px;
+  classDef node_legend font-size:10px;
+  linkStyle 0 stroke:#1e88e5,stroke-width:2px,arrowhead:none;
+  linkStyle 1 stroke:#1e88e5,stroke-width:2px,arrowhead:none;
+```
+
 ## Local install check
 
 ```bash
 pip install .
 ```
 
+## Dev
+
+```bash
+pip install -r requirements-dev.txt -c constraints.txt
+```
+
 ## Release
 
 Build and upload to PyPI:
@@ -142,6 +201,20 @@ git push origin vX.Y.Z
 
 See `LICENSES.md` for third-party license info.
 
+## Installation
+
+PyPI: https://pypi.org/project/unifi-network-maps/
+
+```bash
+pip install unifi-network-maps
+```
+
+Then run:
+
+```bash
+unifi-network-maps --help
+```
+
 ## Options
 
 The CLI groups options by category (`Source`, `Functional`, `Mermaid`, `SVG`, `Output`, `Debug`).
@@ -149,15 +222,26 @@ The CLI groups options by category (`Source`, `Functional`, `Mermaid`, `SVG`, `O
 Source:
 - `--site`: override `UNIFI_SITE`.
 - `--env-file`: load environment variables from a specific `.env` file.
+- `--mock-data`: use mock data JSON instead of the UniFi API.
+Mock:
+- `--generate-mock`: write mock data JSON and exit.
+- `--mock-seed`: seed for deterministic mock generation.
+- `--mock-switches`: number of switches to generate.
+- `--mock-aps`: number of access points to generate.
+- `--mock-wired-clients`: number of wired clients to generate.
+- `--mock-wireless-clients`: number of wireless clients to generate.
 
 Functional:
 - `--include-ports`: show port labels (Mermaid shows both ends; SVG shows compact labels).
 - `--include-clients`: add active wired clients as leaf nodes.
+- `--client-scope wired|wireless|all`: which client types to include (default wired).
 - `--only-unifi`: only include neighbors that are UniFi devices.
 
 Mermaid:
 - `--direction LR|TB`: diagram direction for Mermaid (default TB).
 - `--group-by-type`: group nodes by gateway/switch/AP in Mermaid subgraphs.
+- `--legend-scale`: scale legend font/link sizes for Mermaid outputs (default 1.0).
+- `--legend-style auto|compact|diagram`: legend rendering mode (auto uses compact for mkdocs).
 - `--legend-only`: render just the legend as a separate Mermaid graph (Mermaid only).
 
 SVG:
@@ -165,9 +249,10 @@ SVG:
 - `--theme-file`: load a YAML theme for Mermaid + SVG colors (see `examples/theme.yaml` and `examples/theme-dark.yaml`).
 
 Output:
-- `--format mermaid|svg|svg-iso`: output format (default mermaid).
+- `--format mermaid|svg|svg-iso|lldp-md|mkdocs`: output format (default mermaid).
 - `--stdout`: write output to stdout.
 - `--markdown`: wrap Mermaid output in a code fence.
+- `--mkdocs-sidebar-legend`: write assets to place the compact legend in the MkDocs right sidebar.
 
 Debug:
 - `--debug-dump`: dump gateway + sample devices to stderr for debugging.
@@ -178,6 +263,7 @@ Debug:
 - Default output is top-to-bottom (TB) and rendered as a hop-based tree from the gateway(s).
 - Nodes are color-coded by type (gateway/switch/AP/client) with a sensible default palette.
 - PoE links are highlighted in blue and annotated with a power icon when detected from `port_table`.
+- Wireless client links render as dashed lines to indicate the last-known upstream.
 - SVG output uses vendored device glyphs from `src/unifi_network_maps/assets/icons`.
 - Isometric SVG output uses MIT-licensed icons from `markmanx/isopacks`.
 - SVG port labels render inside child nodes for readability.
@@ -211,5 +297,10 @@ svg:
       to: "#b6dcff"
 ```
 
+## MkDocs Material example
+
+See `examples/mkdocs/` for a ready-to-use setup that renders Mermaid diagrams
+with Material for MkDocs, including a sample `unifi-network` page and legend.
+
 The built-in themes live at `src/unifi_network_maps/assets/themes/default.yaml` and
 `src/unifi_network_maps/assets/themes/dark.yaml`.