{"id":13591429,"url":"https://github.com/danielyaa5/puml-for-markdown","last_synced_at":"2025-04-04T16:13:19.603Z","repository":{"id":38451259,"uuid":"452391696","full_name":"danielyaa5/puml-for-markdown","owner":"danielyaa5","description":"A CLI tool to embed interactive PUML diagrams to your github markdown files.","archived":false,"fork":false,"pushed_at":"2022-11-28T14:28:38.000Z","size":1670,"stargazers_count":309,"open_issues_count":5,"forks_count":63,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-02-19T12:50:59.168Z","etag":null,"topics":["c4","cli","diagram","github","markdown","plantuml","uml","uml-diagram"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/danielyaa5.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-26T18:24:43.000Z","updated_at":"2025-02-18T20:05:25.000Z","dependencies_parsed_at":"2023-01-22T04:05:44.324Z","dependency_job_id":null,"html_url":"https://github.com/danielyaa5/puml-for-markdown","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielyaa5%2Fpuml-for-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielyaa5%2Fpuml-for-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielyaa5%2Fpuml-for-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielyaa5%2Fpuml-for-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielyaa5","download_url":"https://codeload.github.com/danielyaa5/puml-for-markdown/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247208139,"owners_count":20901570,"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":["c4","cli","diagram","github","markdown","plantuml","uml","uml-diagram"],"created_at":"2024-08-01T16:00:57.368Z","updated_at":"2025-04-04T16:13:19.586Z","avatar_url":"https://github.com/danielyaa5.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# puml-for-markdown\n\n## Simple CLI Usage\nJust run `puml-for-markdown` in any directory where you have markdown files and it will render links to PlantUML files\nin markdown comments. The best part about this is that it requires no build files, you don't even need to store \npuml images in your repo. Also the embedded diagrams can link to other diagrams. [PlantUML](https://plantuml.com) files \nallow you to create diagrams that are defined using a simple and intuitive language. By default the entire directory \nis recursively searched, automatically ignoring anything in the gitignore file.\n\n## Examples\nThe following examples are of a project I worked on, **yellow components will link you to another diagram**. Obviously the\ndiagram content has been obfuscated.\n\n### Embed a Diagram\nYou can easily add an embedded diagram to your markdown. Simply add a link to the puml file in a markdown comment like so:\n\n```\n\u003c!--![Diagram Image Link](./puml/level_1_system_view.puml)--\u003e\n```\n\nHere's the result. **Try clicking on the yellow blocks.**\n\n[![Diagram Image Link](https://tinyurl.com/y847en68)](https://tinyurl.com/y847en68)\u003c!--![Diagram Image Link](./puml/level_1_system_view.puml)--\u003e\n\n### Link Only\nTo render a link to a puml diagram, do the same thing but exclude the `!`\n```\n\u003c!--[Click to Open Interactive Diagram](./puml/level_1_system_view.puml)--\u003e\n```\n\nwhich renders into\n\n[Click to Open Interactive Diagram](https://tinyurl.com/y847en68)\u003c!--[Click to Open Interactive Diagram](./puml/level_1_system_view.puml)--\u003e\n\n## Goal\nThe goal is to make PlantUML diagrams easily accessible from markdown, specifically GitHub flavored.\n* Should work with both private and public repositories\n* Should not have to use tokens to get it to work with private repositories\n* Should support hyperlinking to other diagrams\n* Should support PlantUML `!include`\n* Should support PlantUML [sprites](https://crashedmind.github.io/PlantUMLHitchhikersGuide/PlantUMLSpriteLibraries/plantuml_sprites.html) (small graphic images)\n* Any time you make changes to diagrams you should be able to run the CLI tool to update the markdown links\n\n## Background\n[PlantUML](https://plantuml.com) allows you to create diagrams that are defined using a simple and intuitive language.\nPlantUML diagrams are great for designing new projects but they don't work very well in Github markdown preview. There\nare some [workarounds](https://stackoverflow.com/questions/32203610/how-to-integrate-uml-diagrams-into-gitlab-or-github),\nbut I found these to be unstable and they have a lot of caveats.\n\n**Update**: Github released support for embeddable Mermaid diagrams, but PlantUML is still unsupported,\n[see here](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/) for more info.\n\n\n### Basic Usage\nWhenever you run the CLI it will add a tinyurl link to the rendered SVG next to the markdown comments referencing a\npuml diagram. E.g.\n```\n\u003c!--[Example With Only Link](./puml/level_1_system_view.puml)--\u003e\n```\nwill be replaced with\n```\n[Example With Only Link](https://tinyurl.com/yfpclfpp)\u003c!--[Example With Only Link](./puml/level_1_system_view.puml)--\u003e\n```\n\nWhen `!` is included in front of the markdown link, it will render the diagram image in the markdown. If the image is\nclicked it will open up the diagram. E.g.\n```\n\u003c!--![Example With Graph Image](./puml/level_1_system_view.puml)--\u003e\n```\nwill be replaced with\n```\n[![Example With Graph Image](https://tinyurl.com/yfpclfpp)](https://tinyurl.com/yfpclfpp)\u003c!--![Example With Graph Image](./puml/level_1_system_view.puml)--\u003e\n```\n\nIf you want to update the link text or switch it between image and link, just update the comment and rerun the CLI. You\ndon't need to delete the rendered image or link.\n\n### Installation\n`npm i -g puml-for-markdown`\n\n### Advanced Usage\nHere are some other features supported\n- You can specify the CLI to output the diagram images as png and/or svg see `--output-images` and `--image-formats`.\nFor an example of outputted images, checkout [dist_puml/puml](./dist_puml/puml). These images were created by the\n[pre-commit hook](./.husky/pre-commit).\n- You can specify the PUML server used to render the diagrams see `--puml-server-url`\n\n### All CLI Options\n```\nUsage: puml-for-markdown [options]\n\nAn application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.\n\nOptions:\n  -s, --puml-server-url \u003curl\u003e      This is the base URL used to render diagrams. Defaults to the public plantuml server. (default: \"https://www.plantuml.com/plantuml\")\n  -x, --root-directory \u003cpath\u003e      The path to your project (default: CWD)\n  -r, --hot-reload                 Rerun markdown generator every `interval` seconds, determined by interval option\n  -v, --interval-seconds \u003cnumber\u003e  If --hot-reload is set, how often should it reload (default: 2)\n  -p, --puml-directory \u003cpath\u003e      Path to directory containing puml files which are referenced in markdown files (default: rootDirectory)\n  -m, --markdown-directory \u003cpath\u003e  Path to directory containing markdown files referencing puml files (default: rootDirectory)\n  -g, --ignore-gitignore           Don't use .gitignore to skip PUML and MD\n  -i, --gitignore-path \u003cpath\u003e      Use this as path to .gitignore file. (default: rootDirectory/.gitignore)\n  -d, --output-images              If set, will output images of diagrams to the dist directory\n  -b, --dist-directory \u003cpath\u003e      If --output-images is set, path to output diagram images (default: rootDirectory/dist_puml)\n  -f, --image-formats \u003cformat\u003e     If --output-images is set, sets the output image format (choices: \"png\", \"svg\", \"both\", default: \"png\")\n  -t, --turn-off-link-shortening   Use the full puml server link instead of the tiny url, if your diagrams are too big this won't work\n  -h, --help                       display help for command\n```\n\n### Notes\n- Comments within inline or multiline code styling will be ignored\n- Currently doesn't support cyclic graph references, i.e. a diagram can't reference any diagrams which reference back\nto it\n- See the [pre-commit hook](./.husky/pre-commit) to see how to add a git hook\n- If you are saving diagram images and have puml files which only define constants or settings\n(i.e. [example](./puml/constants.puml)) you'll see a warning in the console saying it failed to save the image to file\nbecause these aren't renderable on their own (since there is nothing to render)\n- Anything inside `inline code` or `code blocks` will be excluded from rendering\n\n### How It Works\n#### Using PlantUML Web Service to Render PUML Diagrams\nYou can use PlantUML using the online web service to generate images on-the-fly. A online demonstration is available at\n[http://www.plantuml.com/plantuml](http://www.plantuml.com/plantuml). You can pass the\n[encoded text](https://plantuml.com/text-encoding) of your diagrams to the web service in the url path and it will\ngenerate an SVG or PNG for you. Here's a simple HelloWorld example\n[http://www.plantuml.com/plantuml/uml/Aov9B2hXil98pSd9LoZFByf9iUOgBial0000](http://www.plantuml.com/plantuml/uml/Aov9B2hXil98pSd9LoZFByf9iUOgBial0000).\nLarge diagrams will have very long encoding strings, they can exceed maximum url length. They also don't look very good\nin markdown files. By default the CLI will use the tinyurl.com service to shorten the link to the diagram.\n\n#### Encoding PUML Diagrams for the Web Service\nThe CLI will use the `plantuml-encoder` package to encode puml files. To support hyperlinking diagrams we need to parse\nall hyperlinks in the puml files. A dependency graph is created for the files and a DFS is performed where we create\nlinks for the leaf nodes first, then replace the links in the parent nodes with the links to the leaf nodes. The puml\nfiles are not actually modified, only the puml files content in memory is modified. By default the tinyurl free service\nis used to shorten the links.\n\nIn order to support `!include` we parse puml files and replace any `!include` with the contents of the file referenced.\n\n#### Parsing Markdown\nThe markdown files are then parsed for markdown comments. If the comments reference a PlantUML file, a link to the web\nservice url will be added next to the comment. Because these links contain the full PlantUML diagram encoding in it,\nthere are no issues using them in private repositories.\n\n### Testing\nCurrently there is no TDD, for now I've just been using the example diagrams to test. The examples are pretty extensive\nthough.\n\n### Other Helpful Links\n* [C4-Puml](https://github.com/plantuml-stdlib/C4-PlantUML): A collection of PlantUML diagrams for use in C4, you'll see me using this in my examples\n\n### Known Issues\n* Seems to be breaking on Windows, see [here](https://github.com/danielyaa5/puml-for-markdown/issues/6). I don't have a\nWindows machine to test on so help here would be appreciated.\n\n### More Examples\n[![ERD](https://tinyurl.com/ya6qvr7r)](https://tinyurl.com/ya6qvr7r)\u003c!--![ERD](./puml/level_4_erd.puml)--\u003e\n\n\n\n[![Container View](https://tinyurl.com/yblre3m4)](https://tinyurl.com/yblre3m4)\u003c!--![Container View](./puml/level_2_container_view.puml)--\u003e\n\n\n\n[![Component View - Label Retrieval Job](https://tinyurl.com/y8egw3wt)](https://tinyurl.com/y8egw3wt)\u003c!--![Component View - Label Retrieval Job](./puml/level_3_component_view_label_retrieval_job.puml)--\u003e\n\n\n\n[![Component View - Pipeline Component](https://tinyurl.com/y9j7twkz)](https://tinyurl.com/y9j7twkz)\u003c!--![Component View - Pipeline Component](./puml/level_3_component_view_pipeline.puml)--\u003e\n\n\n\n[![Activity Diagram - Sampler A](https://tinyurl.com/ybp8ju9x)](https://tinyurl.com/ybp8ju9x)\u003c!--![Activity Diagram - Sampler A](./puml/level_4_activity_diagram_sampler_a.puml)--\u003e\n\n\n\n[![Activity Diagram - Sampler B](https://tinyurl.com/ya3cqxkv)](https://tinyurl.com/ya3cqxkv)\u003c!--![Activity Diagram - Sampler B](./puml/level_4_activity_diagram_sampler_b.puml)--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielyaa5%2Fpuml-for-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielyaa5%2Fpuml-for-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielyaa5%2Fpuml-for-markdown/lists"}