All Projects → LukeCarrier → mkdocs-drawio-exporter

LukeCarrier / mkdocs-drawio-exporter

Licence: MIT license
Exports your Draw.io diagrams at build time for easier embedding into your documentation

Programming Languages

python
139335 projects - #7 most used programming language

Projects that are alternatives of or similar to mkdocs-drawio-exporter

c4-diagrams.net
The EasyC4 library is for quick and convenient visualising software architecture in diagrams.net / draw.io application using the C4 model approach.
Stars: ✭ 28 (-44%)
Mutual labels:  drawio, diagramsnet
dotfiles
My dotfiles
Stars: ✭ 22 (-56%)
Mutual labels:  mkdocs
docs
📖 TomoChain documentation
Stars: ✭ 19 (-62%)
Mutual labels:  mkdocs
lavalink-list
A list of free and available public lavalink. Feel free to make a pull request!
Stars: ✭ 43 (-14%)
Mutual labels:  mkdocs
mkdocs-section-index
MkDocs plugin to allow clickable sections that lead to an index page
Stars: ✭ 36 (-28%)
Mutual labels:  mkdocs
Wechat Admin
Wechat Management System
Stars: ✭ 1,716 (+3332%)
Mutual labels:  mkdocs
mkdocs-click
An MkDocs extension to generate documentation for Click command line applications
Stars: ✭ 34 (-32%)
Mutual labels:  mkdocs
docs
Source for documentation site
Stars: ✭ 73 (+46%)
Mutual labels:  mkdocs
Awesome-Retro-Docs
A curated collection of technical documentation for Arcades, Handhelds, Consoles, Computers and MCU’s.
Stars: ✭ 128 (+156%)
Mutual labels:  diagrams
mr-pdf
PDF generator of document website
Stars: ✭ 58 (+16%)
Mutual labels:  mkdocs
mkdocs-markdownextradata-plugin
A MkDocs plugin that injects the mkdocs.yml extra variables into the markdown template
Stars: ✭ 48 (-4%)
Mutual labels:  mkdocs
fosscord-docs
Docs for Fosscord
Stars: ✭ 23 (-54%)
Mutual labels:  mkdocs
Actions Gh Pages
GitHub Actions for GitHub Pages 🚀 Deploy static files and publish your site easily. Static-Site-Generators-friendly.
Stars: ✭ 2,576 (+5052%)
Mutual labels:  mkdocs
mkdocs-print-site-plugin
MkDocs Plugin that adds an additional page that combines all pages, allowing easy exports to PDF and standalone HTML.
Stars: ✭ 38 (-24%)
Mutual labels:  mkdocs
makeitpdf
A close-to-code documentation helper
Stars: ✭ 15 (-70%)
Mutual labels:  diagrams
mkdocs-rtl
mkdocs rtl theme based on mkdocs-material
Stars: ✭ 22 (-56%)
Mutual labels:  mkdocs
mkdocs-literate-nav
MkDocs plugin to specify the navigation in Markdown instead of YAML
Stars: ✭ 19 (-62%)
Mutual labels:  mkdocs
Readthedocs.org
The source code that powers readthedocs.org
Stars: ✭ 6,802 (+13504%)
Mutual labels:  mkdocs
docker-diagrams
An image for https://github.com/mingrammer/diagrams
Stars: ✭ 19 (-62%)
Mutual labels:  diagrams
mkdocs-rss-plugin
MkDocs plugin to generate a RSS feeds for created and updated pages, using git log and YAML frontmatter (page.meta).
Stars: ✭ 43 (-14%)
Mutual labels:  mkdocs

Diagrams.net (Draw.io) Exporter for MkDocs

Exports your Draw.io diagrams at build time for easier embedding into your documentation.


Quick start

First install the package:

$ pip install mkdocs-drawio-exporter

Then enable it:

plugins:
    - drawio-exporter

Configuration

For the default configuration, just add the plugin to the plugins key:

plugins:
    - drawio-exporter

You can override the default configuration:

plugins:
    - drawio-exporter:
        # Diagrams are cached to speed up site generation. The default path is
        # drawio-exporter, relative to the documentation directory.
        cache_dir: 'drawio-exporter'
        # Path to the Draw.io executable:
        #   * drawio on Linux
        #   * draw.io on macOS
        #   * or draw.io.exe on Windows
        # We'll look for it on your system's PATH, then default installation
        # paths. If we can't find it we'll warn you.
        drawio_executable: null
        # Additional Draw.io CLI args
        drawio_args: []
        # Output format (see draw.io --help | grep format)
        format: svg
        # Embed format
        #   * The default is to embed via the <img> tag, only rewriting the
        #     value of the src attribute.
        #   * Consider <object type="image/svg+xml" data="{img_src}"></object>
        #     to enable interactive elements (like hyperlinks) in SVGs.
        embed_format: '{img_open}{img_src}{img_close}'
        # Glob pattern for matching source files
        sources: '*.drawio'

Usage

With the plugin configured, you can now proceed to embed images by simply embedding the *.drawio diagram file as you would with any image file:

![My alt text](my-diagram.drawio)

If you're working with multi-page documents, append the index of the page as an anchor in the URL:

![Page 1](my-diagram.drawio#0)

The plugin will export the diagram to the format specified in your configuration and will rewrite the <img> tag in the generated page to match. To speed up your documentation rebuilds, the generated output will be placed into cache_dir and then copied to the desired destination. The cached images will only be updated if the source diagram's modification date is newer than the cached export. Thus, bear in mind caching works per file - with large multi-page documents a change to one page will rebuild all pages, which will be slower than separate files per page.

GitHub Actions

See this guide.

Headless usage

In addition to the above, if you're running in a headless environment (e.g. in integration, or inside a Docker container), you may need to ensure a display server is running and that the necessary dependencies are installed.

On Debian and Ubuntu, the following should install the dependencies:

sudo apt install libasound2 xvfb

To run MkDocs with an automatically assigned X display, wrap the command as follows:

xvfb-run -a mkdocs build

Running without the sandbox

If you're seeing messages like the following it's likely that you're running MkDocs as root:

[22:0418/231827.169035:FATAL:electron_main_delegate.cc(211)] Running as root without --no-sandbox is not supported. See https://crbug.com/638180.

If possible, consider running MkDocs as a non-privileged user. Depending on the circumstances (e.g. running within an unprivileged container) it may be appropriate to disable the Chrome sandbox by adding the following option to mkdocs.yml:

plugins:
    - drawio-exporter:
        drawio_args:
            - --no-sandbox

Hacking

To get completion working in your editor, set up a virtual environment in the root of this repository and install MkDocs:

$ pip3 install --user --upgrade setuptools twine wheel
$ python3 -m venv venv
$ . venv/bin/activate
$ pip install -r requirements.txt

To install the plugin onto a local MkDocs site in editable form:

$ pip install --editable /path/to/mkdocs-drawio-exporter

Note that you'll need to repeat this step if you make any changes to the entry_points listed in setup.py.

Run the tests with the Python unittest module:

$ python -m unittest mkdocsdrawioexporter.tests

Upgrading dependencies

To upgrade the dependencies, install pip-upgrader:

. venv/bin/activate
pip install -r requirements.dev.txt

Then proceed to update the dependencies:

pip-upgrade requirements.dev.txt

Releasing

Build the distributable package:

$ python3 setup.py sdist bdist_wheel

Push it to the PyPI test instance:

$ python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Test it inside a virtual environment:

$ pip install --index-url https://test.pypi.org/simple/ --no-deps mkdocs-drawio-exporter

Let's go live:

$ python3 -m twine upload dist/*
Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].