puml-for-markdown 1.1.0 → 1.2.0

package/README.md

@@ -1,25 +1,44 @@
 # puml-for-markdown
 
-## 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](https://crashedmind.github.io/PlantUMLHitchhikersGuide/PlantUMLSpriteLibraries/plantuml_sprites.html) (small graphic images)
-* Any time you make changes to diagrams you should be able to run the CLI tool to update the markdown links
+## 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. [PlantUML](https://plantuml.com) 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.
 
-### Example With Link Only
+### 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)-->
+```
 
-[Only Link](https://tinyurl.com/y847en68)<!--[Only Link](./puml/level_1_system_view.puml)-->
+Here's the result. **Try clicking on the yellow blocks.**
 
-### Example with Image, Click to Open Interactive Diagram
+[![Diagram Image Link](https://tinyurl.com/y847en68)](https://tinyurl.com/y847en68)<!--![Diagram Image Link](./puml/level_1_system_view.puml)-->
 
-[![Example With Graph Image](https://tinyurl.com/y847en68)](https://tinyurl.com/y847en68)<!--![Example With Graph Image](./puml/level_1_system_view.puml)-->
+### 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](https://tinyurl.com/y847en68)<!--[Click to Open Interactive Diagram](./puml/level_1_system_view.puml)-->
+
+## 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](https://crashedmind.github.io/PlantUMLHitchhikersGuide/PlantUMLSpriteLibraries/plantuml_sprites.html) (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](https://plantuml.com) allows you to create diagrams that are defined using a simple and intuitive language.
@@ -27,19 +46,27 @@ PlantUML diagrams are great for designing new projects but they don't work very
 are some [workarounds](https://stackoverflow.com/questions/32203610/how-to-integrate-uml-diagrams-into-gitlab-or-github),
 but I found these to be unstable and they have a lot of caveats.
 
-### Installation
-`npm i -g puml-for-markdown`
+**Update**: Github released support for embeddable Mermaid diagrams, but PlantUML is still unsupported,
+[see here](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/) 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
+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
+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)-->
 ```
@@ -47,22 +74,29 @@ replaced with
 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.
 
-Optionally you can specify the CLI to output the diagram images as png and/or svg.
+### 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`
+- You can specify the PUML server used to render the diagrams see `--puml-server-url`
 
-### CLI Usage
+### 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, --respect-gitignore          Automatically ignore MD files in .gitignore paths (default: true)
-  -i, --gitignore-path <path>      If --respect-gitignore is set, use set this as path to .gitignore file. (default: rootDirectory/.gitignore)
+  -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")
@@ -75,9 +109,10 @@ Options:
 - 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](./.husky/pre-commit) to see how to add a git hook
-- If you are saving diagram images and have puml files which only define constants/settings
-(i.e. [example](./puml/constants.puml)) these aren't renderable on their own (since there is nothing to render)
-and you'll see a warning in the console saying it failed to save the image to file.
+- If you are saving diagram images and have puml files which only define constants or settings
+(i.e. [example](./puml/constants.puml)) 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
@@ -112,8 +147,23 @@ though.
 
 ### More Examples
 [![ERD](https://tinyurl.com/ya6qvr7r)](https://tinyurl.com/ya6qvr7r)<!--![ERD](./puml/level_4_erd.puml)-->
+
+
+
 [![Container View](https://tinyurl.com/yblre3m4)](https://tinyurl.com/yblre3m4)<!--![Container View](./puml/level_2_container_view.puml)-->
+
+
+
 [![Component View - Label Retrieval Job](https://tinyurl.com/y8egw3wt)](https://tinyurl.com/y8egw3wt)<!--![Component View - Label Retrieval Job](./puml/level_3_component_view_label_retrieval_job.puml)-->
+
+
+
 [![Component View - Pipeline Component](https://tinyurl.com/y9j7twkz)](https://tinyurl.com/y9j7twkz)<!--![Component View - Pipeline Component](./puml/level_3_component_view_pipeline.puml)-->
+
+
+
 [![Activity Diagram - Sampler A](https://tinyurl.com/ybp8ju9x)](https://tinyurl.com/ybp8ju9x)<!--![Activity Diagram - Sampler A](./puml/level_4_activity_diagram_sampler_a.puml)-->
+
+
+
 [![Activity Diagram - Sampler B](https://tinyurl.com/ya3cqxkv)](https://tinyurl.com/ya3cqxkv)<!--![Activity Diagram - Sampler B](./puml/level_4_activity_diagram_sampler_b.puml)-->

package/bin/index.js

@@ -13,6 +13,11 @@ const run = require(path.resolve(__dirname, '../index.js'))
 
 new Command()
     .description('An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.')
+    .option(
+        '-s, --puml-server-url <url>',
+        'This is the base URL used to render diagrams. Defaults to the public plantuml server.',
+        'https://www.plantuml.com/plantuml',
+    )
     .addOption(new Option(
             '-x, --root-directory <path>',
             'The path to your project'
@@ -39,7 +44,7 @@ new Command()
     )
     .option(
         '-g, --ignore-gitignore',
-        "Don't ignore files PUML and MD files in projects gitignore",
+        "Don't use .gitignore to skip PUML and MD",
     )
     .addOption(new Option(
             '-i, --gitignore-path <path>',

package/index.js

@@ -17,17 +17,14 @@ const tiny = require('tinyurl');
 const parseGitIgnore = require('gitignore-globs');
 
 
-// CONSTANTS
-
-const PUML_SERVER = 'https://www.plantuml.com/plantuml'
-
 // HELPERS
 
 const getBuffer = bent('buffer')
 const mkdirIfDoesntExist = (p) => !fs.existsSync(p) && fs.mkdirSync(p, {recursive: true})
-const getPumlUrl = (imgFormat, encodedData, shorten) => shorten ?
-    tiny.shorten(getFullPumlUrl(imgFormat, encodedData)) : getFullPumlUrl(imgFormat, encodedData)
-const getFullPumlUrl = (imgFormat, encodedData) => `${PUML_SERVER}/${imgFormat}/${encodedData}}`
+const getPumlUrl = ({imgFormat, encodedData, shorten, pumlServerUrl}) => shorten ?
+    tiny.shorten(getFullPumlUrl({imgFormat, encodedData, pumlServerUrl})) :
+    getFullPumlUrl({imgFormat, encodedData, pumlServerUrl})
+const getFullPumlUrl = ({imgFormat, encodedData, pumlServerUrl}) => `${pumlServerUrl}/${imgFormat}/${encodedData}}`
 const mapUniqMatches = (s, re, mapper, match = re.exec(s), results = []) => {
     if (match) return mapUniqMatches(s, re, mapper, re.exec(s), results.concat([match]))
     return _.uniqBy(results, String).map(mapper)
@@ -58,11 +55,12 @@ const replaceMdIgnoringCode = (mdString, replaceFn) => {
 // DATA STRUCTURES
 
 class PumlLinks extends Map {
-    constructor(pumlPaths, shouldShortenLinks) {
+    constructor({ pumlPaths, shouldShortenLinks, pumlServerUrl }) {
         super();
         this.shouldShortenLinks = shouldShortenLinks
-        // Mark paths so we know which should be visited
-        // Any path that's not marked 0 we know isn't a puml path because it doesn't correspond to a puml fil
+        this.pumlServerUrl = pumlServerUrl
+        // We need to know which paths should be visited
+        // Any path that's not marked 0 we know isn't a puml path because it doesn't correspond to a puml file
         pumlPaths.forEach(p => this.set(p, 0))
     }
 
@@ -74,7 +72,9 @@ class PumlLinks extends Map {
         if (typeof v === 'number') return super.set(pumlPath, v)
 
         const encodedData = plantUmlEncoder.encode(v)
-        const url = await getPumlUrl('svg', encodedData, this.shouldShortenLinks)
+        const url = await getPumlUrl({
+            imgFormat: 'svg', encodedData, shorten: this.shouldShortenLinks, pumlServerUrl: this.pumlServerUrl
+        })
         return super.set(pumlPath, {encodedData, url, data: v});
     }
 
@@ -90,13 +90,13 @@ const downloadImg = async (outputPath, imgUrl) => {
     fs.writeFileSync(outputPath, imgBuffer)
 }
 
-const saveDiagram = async ({rootDirectory, distDirectory, pumlPath, imgFormat, encodedData}) => {
+const saveDiagram = async ({rootDirectory, distDirectory, pumlPath, imgFormat, encodedData, pumlServerUrl}) => {
     const outputPath = path.join(
         distDirectory, pumlPath.replace(rootDirectory, '').replace(/\.puml$/, `.${imgFormat}`)
     )
 
     mkdirIfDoesntExist(path.dirname(outputPath))
-    const imgUrl = getFullPumlUrl(imgFormat, encodedData)
+    const imgUrl = getFullPumlUrl({ imgFormat, encodedData, pumlServerUrl })
     try {
         await downloadImg(outputPath, imgUrl)
     } catch (e) {
@@ -105,12 +105,12 @@ const saveDiagram = async ({rootDirectory, distDirectory, pumlPath, imgFormat, e
     }
 }
 
-const saveDiagrams = async ({ rootDirectory, distDirectory, imageFormats, pumlLinks }) => {
+const saveDiagrams = async ({rootDirectory, distDirectory, imageFormats, pumlLinks, pumlServerUrl}) => {
     fs.rmSync(distDirectory, {recursive: true, force: true});
     for (let [pumlPath, {encodedData}] of pumlLinks) {
         for (let imgFormat of imageFormats) {
             await saveDiagram({
-                distDirectory, rootDirectory, pumlPath, imgFormat, encodedData
+                distDirectory, rootDirectory, pumlPath, imgFormat, encodedData, pumlServerUrl
             })
         }
     }
@@ -190,6 +190,7 @@ const processMdFile = async (mdPath, pumlLinks) => {
 
 const runOnce = async (
     {
+        pumlServerUrl,
         rootDirectory,
         markdownDirectory,
         pumlDirectory,
@@ -207,14 +208,16 @@ const runOnce = async (
     const ignore = respectGitignore ? parseGitIgnore(gitignorePath) : []
     const mdPaths = glob.sync(`${markdownDirectory}/**/*.md`, {ignore, nodir: true})
     const pumlPaths = glob.sync(`${pumlDirectory}/**/*.puml`, {ignore, nodir: true})
-    const pumlLinks = new PumlLinks(pumlPaths, shouldShortenLinks)
+    const pumlLinks = new PumlLinks({
+        pumlPaths, shouldShortenLinks, pumlServerUrl
+    })
 
     for (let p of pumlPaths) await processPumlFile(p, pumlLinks)
     for (let p of mdPaths) await processMdFile(p, pumlLinks)
 
     if (outputImages) {
         await saveDiagrams({
-            rootDirectory, distDirectory, imageFormats, pumlLinks
+            rootDirectory, distDirectory, imageFormats, pumlLinks, pumlServerUrl
         })
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "puml-for-markdown",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.",
   "main": "index.js",
   "scripts": {
@@ -35,7 +35,9 @@
     "generator",
     "cli",
     "diagrams",
-    "documentation"
+    "documentation",
+    "architecture",
+    "architecture-diagrams"
   ],
   "repository": {
     "type": "git",