{"schemaVersion":1,"title":"draw.io diagrams","url":"https://appgram.github.io/docsy/versions/current/es/guides/tutorials/drawio-diagrams","markdownUrl":"https://appgram.github.io/docsy/format-md/versions/current/es/guides/tutorials/drawio-diagrams","jsonUrl":"https://appgram.github.io/docsy/agent/pages/versions/current/es/guides/tutorials/drawio-diagrams.json","version":"current","locale":"es","markdown":"# draw.io diagrams\n\nEmbed SVG and PNG architecture diagrams, expand them to inspect details, and offer editable source downloads.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nUse draw.io SVG or PNG exports in Markdown and MDX articles, with a caption and an optional download of the original `.drawio` file. Diagrams use Docsy’s fullscreen viewer: click to expand, scroll or pinch to zoom, drag to pan, and press Escape to close.\n\n## Example: documentation pipeline\n\nDiagram: Editable Markdown, YAML, OpenAPI and SDK inputs flow through Docsy validation and rendering to self-hosted documentation for humans and coding agents.&#xA;&#xA;Your source, validated output, your infrastructure. Expand to inspect the diagram or download its editable source.&#xA;&#xA;Editable draw.io source is available from the article’s diagram card.\n\nThis source-owned example includes an editable `.drawio` document and a matching SVG preview. Static hosting serves public documentation; permission gates and live agent queries require Node or Bun.\n\n## Export from draw.io\n\n1. Save your editable diagram as a `.drawio` file.\n2. Choose **File → Export as → SVG** for a sharp vector diagram, or **PNG** for a raster preview. Embed any images and fonts in the export: remote resources are rejected so readers do not contact a third-party host.\n3. Store both files under `content/diagrams/`, not `public/` when the article is protected.\n4. Register the preview and optional source in YAML.\n\n```yaml\ncontent:\n  diagrams:\n    architecture:\n      image: content/diagrams/architecture.drawio.svg\n      source: content/diagrams/architecture.drawio\n      alt: Clients reach the API through an authentication gateway.\n      caption: Requests are authorized before they reach internal services.\n      background: light\n      sourceLabel: Download source\n```\n\nUse `.drawio.png` or `.png` in `image` for a PNG export. `alt` is required. Omit `source` to hide the download link; `sourceLabel` changes its text. `background` can be `light` (default), `dark`, or `transparent`. It applies to both the inline preview and expanded image, so a transparent export with dark labels remains readable in a dark portal.\n\nEach file must be local, inside the project, and at most 5 MiB. Previews must be well-formed SVG or PNG with bounded dimensions. SVG scripts, handlers, external images/styles/fonts and XML entities are rejected. Embedded fonts remain inside their SVG image; they do not change the portal’s font stack.\n\n## Use in Markdown\n\nUse the YAML registration key rather than a filesystem path:\n\n```md\n## Technical architecture\n\n::drawio{src=\"architecture\"}\n```\n\n## Use in MDX\n\nThe built-in component works in declarative MDX without imports or executable JavaScript:\n\n```mdx\n## Technical architecture\n\n<Drawio src=\"architecture\" />\n```\n\nIf you explicitly configure `content.components`, add `drawio` to that list. It is included in the defaults. Fullscreen expansion follows `content.media.enabled` and `content.media.images`; disabling the viewer leaves the preview and source download available.\n\n## Access and agent exports\n\nDiagram bytes are embedded only in the rendered article, not copied into a public asset directory or a separate unprotected download route. A locked article’s existing permission checks therefore also protect its preview and source download. Do not put protected originals in `public/`, which is always publicly accessible.\n\nCaptions participate in full-text search. Markdown/JSON exports include the supplied description and caption, not large base64 images or native XML. Give agents a useful textual explanation alongside any important architecture diagram.\n\nThis integration displays exports and offers source downloads. It does **not** automatically render raw `.drawio` XML, open an online editor, or synchronize the preview after the editable source changes. Re-export the SVG/PNG when you update the diagram and review both files together.\n\n","contentLocale":"en","isFallback":true,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/tutorials/drawio-diagrams.md"}