puml-for-markdown 1.0.0 → 1.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -24
- package/bin/index.js +80 -69
- package/index.js +36 -34
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -1,25 +1,45 @@
|
|
|
1
1
|
# puml-for-markdown
|
|
2
2
|
|
|
3
|
-
##
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
* Should support PlantUML [sprites](https://crashedmind.github.io/PlantUMLHitchhikersGuide/PlantUMLSpriteLibraries/plantuml_sprites.html) (small graphic images)
|
|
10
|
-
* Any time you make changes to diagrams you should be able to run the CLI tool to update the markdown links
|
|
3
|
+
## Simple CLI Usage
|
|
4
|
+
Just run `puml-for-markdown` in any directory where you have markdown files and it will render links to PlantUML files
|
|
5
|
+
in markdown comments. The best part about this is that it requires no build files, you don't even need to store
|
|
6
|
+
puml images in your repo. Also the embedded diagrams can link to other diagrams. [PlantUML](https://plantuml.com) files
|
|
7
|
+
allow you to create diagrams that are defined using a simple and intuitive language. By default the entire directory
|
|
8
|
+
is recursively searched, automatically ignoring anything in the gitignore file.
|
|
11
9
|
|
|
12
10
|
## Examples
|
|
13
11
|
The following examples are of a project I worked on, **yellow components will link you to another diagram**. Obviously the
|
|
14
12
|
diagram content has been obfuscated.
|
|
15
13
|
|
|
16
|
-
###
|
|
14
|
+
### Embed a Diagram
|
|
15
|
+
You can easily add an embedded diagram to your markdown. Simply add a link to the puml file in a markdown comment like so:
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
<!---->
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Here's the result. **Try clicking on the yellow blocks.**
|
|
22
|
+
|
|
23
|
+
[](https://tinyurl.com/y847en68)<!---->
|
|
17
24
|
|
|
18
|
-
|
|
25
|
+
### Link Only
|
|
26
|
+
To render a link to a puml diagram, do the same thing but exclude the `!`
|
|
27
|
+
```
|
|
28
|
+
<!--[Click to Open Interactive Diagram](./puml/level_1_system_view.puml)-->
|
|
29
|
+
```
|
|
19
30
|
|
|
20
|
-
|
|
31
|
+
which renders into
|
|
21
32
|
|
|
22
|
-
[
|
|
33
|
+
[Click to Open Interactive Diagram](https://tinyurl.com/y847en68)<!--[Click to Open Interactive Diagram](./puml/level_1_system_view.puml)-->
|
|
34
|
+
|
|
35
|
+
## Goal
|
|
36
|
+
The goal is to make PlantUML diagrams easily accessible from markdown, specifically GitHub flavored.
|
|
37
|
+
* Should work with both private and public repositories
|
|
38
|
+
* Should not have to use tokens to get it to work with private repositories
|
|
39
|
+
* Should support hyperlinking to other diagrams
|
|
40
|
+
* Should support PlantUML `!include`
|
|
41
|
+
* Should support PlantUML [sprites](https://crashedmind.github.io/PlantUMLHitchhikersGuide/PlantUMLSpriteLibraries/plantuml_sprites.html) (small graphic images)
|
|
42
|
+
* Any time you make changes to diagrams you should be able to run the CLI tool to update the markdown links
|
|
23
43
|
|
|
24
44
|
## Background
|
|
25
45
|
[PlantUML](https://plantuml.com) allows you to create diagrams that are defined using a simple and intuitive language.
|
|
@@ -27,19 +47,27 @@ PlantUML diagrams are great for designing new projects but they don't work very
|
|
|
27
47
|
are some [workarounds](https://stackoverflow.com/questions/32203610/how-to-integrate-uml-diagrams-into-gitlab-or-github),
|
|
28
48
|
but I found these to be unstable and they have a lot of caveats.
|
|
29
49
|
|
|
30
|
-
|
|
31
|
-
|
|
50
|
+
**Update**: Github released support for embeddable Mermaid diagrams, but PlantUML is still unsupported,
|
|
51
|
+
[see here](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/) for more info.
|
|
52
|
+
|
|
32
53
|
|
|
33
54
|
### Basic Usage
|
|
34
55
|
Whenever you run the CLI it will add a tinyurl link to the rendered SVG next to the markdown comments referencing a
|
|
35
|
-
puml diagram. E.g.
|
|
56
|
+
puml diagram. E.g.
|
|
57
|
+
```
|
|
58
|
+
<!--[Example With Only Link](./puml/level_1_system_view.puml)-->
|
|
59
|
+
```
|
|
60
|
+
will be replaced with
|
|
36
61
|
```
|
|
37
62
|
[Example With Only Link](https://tinyurl.com/yfpclfpp)<!--[Example With Only Link](./puml/level_1_system_view.puml)-->
|
|
38
63
|
```
|
|
39
64
|
|
|
40
65
|
When `!` is included in front of the markdown link, it will render the diagram image in the markdown. If the image is
|
|
41
|
-
clicked it will open up the diagram. E.g.
|
|
42
|
-
|
|
66
|
+
clicked it will open up the diagram. E.g.
|
|
67
|
+
```
|
|
68
|
+
<!---->
|
|
69
|
+
```
|
|
70
|
+
will be replaced with
|
|
43
71
|
```
|
|
44
72
|
[](https://tinyurl.com/yfpclfpp)<!---->
|
|
45
73
|
```
|
|
@@ -47,22 +75,31 @@ replaced with
|
|
|
47
75
|
If you want to update the link text or switch it between image and link, just update the comment and rerun the CLI. You
|
|
48
76
|
don't need to delete the rendered image or link.
|
|
49
77
|
|
|
50
|
-
|
|
78
|
+
### Installation
|
|
79
|
+
`npm i -g puml-for-markdown`
|
|
51
80
|
|
|
52
|
-
###
|
|
81
|
+
### Advanced Usage
|
|
82
|
+
Here are some other features supported
|
|
83
|
+
- You can specify the CLI to output the diagram images as png and/or svg see `--output-images` and `--image-formats`.
|
|
84
|
+
For an example of outputted images, checkout [dist_puml/puml](./dist_puml/puml). These images were created by the
|
|
85
|
+
[pre-commit hook](./.husky/pre-commit).
|
|
86
|
+
- You can specify the PUML server used to render the diagrams see `--puml-server-url`
|
|
87
|
+
|
|
88
|
+
### All CLI Options
|
|
53
89
|
```
|
|
54
90
|
Usage: puml-for-markdown [options]
|
|
55
91
|
|
|
56
92
|
An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.
|
|
57
93
|
|
|
58
94
|
Options:
|
|
95
|
+
-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")
|
|
59
96
|
-x, --root-directory <path> The path to your project (default: CWD)
|
|
60
97
|
-r, --hot-reload Rerun markdown generator every `interval` seconds, determined by interval option
|
|
61
98
|
-v, --interval-seconds <number> If --hot-reload is set, how often should it reload (default: 2)
|
|
62
99
|
-p, --puml-directory <path> Path to directory containing puml files which are referenced in markdown files (default: rootDirectory)
|
|
63
100
|
-m, --markdown-directory <path> Path to directory containing markdown files referencing puml files (default: rootDirectory)
|
|
64
|
-
-g, --
|
|
65
|
-
-i, --gitignore-path <path>
|
|
101
|
+
-g, --ignore-gitignore Don't use .gitignore to skip PUML and MD
|
|
102
|
+
-i, --gitignore-path <path> Use this as path to .gitignore file. (default: rootDirectory/.gitignore)
|
|
66
103
|
-d, --output-images If set, will output images of diagrams to the dist directory
|
|
67
104
|
-b, --dist-directory <path> If --output-images is set, path to output diagram images (default: rootDirectory/dist_puml)
|
|
68
105
|
-f, --image-formats <format> If --output-images is set, sets the output image format (choices: "png", "svg", "both", default: "png")
|
|
@@ -75,9 +112,10 @@ Options:
|
|
|
75
112
|
- Currently doesn't support cyclic graph references, i.e. a diagram can't reference any diagrams which reference back
|
|
76
113
|
to it
|
|
77
114
|
- See the [pre-commit hook](./.husky/pre-commit) to see how to add a git hook
|
|
78
|
-
- If you are saving diagram images and have puml files which only define constants
|
|
79
|
-
(i.e. [example](./puml/constants.puml))
|
|
80
|
-
|
|
115
|
+
- If you are saving diagram images and have puml files which only define constants or settings
|
|
116
|
+
(i.e. [example](./puml/constants.puml)) you'll see a warning in the console saying it failed to save the image to file
|
|
117
|
+
because these aren't renderable on their own (since there is nothing to render)
|
|
118
|
+
- Anything inside `inline code` or `code blocks` will be excluded from rendering
|
|
81
119
|
|
|
82
120
|
### How It Works
|
|
83
121
|
#### Using PlantUML Web Service to Render PUML Diagrams
|
|
@@ -106,3 +144,29 @@ there are no issues using them in private repositories.
|
|
|
106
144
|
### Testing
|
|
107
145
|
Currently there is no TDD, for now I've just been using the example diagrams to test. The examples are pretty extensive
|
|
108
146
|
though.
|
|
147
|
+
|
|
148
|
+
### Other Helpful Links
|
|
149
|
+
* [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
|
|
150
|
+
|
|
151
|
+
### More Examples
|
|
152
|
+
[](https://tinyurl.com/ya6qvr7r)<!---->
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
[](https://tinyurl.com/yblre3m4)<!---->
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
[](https://tinyurl.com/y8egw3wt)<!---->
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
[](https://tinyurl.com/y9j7twkz)<!---->
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
[](https://tinyurl.com/ybp8ju9x)<!---->
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
[](https://tinyurl.com/ya3cqxkv)<!---->
|
package/bin/index.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
|
|
3
3
|
const path = require('path')
|
|
4
|
+
const fs = require('fs')
|
|
4
5
|
|
|
5
6
|
const {Command, Option} = require('commander')
|
|
6
7
|
|
|
@@ -12,72 +13,82 @@ const run = require(path.resolve(__dirname, '../index.js'))
|
|
|
12
13
|
// =============
|
|
13
14
|
|
|
14
15
|
new Command()
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
)
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
16
|
+
.description('An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.')
|
|
17
|
+
.option(
|
|
18
|
+
'-s, --puml-server-url <url>',
|
|
19
|
+
'This is the base URL used to render diagrams. Defaults to the public plantuml server.',
|
|
20
|
+
'https://www.plantuml.com/plantuml',
|
|
21
|
+
)
|
|
22
|
+
.addOption(new Option(
|
|
23
|
+
'-x, --root-directory <path>',
|
|
24
|
+
'The path to your project'
|
|
25
|
+
).default(process.cwd(), 'CWD')
|
|
26
|
+
)
|
|
27
|
+
.option(
|
|
28
|
+
'-r, --hot-reload',
|
|
29
|
+
'Rerun markdown generator every `interval` seconds, determined by interval option',
|
|
30
|
+
)
|
|
31
|
+
.option(
|
|
32
|
+
'-v, --interval-seconds <number>',
|
|
33
|
+
'If --hot-reload is set, how often should it reload',
|
|
34
|
+
2,
|
|
35
|
+
)
|
|
36
|
+
.addOption(new Option(
|
|
37
|
+
'-p, --puml-directory <path>',
|
|
38
|
+
'Path to directory containing puml files which are referenced in markdown files',
|
|
39
|
+
).default(false, 'rootDirectory')
|
|
40
|
+
)
|
|
41
|
+
.addOption(new Option(
|
|
42
|
+
'-m, --markdown-directory <path>',
|
|
43
|
+
'Path to directory containing markdown files referencing puml files',
|
|
44
|
+
).default(false, 'rootDirectory')
|
|
45
|
+
)
|
|
46
|
+
.option(
|
|
47
|
+
'-g, --ignore-gitignore',
|
|
48
|
+
"Don't use .gitignore to skip PUML and MD. Will automatically be true if no gitignore is found",
|
|
49
|
+
)
|
|
50
|
+
.addOption(new Option(
|
|
51
|
+
'-i, --gitignore-path <path>',
|
|
52
|
+
'Use this as path to .gitignore file.'
|
|
53
|
+
).default(false, 'rootDirectory/.gitignore')
|
|
54
|
+
)
|
|
55
|
+
.option(
|
|
56
|
+
'-d, --output-images',
|
|
57
|
+
'If set, will output images of diagrams to the dist directory',
|
|
58
|
+
)
|
|
59
|
+
.addOption(new Option(
|
|
60
|
+
'-b, --dist-directory <path>',
|
|
61
|
+
'If --output-images is set, path to output diagram images'
|
|
62
|
+
).default(false, 'rootDirectory/dist_puml')
|
|
63
|
+
)
|
|
64
|
+
.addOption(new Option(
|
|
65
|
+
'-f, --image-formats <format>',
|
|
66
|
+
'If --output-images is set, sets the output image format',
|
|
67
|
+
).choices(['png', 'svg', 'both']).default('png')
|
|
68
|
+
)
|
|
69
|
+
.option(
|
|
70
|
+
'-t, --turn-off-link-shortening',
|
|
71
|
+
"Use the full puml server link instead of the tiny url, if your diagrams are too big this won't work",
|
|
72
|
+
)
|
|
73
|
+
.action(opts => {
|
|
74
|
+
const useDefaultGitignorePath = !opts.gitignorePath
|
|
75
|
+
|
|
76
|
+
opts.distDirectory = opts.distDirectory || path.resolve(opts.rootDirectory, 'dist_puml')
|
|
77
|
+
opts.gitignorePath = opts.gitignorePath || path.resolve(opts.rootDirectory, '.gitignore')
|
|
78
|
+
opts.markdownDirectory = opts.markdownDirectory || opts.rootDirectory
|
|
79
|
+
opts.pumlDirectory = opts.pumlDirectory || opts.rootDirectory
|
|
80
|
+
opts.shouldShortenLinks = !opts.turnOffLinkShortening
|
|
81
|
+
opts.respectGitignore = !opts.ignoreGitignore
|
|
82
|
+
opts.imageFormats = opts.imageFormats === 'both' ? ['png', 'svg'] : [opts.imageFormats]
|
|
83
|
+
|
|
84
|
+
// If a gitignore path wasn't specified, don't try and parse it
|
|
85
|
+
if (useDefaultGitignorePath && !fs.existsSync(opts.gitignorePath)) {
|
|
86
|
+
opts.respectGitignore = false
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
return run(opts).catch((e) => {
|
|
90
|
+
console.error('FATAL EXCEPTION')
|
|
91
|
+
console.error(e)
|
|
92
|
+
})
|
|
93
|
+
})
|
|
94
|
+
.parse(process.argv)
|
package/index.js
CHANGED
|
@@ -17,15 +17,14 @@ const tiny = require('tinyurl');
|
|
|
17
17
|
const parseGitIgnore = require('gitignore-globs');
|
|
18
18
|
|
|
19
19
|
|
|
20
|
-
// CONSTANTS
|
|
21
|
-
|
|
22
|
-
const PUML_SVG_SERVER = 'https://www.plantuml.com/plantuml/svg'
|
|
23
|
-
const PUML_PNG_SERVER = 'https://www.plantuml.com/plantuml/png'
|
|
24
|
-
|
|
25
20
|
// HELPERS
|
|
26
21
|
|
|
27
22
|
const getBuffer = bent('buffer')
|
|
28
23
|
const mkdirIfDoesntExist = (p) => !fs.existsSync(p) && fs.mkdirSync(p, {recursive: true})
|
|
24
|
+
const getPumlUrl = ({imgFormat, encodedData, shorten, pumlServerUrl}) => shorten ?
|
|
25
|
+
tiny.shorten(getFullPumlUrl({imgFormat, encodedData, pumlServerUrl})) :
|
|
26
|
+
getFullPumlUrl({imgFormat, encodedData, pumlServerUrl})
|
|
27
|
+
const getFullPumlUrl = ({imgFormat, encodedData, pumlServerUrl}) => `${pumlServerUrl}/${imgFormat}/${encodedData}}`
|
|
29
28
|
const mapUniqMatches = (s, re, mapper, match = re.exec(s), results = []) => {
|
|
30
29
|
if (match) return mapUniqMatches(s, re, mapper, re.exec(s), results.concat([match]))
|
|
31
30
|
return _.uniqBy(results, String).map(mapper)
|
|
@@ -53,25 +52,15 @@ const replaceMdIgnoringCode = (mdString, replaceFn) => {
|
|
|
53
52
|
return replaceMdIgnoringCodeBlocks(mdString, str => replaceMdIgnoringInlineCode(str, replaceFn))
|
|
54
53
|
}
|
|
55
54
|
|
|
56
|
-
const getPngUrl = encodedData => `${PUML_PNG_SERVER}/${encodedData}}`
|
|
57
|
-
const getSvgUrl = encodedData => `${PUML_SVG_SERVER}/${encodedData}}`
|
|
58
|
-
const getPumlTinyUrl = encodedData => tiny.shorten(getSvgUrl(encodedData))
|
|
59
|
-
const getImgUrl = (imageFormat, encodedData) => {
|
|
60
|
-
const imgFormatToGetUrlFn = {
|
|
61
|
-
png: getPngUrl,
|
|
62
|
-
svg: getSvgUrl
|
|
63
|
-
}
|
|
64
|
-
return imgFormatToGetUrlFn[imageFormat](encodedData)
|
|
65
|
-
}
|
|
66
|
-
|
|
67
55
|
// DATA STRUCTURES
|
|
68
56
|
|
|
69
57
|
class PumlLinks extends Map {
|
|
70
|
-
constructor(pumlPaths,
|
|
58
|
+
constructor({ pumlPaths, shouldShortenLinks, pumlServerUrl }) {
|
|
71
59
|
super();
|
|
72
|
-
this.
|
|
73
|
-
|
|
74
|
-
//
|
|
60
|
+
this.shouldShortenLinks = shouldShortenLinks
|
|
61
|
+
this.pumlServerUrl = pumlServerUrl
|
|
62
|
+
// We need to know which paths should be visited
|
|
63
|
+
// Any path that's not marked 0 we know isn't a puml path because it doesn't correspond to a puml file
|
|
75
64
|
pumlPaths.forEach(p => this.set(p, 0))
|
|
76
65
|
}
|
|
77
66
|
|
|
@@ -83,7 +72,9 @@ class PumlLinks extends Map {
|
|
|
83
72
|
if (typeof v === 'number') return super.set(pumlPath, v)
|
|
84
73
|
|
|
85
74
|
const encodedData = plantUmlEncoder.encode(v)
|
|
86
|
-
const url =
|
|
75
|
+
const url = await getPumlUrl({
|
|
76
|
+
imgFormat: 'svg', encodedData, shorten: this.shouldShortenLinks, pumlServerUrl: this.pumlServerUrl
|
|
77
|
+
})
|
|
87
78
|
return super.set(pumlPath, {encodedData, url, data: v});
|
|
88
79
|
}
|
|
89
80
|
|
|
@@ -99,13 +90,13 @@ const downloadImg = async (outputPath, imgUrl) => {
|
|
|
99
90
|
fs.writeFileSync(outputPath, imgBuffer)
|
|
100
91
|
}
|
|
101
92
|
|
|
102
|
-
const saveDiagram = async ({rootDirectory, distDirectory, pumlPath,
|
|
93
|
+
const saveDiagram = async ({rootDirectory, distDirectory, pumlPath, imgFormat, encodedData, pumlServerUrl}) => {
|
|
103
94
|
const outputPath = path.join(
|
|
104
|
-
distDirectory, pumlPath.replace(rootDirectory, '').replace(/\.puml$/, `.${
|
|
95
|
+
distDirectory, pumlPath.replace(rootDirectory, '').replace(/\.puml$/, `.${imgFormat}`)
|
|
105
96
|
)
|
|
106
97
|
|
|
107
98
|
mkdirIfDoesntExist(path.dirname(outputPath))
|
|
108
|
-
const imgUrl =
|
|
99
|
+
const imgUrl = getFullPumlUrl({ imgFormat, encodedData, pumlServerUrl })
|
|
109
100
|
try {
|
|
110
101
|
await downloadImg(outputPath, imgUrl)
|
|
111
102
|
} catch (e) {
|
|
@@ -114,12 +105,12 @@ const saveDiagram = async ({rootDirectory, distDirectory, pumlPath, imageFormat,
|
|
|
114
105
|
}
|
|
115
106
|
}
|
|
116
107
|
|
|
117
|
-
const saveDiagrams = async ({
|
|
108
|
+
const saveDiagrams = async ({rootDirectory, distDirectory, imageFormats, pumlLinks, pumlServerUrl}) => {
|
|
118
109
|
fs.rmSync(distDirectory, {recursive: true, force: true});
|
|
119
110
|
for (let [pumlPath, {encodedData}] of pumlLinks) {
|
|
120
|
-
for (let
|
|
111
|
+
for (let imgFormat of imageFormats) {
|
|
121
112
|
await saveDiagram({
|
|
122
|
-
distDirectory, rootDirectory, pumlPath,
|
|
113
|
+
distDirectory, rootDirectory, pumlPath, imgFormat, encodedData, pumlServerUrl
|
|
123
114
|
})
|
|
124
115
|
}
|
|
125
116
|
}
|
|
@@ -151,6 +142,7 @@ const processPumlFile = async (pumlPath, pumlLinks) => {
|
|
|
151
142
|
|
|
152
143
|
let data = fs.readFileSync(pumlPath, 'utf8')
|
|
153
144
|
await Promise.all(mapUniqMatches(data, /\$link=["']([^"']+)['"]/gm, async ([pumlLink, pumlLinkPath]) => {
|
|
145
|
+
// console.debug(pumlLink, pumlLinkPath)
|
|
154
146
|
const newLink = await processPumlFile(path.resolve(path.dirname(pumlPath), pumlLinkPath), pumlLinks)
|
|
155
147
|
data = data.replaceAll(pumlLink, `$link="${newLink.url}"`)
|
|
156
148
|
}))
|
|
@@ -168,7 +160,7 @@ const processMdFile = async (mdPath, pumlLinks) => {
|
|
|
168
160
|
console.info(`Processing md file at ${mdPath}`)
|
|
169
161
|
let originalMdStr = fs.readFileSync(mdPath, 'utf8')
|
|
170
162
|
const findMdPumlLinksRE = new RegExp(
|
|
171
|
-
`(\\[
|
|
163
|
+
`(\\[.*\]\\([^)]+\\))?<!\-\-(!?\\[[^\\]]+\\])\\(([^)]+\\.puml)\\)\-\->`, 'g'
|
|
172
164
|
)
|
|
173
165
|
// Add puml server tinyurl link for puml links indicated in markdown comments
|
|
174
166
|
const mdWithUpdatedPumlLinks = replaceMdIgnoringCode(originalMdStr, (str) => {
|
|
@@ -178,12 +170,17 @@ const processMdFile = async (mdPath, pumlLinks) => {
|
|
|
178
170
|
if (!pumlLink) {
|
|
179
171
|
throw Error(`Could not find puml for md link path = ${mdPumlLinkPath}, absolute path = ${pumlPath}`)
|
|
180
172
|
}
|
|
173
|
+
let replacement
|
|
181
174
|
// If the puml link is a markdown image
|
|
182
175
|
if (linkText[0] === '!') {
|
|
183
|
-
|
|
176
|
+
replacement = `[${linkText}(${pumlLink.url})](${pumlLink.url})<!--${linkText}(${mdPumlLinkPath})-->`
|
|
177
|
+
} else {
|
|
178
|
+
// If the puml link is a markdown hyperlink
|
|
179
|
+
replacement = `${linkText}(${pumlLink.url})<!--${linkText}(${mdPumlLinkPath})-->`
|
|
184
180
|
}
|
|
185
|
-
|
|
186
|
-
|
|
181
|
+
|
|
182
|
+
// console.debug({match, linkText, mdPumlLinkPath, replacement})
|
|
183
|
+
return replacement
|
|
187
184
|
})
|
|
188
185
|
})
|
|
189
186
|
|
|
@@ -193,6 +190,7 @@ const processMdFile = async (mdPath, pumlLinks) => {
|
|
|
193
190
|
|
|
194
191
|
const runOnce = async (
|
|
195
192
|
{
|
|
193
|
+
pumlServerUrl,
|
|
196
194
|
rootDirectory,
|
|
197
195
|
markdownDirectory,
|
|
198
196
|
pumlDirectory,
|
|
@@ -201,7 +199,7 @@ const runOnce = async (
|
|
|
201
199
|
imageFormats,
|
|
202
200
|
respectGitignore,
|
|
203
201
|
gitignorePath,
|
|
204
|
-
|
|
202
|
+
shouldShortenLinks,
|
|
205
203
|
}
|
|
206
204
|
) => {
|
|
207
205
|
assert(fs.existsSync(markdownDirectory), "That's an invalid md folder path")
|
|
@@ -210,13 +208,17 @@ const runOnce = async (
|
|
|
210
208
|
const ignore = respectGitignore ? parseGitIgnore(gitignorePath) : []
|
|
211
209
|
const mdPaths = glob.sync(`${markdownDirectory}/**/*.md`, {ignore, nodir: true})
|
|
212
210
|
const pumlPaths = glob.sync(`${pumlDirectory}/**/*.puml`, {ignore, nodir: true})
|
|
213
|
-
const pumlLinks = new PumlLinks(
|
|
211
|
+
const pumlLinks = new PumlLinks({
|
|
212
|
+
pumlPaths, shouldShortenLinks, pumlServerUrl
|
|
213
|
+
})
|
|
214
214
|
|
|
215
215
|
for (let p of pumlPaths) await processPumlFile(p, pumlLinks)
|
|
216
216
|
for (let p of mdPaths) await processMdFile(p, pumlLinks)
|
|
217
217
|
|
|
218
218
|
if (outputImages) {
|
|
219
|
-
await saveDiagrams({
|
|
219
|
+
await saveDiagrams({
|
|
220
|
+
rootDirectory, distDirectory, imageFormats, pumlLinks, pumlServerUrl
|
|
221
|
+
})
|
|
220
222
|
}
|
|
221
223
|
}
|
|
222
224
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "puml-for-markdown",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.1",
|
|
4
4
|
"description": "An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.",
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"scripts": {
|
|
@@ -35,7 +35,9 @@
|
|
|
35
35
|
"generator",
|
|
36
36
|
"cli",
|
|
37
37
|
"diagrams",
|
|
38
|
-
"documentation"
|
|
38
|
+
"documentation",
|
|
39
|
+
"architecture",
|
|
40
|
+
"architecture-diagrams"
|
|
39
41
|
],
|
|
40
42
|
"repository": {
|
|
41
43
|
"type": "git",
|