{"id":15017487,"url":"https://github.com/lukecarrier/mkdocs-drawio-exporter","last_synced_at":"2025-04-13T02:21:00.133Z","repository":{"id":35109950,"uuid":"207670577","full_name":"LukeCarrier/mkdocs-drawio-exporter","owner":"LukeCarrier","description":"Exports your Draw.io diagrams at build time for easier embedding into your documentation","archived":false,"fork":false,"pushed_at":"2025-03-06T03:33:38.000Z","size":121,"stargazers_count":83,"open_issues_count":7,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-11T19:57:20.655Z","etag":null,"topics":["diagrams","diagramsnet","documentation","drawio","mkdocs"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/mkdocs-drawio-exporter/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LukeCarrier.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-10T21:59:11.000Z","updated_at":"2025-04-07T07:59:26.000Z","dependencies_parsed_at":"2024-01-11T23:17:57.635Z","dependency_job_id":"2580a825-faed-48bf-b075-6a34d4947724","html_url":"https://github.com/LukeCarrier/mkdocs-drawio-exporter","commit_stats":{"total_commits":94,"total_committers":6,"mean_commits":"15.666666666666666","dds":"0.44680851063829785","last_synced_commit":"3fa8822b9c85d4bd94c8c8a2ed111cacf83ee873"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeCarrier%2Fmkdocs-drawio-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeCarrier%2Fmkdocs-drawio-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeCarrier%2Fmkdocs-drawio-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukeCarrier%2Fmkdocs-drawio-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LukeCarrier","download_url":"https://codeload.github.com/LukeCarrier/mkdocs-drawio-exporter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654704,"owners_count":21140348,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diagrams","diagramsnet","documentation","drawio","mkdocs"],"created_at":"2024-09-24T19:50:33.218Z","updated_at":"2025-04-13T02:21:00.097Z","avatar_url":"https://github.com/LukeCarrier.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Diagrams.net (Draw.io) Exporter for MkDocs\n\nExports your Draw.io diagrams at build time for easier embedding into your documentation.\n\n---\n\n## Quick start\n\nFirst install the package:\n\n```shell\npip install mkdocs-drawio-exporter\n```\n\nThen enable it:\n\n```yaml\nplugins:\n  - drawio-exporter\n```\n\n## Configuration\n\nFor the default configuration, just add the plugin to the `plugins` key:\n\n```yaml\nplugins:\n  - drawio-exporter\n```\n\nYou can override the default configuration; values shown are defaults:\n\n```yaml\nplugins:\n  - drawio-exporter:\n      # Diagrams are cached to speed up site generation. The default path is\n      # drawio-exporter, relative to the documentation directory.\n      cache_dir: 'drawio-exporter'\n      # Path to the Draw.io executable:\n      #   * drawio on Linux\n      #   * draw.io on macOS\n      #   * or draw.io.exe on Windows\n      # We'll look for it on your system's PATH, then default installation\n      # paths. If we can't find it we'll warn you.\n      drawio_executable: null\n      # Additional Draw.io CLI args\n      #   * --embed-svg-images will embed external images in SVGS, if format is \"svg\".\n      drawio_args: []\n      # Output format (see draw.io --help | grep format)\n      format: svg\n      # Embed format\n      #   * The default is to embed via the \u003cimg\u003e tag.\n      #   * Consider \u003cobject type=\"image/svg+xml\" data=\"{img_src}\"\u003e\u003c/object\u003e\n      #     to enable interactive elements (like hyperlinks) in SVGs.\n      #   * Consider {content} to inline SVGs into documents directly, useful\n      #     for styling with CSS, preserving interactivity, and improving\n      #     search by indexing diagram text.\n      embed_format: '\u003cimg alt=\"{img_alt}\" src=\"{img_src}\"\u003e'\n      # Glob pattern for matching source files\n      sources: '*.drawio'\n```\n\n## Usage\n\nWith the plugin configured, you can now proceed to embed images by simply embedding the `*.drawio` diagram file as you would with any image file:\n\n```markdown\n![My alt text](my-diagram.drawio)\n```\n\nIf you're working with multi-page documents, append the index of the page as an anchor in the URL:\n\n```markdown\n![Page 1](my-diagram.drawio#0)\n```\n\nThe plugin will export the diagram to the `format` specified in your configuration and will rewrite the `\u003cimg\u003e` 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.\n\n### GitHub Actions\n\nSee [this guide](./docs/github-actions.md).\n\n### Headless usage\n\nIn 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.\n\nOn Debian and Ubuntu, the following should install the dependencies:\n\n```shell\nsudo apt install libasound2 xvfb\n```\n\nTo run MkDocs with an automatically assigned X display, wrap the command as follows:\n\n```shell\nxvfb-run -a mkdocs build\n```\n\n### Running without the sandbox\n\nIf you're seeing messages like the following it's likely that you're running MkDocs as root:\n\n```text\n[22:0418/231827.169035:FATAL:electron_main_delegate.cc(211)] Running as root without --no-sandbox is not supported. See https://crbug.com/638180.\n```\n\nIf 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`:\n\n```yaml\nplugins:\n  - drawio-exporter:\n      drawio_args:\n        - --no-sandbox\n```\n\n## Hacking\n\nOptionally, use [Nix](https://nix.dev/) for a development shell with all the necessary dependencies:\n\n```shell\nnix develop\n```\n\nWe use [Poetry](https://python-poetry.org/) for dependency management:\n\n```shell\npoetry install\n```\n\nTo get completion working in your editor, set up a virtual environment in the root of this repository and install MkDocs:\n\n```shell\npoetry install --with dev\n```\n\nTo install the plugin onto a local MkDocs site in editable form:\n\n```shell\npoetry add --editable /path/to/mkdocs-drawio-exporter\n```\n\nNote that you'll need to repeat this step if you make any changes to the `[tool.poetry.plugins.*]` sections listed in `pyproject.toml`.\n\nRun the tests with the `test` script:\n\n```shell\npoetry run test\n```\n\n## Upgrading dependencies\n\nTo upgrade the dependencies, first make any necessary changes to the constraints expressed in the `[tool.poetry.dependencies]` section of `pyproject.toml`, then have Poetry update them:\n\n```shell\npoetry update\n```\n\n## Releasing\n\nBuild the distributable package:\n\n```shell\npoetry build\n```\n\nPush it to the PyPI test instance:\n\n```shell\ntwine upload --repository-url https://test.pypi.org/legacy/ dist/*\n```\n\nTest it inside a virtual environment:\n\n```shell\npip install --index-url https://test.pypi.org/simple/ --no-deps mkdocs-drawio-exporter\n```\n\nLet's go live:\n\n```shell\ntwine upload dist/*\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukecarrier%2Fmkdocs-drawio-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukecarrier%2Fmkdocs-drawio-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukecarrier%2Fmkdocs-drawio-exporter/lists"}