{"id":14525265,"url":"https://github.com/pandoc-ext/diagram","last_synced_at":"2026-02-13T18:41:30.506Z","repository":{"id":153645094,"uuid":"627957782","full_name":"pandoc-ext/diagram","owner":"pandoc-ext","description":"Generate diagrams from embedded code; supports Mermaid, Dot/GraphViz, PlantUML, Asymptote, D2, CeTZ, and TikZ.","archived":false,"fork":false,"pushed_at":"2025-10-26T20:00:46.000Z","size":120,"stargazers_count":160,"open_issues_count":24,"forks_count":20,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-26T22:05:17.362Z","etag":null,"topics":["asymptote","cetz","d2lang","graphviz","lua","mermaid","pandoc","pandoc-filter","plantuml","text-to-diagram","tikz"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/pandoc-ext.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["tarleb"]}},"created_at":"2023-04-14T15:17:57.000Z","updated_at":"2025-10-26T20:00:50.000Z","dependencies_parsed_at":"2024-05-31T17:10:54.165Z","dependency_job_id":"ac524102-2ba3-48d7-a03b-334a850f8ecf","html_url":"https://github.com/pandoc-ext/diagram","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/pandoc-ext/diagram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandoc-ext%2Fdiagram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandoc-ext%2Fdiagram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandoc-ext%2Fdiagram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandoc-ext%2Fdiagram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pandoc-ext","download_url":"https://codeload.github.com/pandoc-ext/diagram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pandoc-ext%2Fdiagram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29414282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-13T06:24:03.484Z","status":"ssl_error","status_checked_at":"2026-02-13T06:23:12.830Z","response_time":78,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["asymptote","cetz","d2lang","graphviz","lua","mermaid","pandoc","pandoc-filter","plantuml","text-to-diagram","tikz"],"created_at":"2024-09-04T14:01:17.064Z","updated_at":"2026-02-13T18:41:30.501Z","avatar_url":"https://github.com/pandoc-ext.png","language":"Lua","funding_links":["https://github.com/sponsors/tarleb"],"categories":["Lua"],"sub_categories":[],"readme":"Diagram Generator\n=================\n\nThis Lua filter is used to create figures from code blocks: images\nare generated from the code with the help of external programs.\nThe filter processes diagram code for Asymptote, Graphviz,\nMermaid, PlantUML, Ti*k*Z, and D2.\n\n\nUsage\n-----\n\nThe filter modifies the internal document representation; it can\nbe used with many publishing systems that are based on pandoc.\n\nPlease make sure to read the section on [security](#security) if\nyou are going to use this filter with third-party input documents.\n\n\u003e [!IMPORTANT]\n\u003e This filter makes the generated images available to pandoc, but\n\u003e *does not* write image files by itself. Use pandoc's\n\u003e `--extract-media` to write the generated images to disk. Or,\n\u003e when producing HTML, use `--embed-resources` to incorporate the\n\u003e images in the output file via `data` URIs.\n\n### Plain pandoc\n\nPass the filter to pandoc via the `--lua-filter` (or `-L`) command\nline option.\n\n    pandoc --lua-filter diagram.lua ...\n\n### Quarto\n\nUsers of Quarto can install this filter as an extension with\n\n    quarto install extension pandoc-ext/diagram\n\nand use it by adding `diagram` to the `filters` entry in their\nYAML header.\n\n``` yaml\n---\nfilters:\n  - diagram\n---\n```\n\n#### Notes on usage with Quarto\n\nQuarto comes with its own system for diagram generation that can\nbe used for a variety of diagrams. Especially Mermaid diagram\ngeneration is much faster with Quarto's built-in diagram handling.\n\nDue to the way in which Quarto handles code blocks, *do not* add\n`filename` attributes to code block attribute lists.\n\n`````` markdown\n``` {.tikz filename=\"my-graph\"}\n% DON'T use the filename attribute on code blocks\n...\n``````\n\nInstead, use the \"comment-pipe\" syntax to define the graphic's\nfile name.\n\n`````` markdown\n``` tikz\n%%| filename: my-graph\n% This should work ok.\n...\n```\n``````\n\n### R Markdown\n\nUse `pandoc_args` to invoke the filter. See the [R Markdown\nCookbook](https://bookdown.org/yihui/rmarkdown-cookbook/lua-filters.html)\nfor details.\n\n``` yaml\n---\noutput:\n  word_document:\n    pandoc_args: ['--lua-filter=diagram.lua']\n---\n```\n\nDiagram types\n-------------\n\nThe table below lists the supported diagram drawing systems, the\nclass that must be used for the system, and the main executable\nthat the filter calls to generate an image from the code. The\n*environment variables* column lists the names of env variables\nthat can be used to specify a specific executable.\n\n| System      | code block class  | executable | env variable    |\n|-------------|-------------------|------------|-----------------|\n| [Asymptote] | `asymptote`       | `asy`      | `ASYMPTOTE_BIN` |\n| [GraphViz]  | `dot`             | `dot`      | `DOT_BIN`       |\n| [Mermaid]   | `mermaid`         | `mmdc`     | `MERMAID_BIN`   |\n| [PlantUML]  | `plantuml`        | `plantuml` | `PLANTUML_BIN`  |\n| [Ti*k*Z]    | `tikz`            | `pdflatex` | `PDFLATEX_BIN`  |\n| [cetz]      | `cetz`            | `typst`    | `TYPST_BIN`     |\n| [D2]        | `d2`              | `d2`       | `D2_BIN`        |\n\n### Other diagram engines\n\nThe filter can be extended with local packages; see\n[Configuration](#configuration) below.\n\n[Asymptote]: https://asymptote.sourceforge.io/\n[GraphViz]: https://www.graphviz.org/\n[Mermaid]: https://mermaid.js.org/\n[PlantUML]: https://plantuml.com/\n[Ti*k*Z]: https://github.com/pgf-tikz/pgf\n[Cetz]: https://github.com/cetz-package/cetz\n[D2]: https://d2lang.com/\n\nFigure options\n--------------\n\nOptions can be given using the syntax pioneered by [Quarto]:\n\n````\n``` {.dot}\n//| label: fig-boring\n//| fig-cap: \"A boring Graphviz graph.\"\ndigraph boring {\n  A -\u003e B;\n}\n```\n````\n\n[Quarto]: https://quarto.org/\n\nConfiguration\n-------------\n\nThe filter can be configured with the `diagram` metadata entry.\n\nCurrently supported options:\n\n- `cache`: controls whether the images are cached. If the cache is\n  enabled, then the images are recreated only when their code\n  changes. This option is *disabled* by default.\n\n- `cache-dir`: Sets the directory in which the images are cached.\n  The default is to use the `pandoc-diagram-filter` subdir of the\n  a common caching location. This will be, in the order of\n  preference, the value of the `XDG_CACHE_HOME` environment\n  variable if it is set, or alternatively `%USERPROFILE%\\.cache` on\n  Windows and `$HOME/.cache` on all other platforms.\n\n  Caching is disabled if none of the environment variables\n  mentioned above have been defined.\n\n- `engine`: options for specific engines, e.g. `plantuml` or\n  `mermaid`. The options must be nested below the engine name.\n  Allowed settings are either `true` or `false` to enable or\n  disable the engine, respectively, or a map of options.\n  The available settings are:\n\n  + `mime-type`: the output MIME type that should be produced with\n    this engine. This can be used to choose a specific type, or to\n    disable certain output formats. For example, the following\n    disables support for PDF output in PlantUML, which can be\n    useful when the necessary libraries are unavailable on a\n    system:\n\n    ``` yaml\n    diagram:\n      engine:\n        plantuml:\n          mime-type:\n            application/pdf: false\n    ```\n\n  + `line_comment_start`: the character sequence that starts a\n    line comment; unset or change this to disable or modify the\n    syntax of user options in the diagram code.\n\n  + `execpath`: the path to the engine's executable. Use this to\n    override the default executable name listed in the table\n    above.\n\n    Use a list to pass additional arguments to the executable.\n    E.g., `execpath: ['xelatex' '-halt-on-error']` will use\n    `xelatex` as the executable and pass `-halt-on-error` as the\n    first argument.\n\n  + `package`: if this option is set then the filter will try to\n    `require` a Lua package with the given name. If the operation\n    is successful, then the result will be used as the compiler\n    for that diagram type.\n\n  + Any other option is passed through to the engine. See the\n    engine-specific settings below.\n\n### Engine-specific options\n\nSome engines accept additional options. These options can either\nbe passed globally as part of the respective `engine` entry, or\nlocally by adding `opt-NAME` as an attribute to the diagram code\nblock. Global options always override local options for security\nreasons.\n\n#### Ti*k*Z\n\nThe Ti*k*Z engine accepts the `header-includes` and\n`additional-packages` options. Both options are added to the\nintermediary TeX file that is used to produce the output file. The\noptions differ only in how string values are handled, with bare\nstrings in `header-includes` being escaped and those in\n`additional-packages` being treated as TeX code.\n\nWhile mentioned above, it should be highlighted that the\n`execpath` option can be used to select a specific LaTeX engine.\nThe default is `pdflatex`.\n\nExample:\n\n``` yaml\n---\ndiagram:\n  engine:\n    tikz:\n      execpath: lualatex\n      header-includes:\n        - '\\usepackage{adjustbox}'\n        - '\\usetikzlibrary{arrows, shapes}'\n---\n```\n\nSecurity\n--------\n\nThis filter **should not** be used with **untrusted documents**,\n***unless*** local configs prevent the setting of filter options\nin the metadata: An attacker that can set the execpath for an\nengine can execute any binary on the system with the user's\npermissions. It is hence recommended to review any document before\nusing it with this filter to avoid malicious and misuse of the\nfilter.\n\nThe security is improved considerably if the `diagram` metadata\nfield is unset or set to a predefined value before this filter is\ncalled, e.g., via another filter or a defaults file.\n\nHere is an example defaults file that configures the filter such\nthat the configs cannot be overwritten by the document.\n\n``` yaml\n# file: diagram-filter.yaml\nfilters: ['diagram.lua']\nmetadata:\n  diagram:\n    engine:\n      # enable dot/GraphViz and PlantUML with default options\n      dot: true\n      plantuml: true\n\n      # disable processing of asymptote and Mermaid diagrams\n      asymptote: false\n      mermaid: false\n\n      # Use LuaLaTeX to compile TikZ, define headers\n      tikz:\n        execpath: lualatex\n        additional-packages: |\n          \\usepackage{adjustbox}\n          \\usetikzlibrary{arrows, shapes}\n```\n\nUsage:\n\n    pandoc -d diagram-filter ...\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpandoc-ext%2Fdiagram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpandoc-ext%2Fdiagram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpandoc-ext%2Fdiagram/lists"}