Including C4-PlantUML locally with relative path

[schferbe]

The C4-PlantUML documentation suggests that you can include the puml files locally with relative paths. I tried this with c4builder site and "generateLocalImages": true but that results in errors.

Is there a way that I missed?

[azizur]

Looks like this is always going to the remote server (www.plantuml.com):
https://github.com/adrianvlupu/C4-Builder/blob/master/utils.js#L119

[adrianvlupu]

I'm working on a feature to allow it to clone the C4-PlantUML repo locally. Hopefully it will be up this weekend.

@schferbe, the generateLocalImages refers to the actual image generation from .puml files without hitting the PlantUML server. Most likely you don't have java, graphviz and all the stuff required to actually do it locally. I think I need to update the readme with how to set that up or try to make the module actually install them.

[adrianvlupu]

@azizur, the line is from a helper function in case the online server is used. The relevant lines are in https://github.com/adrianvlupu/C4-Builder/blob/master/build.js#L584, https://github.com/adrianvlupu/C4-Builder/blob/master/build.js#L158 and https://github.com/adrianvlupu/C4-Builder/blob/master/build.js#L102

[bwoester]

I wouldn't necessarily go with relative include paths. If you work on the same project with a couple of colleagues, or on a couple different devices, this forces every environment to stick to a certain folder structure.

From my point of view (and maybe it's already possible and I simply missed it), it should be good enough to provide a way to configure PlantUML's include path.

[ognyandim]

This is another problem with C4-PlantUML local install.

I use it locally by replacing the C4-Plantuml web paths to local paths.

Repro:

• Install VS Code and the PlantUML plugin and the vz grapher
• Install c4 builder and copy C4-Plantuml locally
• Replace its links in the C4 PlantUML with the local links by changing the web and local links comment
• Pick one of the examples in the c4 builder and replace the link to point to the local C4 puml files instead of the web.
• Start working on the docs with the site generation option - c4builder site -w
• Open the puml in VS Code and press alt + d to generate the diagram - its generated ok
• Refresh the page for the site - bang!
• Replace the relative path with full path and save and press alt + d to generate the diagram - everything works fine both in VS Code and in the site generation.

The problem with this is that when another developer downloads the docs the absolute path must be replaced everywhere.

Summary:

• Working with relative local links in puml like this

!include ..\docs\C4-PlantUML-master\C4_Component.puml

works but the site generation c4builder site -w brakes

• Working with absolute paths like this

!include C:\absolute_path\docs\C4-PlantUML-master\C4_Component.puml

works fine in both VS and site -w but makes it much harder for a team to work on the project until they all keep the same folder structure, a.k.a. same absolute paths.

Possible solution: Is it hard to add a path in the config that changes that?

[darielrll]

Hi, any update on this issue?

[ognyandim]

Do you accept PRs? I can try to work on this.

[adrianvlupu]

Yes, I accept PRs. Last weekend I managed to merge a couple of them. I would really appreciate a PR.

There's a branch I use for local development at https://github.com/adrianvlupu/C4-PlantUML/tree/local, that could be a good starting point.

[darielrll]

I solved this for now while the final solution is being developed using a local plantuml server in a docker container and adding the capability to serve as a static file the core C4 files, and modify C4 files to get the dependencies from this local server. Here is my initial approach: https://github.com/darielrll/c4-builder-example

[kontza]

This (work on local solution) sounds promising.

My current workaround is as such:

• I have a local copy of C4-Builder's files where, e.g.
  !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
  is replaced with
  !include %getenv("C4PLANTUML")/C4_Container.puml.
• Before I start to work on my project's architecture docs, I run my prep script, which sets the C4PLANTUML environment variable. I work on Mac, and that prep script sets the environment for both the current terminal session, and it uses launchctl to set it globally, so that further processes that are started also are aware of the variable.
• After running the prep script, I can start VS Code, and it can generate the PlantUML previews for the active file.
• And the same works for the command line c4builder.

I noticed that if I have a file .vscode/settings.json with the following:

{
    "plantuml.includepaths": ["C4-PlantUML directory"]
}

it works in VS Code.

The solution you work on... Could it scan that .vscode/settings.json if it exists, and use that?

[uhippo]

1. Put "C4-PlantUML" in the project root.
2. Update "!include https://raw.githubusercontent.com/adrianvlupu/C4-PlantUML/latest/C4_Component.puml" to "!include <C4/C4_Component>"

[jonesmith518]

• Put "C4-PlantUML" in the project root.
• Update "!include https://raw.githubusercontent.com/adrianvlupu/C4-PlantUML/latest/C4_Component.puml" to "!include <C4/C4_Component>"

thanks , and my additional settings:
in vscode settings:
"plantuml.includepaths": ["/path/to/C4-PlantUML-2.4.0"],
"plantuml.commandArgs": ["-DRELATIVE_INCLUDE=".""]