puml-for-markdown - npm Package Compare versions

Comparing version 1.1.0 to 1.2.0

bin/index.js

@@ -16,2 +16,7 @@ #!/usr/bin/env node
     .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(
@@ -43,3 +48,3 @@ '-x, --root-directory <path>',
         '-g, --ignore-gitignore',
-        "Don't ignore files PUML and MD files in projects gitignore",
+        "Don't use .gitignore to skip PUML and MD",
     )
@@ -46,0 +51,0 @@ .addOption(new Option(

index.js

@@ -20,6 +20,2 @@ /**
 
-// CONSTANTS
-
-const PUML_SERVER = 'https://www.plantuml.com/plantuml'
-
 // HELPERS
@@ -29,5 +25,6 @@
 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 = []) => {
@@ -63,7 +60,8 @@ if (match) return mapUniqMatches(s, re, mapper, re.exec(s), results.concat([match]))
 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))
@@ -80,3 +78,5 @@ }
         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});
@@ -97,3 +97,3 @@ }
 
-const saveDiagram = async ({rootDirectory, distDirectory, pumlPath, imgFormat, encodedData}) => {
+const saveDiagram = async ({rootDirectory, distDirectory, pumlPath, imgFormat, encodedData, pumlServerUrl}) => {
     const outputPath = path.join(
@@ -104,3 +104,3 @@ distDirectory, pumlPath.replace(rootDirectory, '').replace(/\.puml$/, `.${imgFormat}`)
     mkdirIfDoesntExist(path.dirname(outputPath))
-    const imgUrl = getFullPumlUrl(imgFormat, encodedData)
+    const imgUrl = getFullPumlUrl({ imgFormat, encodedData, pumlServerUrl })
     try {
@@ -114,3 +114,3 @@ await downloadImg(outputPath, imgUrl)
 
-const saveDiagrams = async ({ rootDirectory, distDirectory, imageFormats, pumlLinks }) => {
+const saveDiagrams = async ({rootDirectory, distDirectory, imageFormats, pumlLinks, pumlServerUrl}) => {
     fs.rmSync(distDirectory, {recursive: true, force: true});
@@ -120,3 +120,3 @@ for (let [pumlPath, {encodedData}] of pumlLinks) {
             await saveDiagram({
-                distDirectory, rootDirectory, pumlPath, imgFormat, encodedData
+                distDirectory, rootDirectory, pumlPath, imgFormat, encodedData, pumlServerUrl
             })
@@ -201,2 +201,3 @@ }
     {
+        pumlServerUrl,
         rootDirectory,
@@ -219,3 +220,5 @@ markdownDirectory,
     const pumlPaths = glob.sync(`${pumlDirectory}/**/*.puml`, {ignore, nodir: true})
-    const pumlLinks = new PumlLinks(pumlPaths, shouldShortenLinks)
+    const pumlLinks = new PumlLinks({
+        pumlPaths, shouldShortenLinks, pumlServerUrl
+    })
 
@@ -227,3 +230,3 @@ for (let p of pumlPaths) await processPumlFile(p, pumlLinks)
         await saveDiagrams({
-            rootDirectory, distDirectory, imageFormats, pumlLinks
+            rootDirectory, distDirectory, imageFormats, pumlLinks, pumlServerUrl
         })
@@ -230,0 +233,0 @@ }

package.json

 {
   "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.",
@@ -38,3 +38,5 @@ "main": "index.js",
     "diagrams",
-    "documentation"
+    "documentation",
+    "architecture",
+    "architecture-diagrams"
   ],
@@ -41,0 +43,0 @@ "repository": {

README.md

 # 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. [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.
+
+### 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](https://tinyurl.com/y847en68)](https://tinyurl.com/y847en68)<!--![Diagram Image Link](./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
@@ -12,14 +43,2 @@ The goal is to make PlantUML diagrams easily accessible from markdown, specifically GitHub flavored.
 
-## 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
-
-[Only Link](https://tinyurl.com/y847en68)<!--[Only Link](./puml/level_1_system_view.puml)-->
-
-### Example with Image, Click to Open Interactive Diagram
-
-[![Example With Graph Image](https://tinyurl.com/y847en68)](https://tinyurl.com/y847en68)<!--![Example With Graph Image](./puml/level_1_system_view.puml)-->
-
 ## Background
@@ -31,9 +50,14 @@ [PlantUML](https://plantuml.com) allows you to create diagrams that are defined using a simple and intuitive language.
 
-### 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)-->
@@ -43,5 +67,8 @@ ```
 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)-->
@@ -53,5 +80,11 @@ ```
 
-Optionally you can specify the CLI to output the diagram images as png and/or svg.
+### Installation
+`npm i -g puml-for-markdown`
 
-### CLI Usage
+### 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`
+
+### All CLI Options
 ```
@@ -63,2 +96,3 @@ Usage: puml-for-markdown [options]
 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)
@@ -69,4 +103,4 @@ -r, --hot-reload                 Rerun markdown generator every `interval` seconds, determined by interval option
   -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
@@ -84,5 +118,6 @@ -b, --dist-directory <path>      If --output-images is set, path to output diagram images (default: rootDirectory/dist_puml)
 - 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
 
@@ -122,6 +157,21 @@ ### How It Works
 [![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)-->

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

41149

increased by4.93%

Lines of code

274

increased by3.79%

Number of lines in readme file

170

increased by41.67%

No dependency changes