{"schemaVersion":1,"title":"Mermaid and UML diagrams","url":"https://appgram.github.io/docsy/versions/current/fr/guides/tutorials/mermaid-and-uml","markdownUrl":"https://appgram.github.io/docsy/format-md/versions/current/fr/guides/tutorials/mermaid-and-uml","jsonUrl":"https://appgram.github.io/docsy/agent/pages/versions/current/fr/guides/tutorials/mermaid-and-uml.json","version":"current","locale":"fr","markdown":"# Mermaid and UML diagrams\n\nWrite Mermaid flowcharts and UML in Markdown or MDX, or embed protected PlantUML exports with editable source downloads.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nWrite Mermaid diagrams directly in Markdown or MDX code fences. Use Mermaid's class, sequence and state notation for UML, or embed an SVG/PNG exported by PlantUML with its editable `.puml` source. No diagram source is sent to a public renderer.\n\n## Mermaid flowcharts\n\nUse a `mermaid` fence. The optional text after the language becomes the caption and accessible image description. Describe the important relationship in surrounding prose so both readers and coding agents understand it.\n\n````markdown\n```mermaid Documentation pipeline\nflowchart LR\n  Sources[Markdown and YAML] --> Validate[Validate]\n  Validate --> Review[Review preview]\n  Review --> Publish[Self-hosted docs]\n```\n````\n\n```mermaid Documentation pipeline\nflowchart LR\n  Sources[Markdown and YAML] --> Validate[Validate]\n  Validate --> Review[Review preview]\n  Review --> Publish[Self-hosted docs]\n```\n\nThe renderer is bundled locally and loaded only on pages containing Mermaid diagrams. Diagrams follow Docsy's current light/dark palette and existing font stack. Click the diagram to open the fullscreen zoom/pan viewer. Expand **Diagram source** to inspect or copy the original notation.\n\n## UML sequence diagrams\n\nAn author submits a change to Docsy, which validates it and produces a preview for a reviewer. The reviewer makes the final decision; generating a preview does not publish the change.\n\n```mermaid Documentation review sequence\nsequenceDiagram\n  actor Author\n  participant Docsy\n  actor Reviewer\n  Author->>Docsy: Update articles and YAML\n  Docsy->>Docsy: Validate content\n  Docsy-->>Reviewer: Reviewable preview\n  Reviewer-->>Author: Approve or request changes\n```\n\n## UML class diagrams\n\nAn article contains sections and credits one or more authors. An agent is a kind of author with explicit provider metadata, not an automatic proof of correctness.\n\n```mermaid Articles, sections and authors\nclassDiagram\n  class Article {\n    +String title\n    +String source\n    +validate()\n  }\n  class Section {\n    +String heading\n    +String anchor\n  }\n  class Author {\n    +String name\n  }\n  class Agent {\n    +String provider\n  }\n  Article \"1\" *-- \"many\" Section : contains\n  Article --> Author : credits\n  Author <|-- Agent\n```\n\n## UML state diagrams\n\nA failed validation returns a draft to editing. Only a reviewed preview is ready for a separate deployment step.\n\n```mermaid Documentation change states\nstateDiagram-v2\n  [*] --> Draft\n  Draft --> Validating: Run checks\n  Validating --> Draft: Fix errors\n  Validating --> Preview: Checks pass\n  Preview --> Draft: Request changes\n  Preview --> Ready: Approve\n  Ready --> [*]\n```\n\n## Configure Mermaid through YAML\n\nMerge this into your existing configuration:\n\n```yaml\ncontent:\n  mermaid:\n    enabled: true\n    maxTextSize: 50000\n    maxEdges: 500\n    sourceLabel: Diagram source\n    errorLabel: This diagram could not be rendered. Check its source below.\n```\n\nThese are the defaults. `enabled: false` leaves Mermaid fences as ordinary source code and does not load the Mermaid renderer. `maxTextSize` is a per-diagram character limit; `maxEdges` is passed to Mermaid's graph renderer. Docsy validates the source safety rules and size during validation/build. Mermaid grammar/layout is evaluated in the reader's browser; a syntax or layout error displays a message and keeps the copyable source visible instead of hiding it.\n\nThe renderer fixes Mermaid to strict security settings. Diagram-local configuration directives and frontmatter, resource URLs, external images and font loading are rejected. Set site-wide appearance through Docsy's theme configuration, not Mermaid `init` directives or `themeCSS`.\n\n## PlantUML exports\n\nThe following preview was generated from a real `.puml` source with PlantUML 1.2026.9. The preview and source download remain inside this article's access boundary.\n\nDiagram: Author submits documentation to Docsy for validation and a reviewer decides whether to approve it.&#xA;&#xA;A PlantUML sequence diagram with downloadable source.&#xA;&#xA;Editable PlantUML source is available from the article’s diagram card.\n\nRegister a local SVG or PNG export and optional source:\n\n```yaml\ncontent:\n  diagrams:\n    article-review:\n      format: plantuml\n      image: content/diagrams/article-review.svg\n      source: content/diagrams/article-review.puml\n      alt: Author submits documentation to Docsy for validation and a reviewer decides whether to approve it.\n      caption: A PlantUML sequence diagram with downloadable source.\n      background: light\n```\n\nEmbed it with `::plantuml{src=\"article-review\"}` in Markdown or `<PlantUml src=\"article-review\" />` in MDX. No imports or executable MDX are required. When using an explicit `content.components` list, include `plantuml` to enable the component.\n\nExport locally using your trusted PlantUML installation, for example:\n\n```sh\njava -DPLANTUML_SECURITY_PROFILE=SANDBOX -jar plantuml.jar -tsvg content/diagrams/article-review.puml\n```\n\nStore protected exports and originals under `content/`, not `public/`. SVG exports must be self-contained: scripts, handlers, external resources and external fonts are rejected. PNG exports are supported as well. The export preserves its chosen palette; set `background` to match that export rather than expecting a light export to automatically become a dark one.\n\nDocsy does **not** run raw PlantUML fences or `.puml` preprocessors, execute Java, resolve `!include` directives or contact a PlantUML server. Re-export the SVG/PNG after changing its source. For diagrams rendered directly from editable text, use the Mermaid examples above.\n\n## Search, agent exports and restricted docs\n\nMermaid notation remains intact in Markdown/JSON exports and participates in full-text search. PlantUML exports contribute their description and caption instead of image data. JavaScript-disabled readers can still read Mermaid source and view PlantUML exports.\n\nBoth integrations use the article's existing access rules. Mermaid notation is delivered with the article, not through a separate public data endpoint. PlantUML image/source data is embedded in the authorized article. Do not put protected diagram sources in `public/`, which bypasses authorization.\n\nSee [draw.io diagrams](/guides/tutorials/drawio-diagrams) for the existing export-based integration and [native MDX](/guides/tutorials/native-mdx) for article authoring.\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/mermaid-and-uml.md"}