npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

puml-for-markdown

v1.2.1

Published

An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.

Downloads

2,091

Readme

puml-for-markdown

Simple CLI Usage

Just run puml-for-markdown in any directory where you have markdown files and it will render links to PlantUML files in markdown comments. The best part about this is that it requires no build files, you don't even need to store puml images in your repo. Also the embedded diagrams can link to other diagrams. PlantUML files allow you to create diagrams that are defined using a simple and intuitive language. By default the entire directory is recursively searched, automatically ignoring anything in the gitignore file.

Examples

The following examples are of a project I worked on, yellow components will link you to another diagram. Obviously the diagram content has been obfuscated.

Embed a Diagram

You can easily add an embedded diagram to your markdown. Simply add a link to the puml file in a markdown comment like so:

<!--![Diagram Image Link](./puml/level_1_system_view.puml)-->

Here's the result. Try clicking on the yellow blocks.

Diagram Image Link

Link Only

To render a link to a puml diagram, do the same thing but exclude the !

<!--[Click to Open Interactive Diagram](./puml/level_1_system_view.puml)-->

which renders into

Click to Open Interactive Diagram

Goal

The goal is to make PlantUML diagrams easily accessible from markdown, specifically GitHub flavored.

  • Should work with both private and public repositories
  • Should not have to use tokens to get it to work with private repositories
  • Should support hyperlinking to other diagrams
  • Should support PlantUML !include
  • Should support PlantUML sprites (small graphic images)
  • Any time you make changes to diagrams you should be able to run the CLI tool to update the markdown links

Background

PlantUML allows you to create diagrams that are defined using a simple and intuitive language. PlantUML diagrams are great for designing new projects but they don't work very well in Github markdown preview. There are some workarounds, but I found these to be unstable and they have a lot of caveats.

Update: Github released support for embeddable Mermaid diagrams, but PlantUML is still unsupported, see here for more info.

Basic Usage

Whenever you run the CLI it will add a tinyurl link to the rendered SVG next to the markdown comments referencing a puml diagram. E.g.

<!--[Example With Only Link](./puml/level_1_system_view.puml)-->

will be replaced with

[Example With Only Link](https://tinyurl.com/yfpclfpp)<!--[Example With Only Link](./puml/level_1_system_view.puml)-->

When ! is included in front of the markdown link, it will render the diagram image in the markdown. If the image is clicked it will open up the diagram. E.g.

<!--![Example With Graph Image](./puml/level_1_system_view.puml)-->

will be replaced with

[![Example With Graph Image](https://tinyurl.com/yfpclfpp)](https://tinyurl.com/yfpclfpp)<!--![Example With Graph Image](./puml/level_1_system_view.puml)-->

If you want to update the link text or switch it between image and link, just update the comment and rerun the CLI. You don't need to delete the rendered image or link.

Installation

npm i -g puml-for-markdown

Advanced Usage

Here are some other features supported

  • You can specify the CLI to output the diagram images as png and/or svg see --output-images and --image-formats. For an example of outputted images, checkout dist_puml/puml. These images were created by the pre-commit hook.
  • You can specify the PUML server used to render the diagrams see --puml-server-url

All CLI Options

Usage: puml-for-markdown [options]

An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.

Options:
  -s, --puml-server-url <url>      This is the base URL used to render diagrams. Defaults to the public plantuml server. (default: "https://www.plantuml.com/plantuml")
  -x, --root-directory <path>      The path to your project (default: CWD)
  -r, --hot-reload                 Rerun markdown generator every `interval` seconds, determined by interval option
  -v, --interval-seconds <number>  If --hot-reload is set, how often should it reload (default: 2)
  -p, --puml-directory <path>      Path to directory containing puml files which are referenced in markdown files (default: rootDirectory)
  -m, --markdown-directory <path>  Path to directory containing markdown files referencing puml files (default: rootDirectory)
  -g, --ignore-gitignore           Don't use .gitignore to skip PUML and MD
  -i, --gitignore-path <path>      Use this as path to .gitignore file. (default: rootDirectory/.gitignore)
  -d, --output-images              If set, will output images of diagrams to the dist directory
  -b, --dist-directory <path>      If --output-images is set, path to output diagram images (default: rootDirectory/dist_puml)
  -f, --image-formats <format>     If --output-images is set, sets the output image format (choices: "png", "svg", "both", default: "png")
  -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
  -h, --help                       display help for command

Notes

  • Comments within inline or multiline code styling will be ignored
  • Currently doesn't support cyclic graph references, i.e. a diagram can't reference any diagrams which reference back to it
  • See the pre-commit hook to see how to add a git hook
  • If you are saving diagram images and have puml files which only define constants or settings (i.e. example) you'll see a warning in the console saying it failed to save the image to file because these aren't renderable on their own (since there is nothing to render)
  • Anything inside inline code or code blocks will be excluded from rendering

How It Works

Using PlantUML Web Service to Render PUML Diagrams

You can use PlantUML using the online web service to generate images on-the-fly. A online demonstration is available at http://www.plantuml.com/plantuml. You can pass the encoded text of your diagrams to the web service in the url path and it will generate an SVG or PNG for you. Here's a simple HelloWorld example http://www.plantuml.com/plantuml/uml/Aov9B2hXil98pSd9LoZFByf9iUOgBial0000. Large diagrams will have very long encoding strings, they can exceed maximum url length. They also don't look very good in markdown files. By default the CLI will use the tinyurl.com service to shorten the link to the diagram.

Encoding PUML Diagrams for the Web Service

The CLI will use the plantuml-encoder package to encode puml files. To support hyperlinking diagrams we need to parse all hyperlinks in the puml files. A dependency graph is created for the files and a DFS is performed where we create links for the leaf nodes first, then replace the links in the parent nodes with the links to the leaf nodes. The puml files are not actually modified, only the puml files content in memory is modified. By default the tinyurl free service is used to shorten the links.

In order to support !include we parse puml files and replace any !include with the contents of the file referenced.

Parsing Markdown

The markdown files are then parsed for markdown comments. If the comments reference a PlantUML file, a link to the web service url will be added next to the comment. Because these links contain the full PlantUML diagram encoding in it, there are no issues using them in private repositories.

Testing

Currently there is no TDD, for now I've just been using the example diagrams to test. The examples are pretty extensive though.

Other Helpful Links

  • C4-Puml: A collection of PlantUML diagrams for use in C4, you'll see me using this in my examples

More Examples

ERD

Container View

Component View - Label Retrieval Job

Component View - Pipeline Component

Activity Diagram - Sampler A

Activity Diagram - Sampler B