puml-for-markdown 1.0.0 → 1.1.0

package/README.md

@@ -106,3 +106,14 @@ 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](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
+
+### 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

@@ -38,13 +38,12 @@ new Command()
         ).default(false, 'rootDirectory')
     )
     .option(
-        '-g, --respect-gitignore',
-        'Automatically ignore MD files in .gitignore paths',
-        true,
+        '-g, --ignore-gitignore',
+        "Don't ignore files PUML and MD files in projects gitignore",
     )
     .addOption(new Option(
             '-i, --gitignore-path <path>',
-            'If --respect-gitignore is set, use set this as path to .gitignore file.'
+            'Use this as path to .gitignore file.'
         ).default(false, 'rootDirectory/.gitignore')
     )
     .option(
@@ -70,11 +69,10 @@ new Command()
         opts.gitignorePath = opts.gitignorePath || path.resolve(opts.rootDirectory, '.gitignore')
         opts.markdownDirectory = opts.markdownDirectory || opts.rootDirectory
         opts.pumlDirectory = opts.pumlDirectory || opts.rootDirectory
-        if (opts.imageFormats === 'both') {
-            opts.imageFormats = ['png', 'svg']
-        } else {
-            opts.imageFormats = [opts.imageFormats]
-        }
+        opts.shouldShortenLinks = !opts.turnOffLinkShortening
+        opts.respectGitignore = !opts.ignoreGitignore
+        opts.imageFormats = opts.imageFormats === 'both' ? ['png', 'svg'] : [opts.imageFormats]
+
         return run(opts).catch((e) => {
             console.error('FATAL EXCEPTION')
             console.error(e)

package/index.js

@@ -19,13 +19,15 @@ const parseGitIgnore = require('gitignore-globs');
 
 // CONSTANTS
 
-const PUML_SVG_SERVER = 'https://www.plantuml.com/plantuml/svg'
-const PUML_PNG_SERVER = 'https://www.plantuml.com/plantuml/png'
+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 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)
@@ -53,23 +55,12 @@ const replaceMdIgnoringCode = (mdString, replaceFn) => {
     return replaceMdIgnoringCodeBlocks(mdString, str => replaceMdIgnoringInlineCode(str, replaceFn))
 }
 
-const getPngUrl = encodedData => `${PUML_PNG_SERVER}/${encodedData}}`
-const getSvgUrl = encodedData => `${PUML_SVG_SERVER}/${encodedData}}`
-const getPumlTinyUrl = encodedData => tiny.shorten(getSvgUrl(encodedData))
-const getImgUrl = (imageFormat, encodedData) => {
-    const imgFormatToGetUrlFn = {
-        png: getPngUrl,
-        svg: getSvgUrl
-    }
-    return imgFormatToGetUrlFn[imageFormat](encodedData)
-}
-
 // DATA STRUCTURES
 
 class PumlLinks extends Map {
-    constructor(pumlPaths, turnOffLinkShortening) {
+    constructor(pumlPaths, shouldShortenLinks) {
         super();
-        this.turnOffLinkShortening = turnOffLinkShortening
+        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
         pumlPaths.forEach(p => this.set(p, 0))
@@ -83,7 +74,7 @@ class PumlLinks extends Map {
         if (typeof v === 'number') return super.set(pumlPath, v)
 
         const encodedData = plantUmlEncoder.encode(v)
-        const url = this.turnOffLinkShortening ? getSvgUrl(encodedData) : await getPumlTinyUrl(encodedData)
+        const url = await getPumlUrl('svg', encodedData, this.shouldShortenLinks)
         return super.set(pumlPath, {encodedData, url, data: v});
     }
 
@@ -99,13 +90,13 @@ const downloadImg = async (outputPath, imgUrl) => {
     fs.writeFileSync(outputPath, imgBuffer)
 }
 
-const saveDiagram = async ({rootDirectory, distDirectory, pumlPath, imageFormat, encodedData}) => {
+const saveDiagram = async ({rootDirectory, distDirectory, pumlPath, imgFormat, encodedData}) => {
     const outputPath = path.join(
-        distDirectory, pumlPath.replace(rootDirectory, '').replace(/\.puml$/, `.${imageFormat}`)
+        distDirectory, pumlPath.replace(rootDirectory, '').replace(/\.puml$/, `.${imgFormat}`)
     )
 
     mkdirIfDoesntExist(path.dirname(outputPath))
-    const imgUrl = getImgUrl(imageFormat, encodedData)
+    const imgUrl = getFullPumlUrl(imgFormat, encodedData)
     try {
         await downloadImg(outputPath, imgUrl)
     } catch (e) {
@@ -117,9 +108,9 @@ const saveDiagram = async ({rootDirectory, distDirectory, pumlPath, imageFormat,
 const saveDiagrams = async ({ rootDirectory, distDirectory, imageFormats, pumlLinks }) => {
     fs.rmSync(distDirectory, {recursive: true, force: true});
     for (let [pumlPath, {encodedData}] of pumlLinks) {
-        for (let imageFormat of imageFormats) {
+        for (let imgFormat of imageFormats) {
             await saveDiagram({
-                distDirectory, rootDirectory, pumlPath, imageFormat, encodedData
+                distDirectory, rootDirectory, pumlPath, imgFormat, encodedData
             })
         }
     }
@@ -151,6 +142,7 @@ const processPumlFile = async (pumlPath, pumlLinks) => {
 
     let data = fs.readFileSync(pumlPath, 'utf8')
     await Promise.all(mapUniqMatches(data, /\$link=["']([^"']+)['"]/gm, async ([pumlLink, pumlLinkPath]) => {
+        // console.debug(pumlLink, pumlLinkPath)
         const newLink = await processPumlFile(path.resolve(path.dirname(pumlPath), pumlLinkPath), pumlLinks)
         data = data.replaceAll(pumlLink, `$link="${newLink.url}"`)
     }))
@@ -168,7 +160,7 @@ const processMdFile = async (mdPath, pumlLinks) => {
     console.info(`Processing md file at ${mdPath}`)
     let originalMdStr = fs.readFileSync(mdPath, 'utf8')
     const findMdPumlLinksRE = new RegExp(
-        `(\\[?!?\\[?\\[[^\\[]*)?<!\-\-(!?\\[[^\\]]+\\])\\(([^)]+\\.puml)\\)\-\->`, 'g'
+        `(\\[.*\]\\([^)]+\\))?<!\-\-(!?\\[[^\\]]+\\])\\(([^)]+\\.puml)\\)\-\->`, 'g'
     )
     // Add puml server tinyurl link for puml links indicated in markdown comments
     const mdWithUpdatedPumlLinks = replaceMdIgnoringCode(originalMdStr, (str) => {
@@ -178,12 +170,17 @@ const processMdFile = async (mdPath, pumlLinks) => {
             if (!pumlLink) {
                 throw Error(`Could not find puml for md link path = ${mdPumlLinkPath}, absolute path = ${pumlPath}`)
             }
+            let replacement
             // If the puml link is a markdown image
             if (linkText[0] === '!') {
-                return `[${linkText}(${pumlLink.url})](${pumlLink.url})<!--${linkText}(${mdPumlLinkPath})-->`
+                replacement = `[${linkText}(${pumlLink.url})](${pumlLink.url})<!--${linkText}(${mdPumlLinkPath})-->`
+            } else {
+                // If the puml link is a markdown hyperlink
+                replacement = `${linkText}(${pumlLink.url})<!--${linkText}(${mdPumlLinkPath})-->`
             }
-            // If the puml link is a markdown hyperlink
-            return `${linkText}(${pumlLink.url})<!--${linkText}(${mdPumlLinkPath})-->`
+
+            // console.debug({match, linkText, mdPumlLinkPath, replacement})
+            return replacement
         })
     })
 
@@ -201,7 +198,7 @@ const runOnce = async (
         imageFormats,
         respectGitignore,
         gitignorePath,
-        turnOffLinkShortening,
+        shouldShortenLinks,
     }
 ) => {
     assert(fs.existsSync(markdownDirectory), "That's an invalid md folder path")
@@ -210,13 +207,15 @@ 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, turnOffLinkShortening)
+    const pumlLinks = new PumlLinks(pumlPaths, shouldShortenLinks)
 
     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 })
+        await saveDiagrams({
+            rootDirectory, distDirectory, imageFormats, pumlLinks
+        })
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "puml-for-markdown",
-  "version": "1.0.0",
+  "version": "1.1.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": {