Skip to main content

mkdocs-topoviewer

Support status: Supported

mkdocs-topoviewer is the MkDocs plugin wrapper for TopoViewer. It lets MkDocs users install TopoViewer with pip and embed declarative topology diagrams with a fenced Markdown block.

This package is licensed under Apache-2.0, like TopoViewer. It is publish-shaped for intentional public Python package releases, while private/customer-specific material should stay in separate packages or private indexes.

Repository Boundary

This package is intentionally separate from the npm renderer package, but both packages are intended to live in one monorepo:

topoviewer/
  package.json            # npm workspace orchestrator
  packages/
    topoviewer/           # npm package: topoviewer
    mkdocs-topoviewer/    # Python package: mkdocs-topoviewer

The renderer package owns the React component, compiler, schemas, and browser bundle. This package owns only the MkDocs integration: fenced-block parsing, page-relative reference resolution, asset injection, and packaging the approved browser bundle for Python users.

The dependency direction is one way: build TopoViewer first, then vendor its browser-ready embed assets into this package. MkDocs users should not need npm, Vite, React, or TypeScript in their documentation build pipeline.

Install

Requires Python 3.9+ and MkDocs 1.6 or later, below 2.0. The plugin uses MkDocs 1.6's generated-file API to ship its browser assets.

Install from PyPI:

pip install mkdocs-topoviewer

For local plugin development inside the TopoViewer repository:

pip install -e packages/mkdocs-topoviewer

Private distribution should use an approved package index:

pip install --index-url https://<private-index>/simple mkdocs-topoviewer

Configure

plugins:
  - search
  - topoviewer

Optional plugin config:

plugins:
  - topoviewer:
      asset_path: assets/topoviewer

Use

```topoviewer
topology: ./topoviewer-topo.yaml
stylesheet: ./topoviewer-style.yaml
height: 640px
title: MV network SR-TE service path
controls: true
controlsOpen: false
```

The plugin resolves topology and stylesheet relative to the Markdown page.

What The Plugin Ships

The Python package vendors the browser-ready TopoViewer bundle:

  • topoviewer-embed.iife.js
  • topoviewer-embed.css
  • topoviewer-mkdocs.css

MkDocs receives those files as generated site assets. Projects using the plugin do not need to run npm or copy assets manually.

Development

When the TopoViewer browser bundle changes, refresh the vendored assets from the npm package:

cd ../topoviewer
npm run build
npm run sync:mkdocs

When changing only this Python plugin, work from this package root:

python -m pip install -e .
python -m build

The plugin package should remain independently buildable and publishable. Do not import source files from ../topoviewer; use only the vendored browser assets under mkdocs_topoviewer/assets/.

From the repository root, validate the candidate wheel with real site builds:

npm run dist:mkdocs
npm run inspect:mkdocs
npm run install:check:mkdocs:wheel

This installs the local wheel into clean environments with MkDocs 1.6.0 and the latest release below 2.0, then verifies embeds, relative references, and generated assets. CI repeats those builds on Python 3.9 and 3.14. The separate install:check:mkdocs command checks the already published PyPI package.

Release Model

  • mkdocs-topoviewer is the MkDocs wrapper for the stable TopoViewer browser bundle.
  • Public plugin releases should contain stable behavior, docs, schemas, and vendored assets.
  • Internal preview builds should use approved private package indexes.
  • Customer-specific templates, private assets, or proprietary importers belong in separate private packages, not in this generic plugin.

Metadata

Release files for mkdocs-topoviewer 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mkdocs-topoviewer 0.6.0
File Size Uploaded Provenance Actions
mkdocs_topoviewer-0.6.0.tar.gz 246.8 kB With provenance Details for mkdocs_topoviewer-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mkdocs-topoviewer 0.6.0
File Interpreter ABI Platform Actions
mkdocs_topoviewer-0.6.0-py3-none-any.whl Python 3 none any Details for mkdocs_topoviewer-0.6.0-py3-none-any.whl

Total release size: 495.4 kB

Release files / mkdocs_topoviewer-0.6.0.tar.gz

Download URL mkdocs_topoviewer-0.6.0.tar.gz
Size 246.8 kB
Tags Source
SHA-256 checksum
How to use checksums
e1ee16d03ec9841d6a2fd733bc979197ab27dbac826ab1fa784150865a2f7537
BLAKE2b-256 checksum
How to use checksums
8bea42e31a8a07ed2afbf10a82ff45d0ee1ab55985bca367adb1e7d6cf32be60
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.

Transparency log

Release files / mkdocs_topoviewer-0.6.0-py3-none-any.whl

Download URL mkdocs_topoviewer-0.6.0-py3-none-any.whl
Size 248.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5f0ed6bb9c0b810940ced6576f379d35e83a6431d84aa188453c77d978584e68
BLAKE2b-256 checksum
How to use checksums
9697994cf304754190de78163e0e9ef4032b70d29fb97619a63d35c58f636896
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.

Transparency log

Security for mkdocs-topoviewer 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mkdocs_topoviewer-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page