NetBox Documentation

A wiki for operational documentation and how-tos, integrated into NetBox.

Plugin name	netbox_documentation
Package	netbox-documentation
NetBox	>=4.0
Python	>=3.10
Repository	https://git.mrblake.cc/MrBlake/Netbox-Documentation

Features

• Write documentation directly in NetBox, displayed as safely sanitised rich text
• Word-like WYSIWYG editor with fonts, font sizes, colours, alignment and tables
• Hierarchical folders and sub-folders for a BookStack-like structure
• Wide editor view and TinyMCE full-screen mode
• Optionally assign documents and folders to tenants and tenant groups
• Upload images from your own device directly into a document
• Paste formatted Word content including tables and supported clipboard images
• Export and re-import multiple documents with folders, assignments and attachments as ZIP
• Print-optimised A4 view for printing or saving as PDF
• Full-page view via button or by clicking a table
• Readable tables with full cell borders and horizontal content scrolling
• Table presets, coloured header rows and cell highlighting in the editor
• Excel multi-sheet import: one document per worksheet in a chosen target folder
• Two-step Excel preview with sheet selection and editable document titles
• Optional flattening of Excel tables into compact field/value text blocks
• Assign one document to many objects and vice versa (unlimited; only identical duplicates are prevented)
• Supported objects: region, site, location, rack, device, VM, VM cluster and tenant/customer
• Import DOCX, XLSX/XLSM, text-based PDF, Markdown and text files
• Optionally keep the original file together with the document
• Find documents via NetBox global search and the REST API
• NetBox permissions, changelog, tags and custom fields

Compatibility

• NetBox >=4.0
• Python >=3.10

Test the plugin against your exact NetBox minor version in a staging instance before a production rollout.

Installation

All paths assume a standard installation under /opt/netbox.

1. Install the package

/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
  "git+https://git.mrblake.cc/MrBlake/Netbox-Documentation.git@main"

For reproducible production installs, replace main with a release tag or a full commit ID.

2. Add the plugin to local_requirements.txt

This makes upgrade.sh reinstall the plugin automatically on every NetBox upgrade:

grep -qxF "git+https://git.mrblake.cc/MrBlake/Netbox-Documentation.git@main" /opt/netbox/local_requirements.txt \
  || echo "git+https://git.mrblake.cc/MrBlake/Netbox-Documentation.git@main" | sudo tee -a /opt/netbox/local_requirements.txt

If the repository is private, the NetBox server needs a read-only deploy token or an SSH key. Do not store credentials in local_requirements.txt.

3. Enable the plugin

In /opt/netbox/netbox/netbox/configuration.py:

PLUGINS = [
    "netbox_documentation",
]

PLUGINS_CONFIG = {
    "netbox_documentation": {
        "max_import_size_mb": 25,
        "max_archive_size_mb": 250,
        "keep_imported_file": True,
        "allowed_object_types": [
            "dcim.region",
            "dcim.site",
            "dcim.location",
            "dcim.rack",
            "dcim.device",
            "virtualization.virtualmachine",
            "virtualization.cluster",
            "tenancy.tenant",
        ],
    },
}

If other plugins are already configured, add netbox_documentation to the existing list and dictionary instead of replacing them.

4. Apply migrations, collect static files, restart

cd /opt/netbox/netbox
/opt/netbox/venv/bin/python manage.py migrate netbox_documentation
/opt/netbox/venv/bin/python manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq

TinyMCE is installed as a Python dependency and served via a local, cached plugin endpoint; collectstatic also copies the files into NetBox. The editor therefore needs neither CDN access nor an API key (TinyMCE runs in GPL mode). If the script cannot be loaded, a plain HTML text field is used as a fallback.

For Docker installations, add the package to your NetBox image, set plugin and configuration, and rebuild the image. Uploaded files live in NetBox's MEDIA_ROOT, which must be persistent and backed up.

Update

/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
  "git+https://git.mrblake.cc/MrBlake/Netbox-Documentation.git@main"

cd /opt/netbox/netbox
/opt/netbox/venv/bin/python manage.py migrate netbox_documentation
/opt/netbox/venv/bin/python manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq

--force-reinstall makes pip pick up branch changes even if the package version has not been bumped.

When NetBox itself is upgraded, upgrade.sh reinstalls the plugin from local_requirements.txt and runs migrations and collectstatic:

sudo /opt/netbox/upgrade.sh
sudo systemctl restart netbox netbox-rq

Check the installed version and migrations:

/opt/netbox/venv/bin/pip show netbox-documentation
cd /opt/netbox/netbox
/opt/netbox/venv/bin/python manage.py showmigrations netbox_documentation

Migrating from the old repository name: earlier versions were installed from Netbox-DokiWiki.git. Replace that line in /opt/netbox/local_requirements.txt with the URL above.

Uninstall

1. Remove "netbox_documentation" from PLUGINS and PLUGINS_CONFIG.
2. Remove the line from /opt/netbox/local_requirements.txt.
3. Uninstall the package and restart NetBox:

/opt/netbox/venv/bin/pip uninstall netbox-documentation
sudo systemctl restart netbox netbox-rq

Configuration

Key	Default	Description
max_import_size_mb	25	Maximum size of a single imported file
max_archive_size_mb	250	Maximum size of a ZIP archive import
keep_imported_file	True	Keep the original file as an attachment
allowed_object_types	see above	Object types documents can be assigned to

Usage

Permissions

Grant permissions under Admin → Users → Permissions:

• netbox_documentation.view_document
• netbox_documentation.add_document, change_document, delete_document
• netbox_documentation.view_documentassignment and the corresponding change permissions
• netbox_documentation.import_document for Office/PDF imports

Set object-level constraints matching your tenants and areas of responsibility. Unpublished documents are an editorial status, not a replacement for object permissions.

Import behaviour

Format	Imported content
DOCX	Headings, paragraphs, lists, links and simple tables
XLSX/XLSM	Each worksheet as its own table; formula results only if Excel saved them
PDF	Extractable text, split by page
MD/TXT	Taken over directly (UTF-8)

Legacy binary .doc and .xls files must be converted to .docx/.xlsx first. Scanned PDFs require OCR, which is not included yet. Complex Word/PDF layouts, embedded images and Excel formatting cannot be converted losslessly.

For large Excel files, enable "Excel with multiple worksheets — one document per sheet" on the import page (a target folder is required). Every non-empty worksheet becomes its own document titled after the sheet, with its own copy of the original Excel file attached. Embedded PNG, JPEG, GIF and WebP images are added as media attachments; charts, SmartArt, controls and externally linked images cannot be imported reliably.

A preview page lists all detected worksheets first. Sheets can be deselected, titles changed and the resulting documents expanded. Only the final confirmation writes documents and attachments to the database. Unconfirmed previews are bound to the user and cleaned up after 24 hours.

"Flatten Excel tables" takes over normal cells in reading order without artificial record or field labels: cells of one row become lines of a paragraph, rows are separated by paragraphs. Ranges explicitly formatted as a table in Excel (Insert → Table) stay tables. Non-flattened tables are shown compactly and scroll horizontally inside the content without widening the NetBox layout.

ZIP archive

Under Documentation → ZIP Export & Import, multiple folders can be added via a search field and downloaded together, optionally including all sub-folders. Documents found by overlapping folder selections are included only once. The archive contains:

• document content and metadata
• full folder paths
• assignments to NetBox objects
• imported files and editor images

On import, choose whether documents with the same identifier are updated or created as new copies. Assignments to missing or disallowed objects are skipped. Embedded image URLs are rewritten to the newly stored attachments.

Archives are checked for safe paths, file count, file types, compression ratio and total extracted size before import. The size limit is set with max_archive_size_mb.

REST API

• /api/plugins/documentation/documents/
• /api/plugins/documentation/assignments/
• /api/plugins/documentation/folders/
• /api/plugins/documentation/attachments/

Development and tests

pip install -e ".[test]"
pytest

Full UI/API tests require NetBox in the same virtualenv. The pure import tests are located in netbox_documentation/tests/.

Roadmap

• OCR for scanned PDFs (e.g. Tesseract/OCRmyPDF as an optional worker)
• Import embedded DOCX images as NetBox media
• Real document revisions with diff and approval workflow
• Asynchronous bulk import of large Excel datasets via NetBox RQ
• Templates and inherited documentation along region → site → device

License

Apache License 2.0.