adrianvlupu/c4-builder

This is a documentation builder. You feed it .md and .puml and it exports a site, pdf, or a markdown with navigation.

c4-builder's Issues

Is it possible to exclude or include specific pattern matched files when building?

Hi! I tried to build my project and the output includes all my source files.
I'd like to include .md and .puml files only when building docs.
Is there any config variable that I can set this up?

graphviz was not found on the system

During installation (on MacOS) I am getting this message:
graphviz was not found on the system. Downloading vizjs instead. See http://plantuml.com/vizjs. This may take a few minutes.

This means it should work regardless of graphviz installed or not because vizjs is being installed. However, I am getting an error in the generated output site.

The graphviz requirement is not listed as a dependency. It would be useful to have this documented for new starters.

On Mac OS, it's simple homebrew command to install it:
brew install graphviz

C4Builder command never terminates

C4Builder command (version 0.2.16) never terminates and have to do Ctrl-C to close.
This causes timeout issues when used in a DevOps CI/Cd pipelines.
Command works and build the docs as expected, but then just hangs after it is done,

Support to multiple languages when create a c4builder project

Maybe it should be helpful to support multiple languages.

I'm a committer in an OpenSource project, which has PT-BR and ENG doc versions. I aim to use c4 builder to document the project's architecture and integrate them with my doc. For this, I need to build two c4 builder projects, one in PT-BR and a second in English.
I think it should be an option when creating the project to allow support for multiple languages.

Something as:

• docs
  • pt-br
  • eng
  • fr
• src
  • pt-br
    • system.puml
    • system.md
  • eng
    • system.puml
    • system.md
  • fr
    • system.puml
    • system.md

If this sounds like a good idea, I'd be happy to also work on a PR for this.

Fix markdown heading levels

Problem description

c4builder currently assumes that markdown files don't use h1 (#) and h2 (##) headers. For example:

If you don't know this, you might be tempted to start with a h1 heading, which is what you'd usually do. Then it looks like this:

This is probably not what you want. Even more obvious in case of generated markdown:

# test

* [Overview](#Overview)
* [src](#src)
  * [foo](#foo)

---

## Overview

# Top-level readme h1

top-level readme content

And here's the PDF view:

Thoughts

• Most projects use a h1 heading with their project name in the top-level readme file. If that is present, there's no need to render the project name separately or define a HOMEPAGE_NAME. (Related to #9.)
• To prevent forcing users to use only level 3+ headings, c4builder could alter heading levels in the build process.

Thoughts?

Feature Request: Support for Structurizr DSL

Now that there is a formal definition of Structurizr DSL exists, perhaps it is time to consider if C4Builder should support it.

I haven't read the Language reference line by line yet. I am sure it's possible to do this.

I am not sure if this is something the community would like? If you like this feature then why not leave a thumb up?

Partial build in development

c4builder seems to be building images for all of them for every build even when there are no changes. It would be great if we can only build images where there are changes.

same thing with -watch as well.

Feature: Support openapi static html page generation using swagger UI

This tool is awesome to prepare and present Design Artifacts in various forms like C4, Sequence diagrams, draw.io wireframes, json files

support openapi static html page generation using swagger UI when specs are available as one of the file

example as described here: swagger-api/swagger-ui#7709

Another option is to convert open API into markdown file using https://github.com/theBenForce/openapi-markdown

Open diagrams in a new tab

Hi! Thank you for this amazing project !

Is there a way to create a link for generated diagrams when using local render ? We cant zoom in on diagrams, so it would be cool if we had link targeting "_ blank".

What do You think ?

Edit:
I saw docsfy has a plugin to zoom in: https://docsify.js.org/#/plugins?id=zoom-image
I created a PR includind this ref.

Fails to install on ubuntu (via docker/node)

I tried installing on my local ubuntu machine and when that didn't work (thought it was my version of node/npm) I tried installing in a docker container:

$ docker pull node:16
$ cat c4builder.Dockerfile
FROM node:16
RUN npm i -g c4builder
$ docker build -t c4builder - < c4builder.Dockerfile

This fails:

npm WARN deprecated [email protected]: This module has moved and is now available at @hapi/hoek. Please update your dependencies as this version is no longer maintained an may contain bugs and security issues.
npm WARN deprecated [email protected]: This module has moved and is now available at @hapi/topo. Please update your dependencies as this version is no longer maintained an may contain bugs and security issues.
npm WARN deprecated [email protected]: This module has moved and is now available at @hapi/joi. Please update your dependencies as this version is no longer maintained an may contain bugs and security issues.
npm ERR! code 1
npm ERR! path /usr/local/lib/node_modules/c4builder/node_modules/node-plantuml
npm ERR! command failed
npm ERR! command sh -c node scripts/get-vizjs.js
npm ERR! node:events:498
npm ERR!       throw er; // Unhandled 'error' event
npm ERR!       ^
npm ERR! 
npm ERR! Error: spawn java ENOENT
npm ERR!     at Process.ChildProcess._handle.onexit (node:internal/child_process:283:19)
npm ERR!     at onErrorNT (node:internal/child_process:478:16)
npm ERR!     at processTicksAndRejections (node:internal/process/task_queues:83:21)
npm ERR! Emitted 'error' event on ChildProcess instance at:
npm ERR!     at Process.ChildProcess._handle.onexit (node:internal/child_process:289:12)
npm ERR!     at onErrorNT (node:internal/child_process:478:16)
npm ERR!     at processTicksAndRejections (node:internal/process/task_queues:83:21) {
npm ERR!   errno: -2,
npm ERR!   code: 'ENOENT',
npm ERR!   syscall: 'spawn java',
npm ERR!   path: 'java',
npm ERR!   spawnargs: [
npm ERR!     '-Dplantuml.include.path=/usr/local/lib/node_modules/c4builder/node_modules/node-plantuml',
npm ERR!     '-Djava.awt.headless=true',
npm ERR!     '-jar',
npm ERR!     '/usr/local/lib/node_modules/c4builder/node_modules/node-plantuml/vendor/plantuml.jar',
npm ERR!     '-testdot'
npm ERR!   ]
npm ERR! }

npm ERR! A complete log of this run can be found in:
npm ERR!     /root/.npm/_logs/2022-02-28T22_11_43_780Z-debug-0.log
The command '/bin/sh -c npm i -g c4builder' returned a non-zero code: 1

I get the same error using node:alpine or node:17 as the FROM

Relative paths for navigation links.

It seems that when the output is multiple markdown files the navigation link targets are preceded by '/' which when viewed on GitHub links relative to the project root and causes problems when the c4builder project is not located at the repository's root. I think it is reasonable to expect the documentation to be in a directory not at root.

Outdated PlantUML version or broken C4-PlantUML?

I've noticed that on some C4-Build-based projects, the generated diagrams end up being along the lines of
(cf. https://ac-architecture.netlify.app/#/) and even trying to change the config to have the generateLocalImages/embedDiagram``and such set differently as well as using https://raw.githubusercontent.com/adrianvlupu/C4-PlantUML/latest/C4_Context.puml` over https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml lead to failed images (which doesn't happen locally when using the PlantUML VSC extension).

Error create new project

After install, i create new project

c4builder new

And i have this message:

_ _ _ _ _ _ ___| || | | |__ _ _(_) | __| | ___ _ __ / __| || |_| '_ \| | | | | |/ _ |/ _ \ '|
| (|__ | |) | || | | | (| | / |
_| || |./ _,|||_,|_|_|

Blow up your software documentation writing skills

This will create a new folder with the name of the project
? Project Name (node:42774) ExperimentalWarning: The fs.promises API is experimental
`

$ node -v
v10.15.1

c4builder on centos 7

Hi,
Does c4builder is supported on centos server without GUI? If so what is the installation process. Thanks in advance.

c4builder watch

A watch option with the site command would be convenient, to update the site upon changes, without having to stop the server, rebuild, and start again.

I'd like to use c4Builder on a non-windows machine but CLRF are causing issues

Would you consider doing something like this: https://www.edwardthomson.com/blog/git_for_windows_line_endings.html

to support other platforms that want to use this plugin?

Provide option to include PlantUML diagrams at arbitrary positions in doc

At the moment the user is forced to either have all PlantUML images at the very top of a page, or at the very bottom (option diagramsOnTop).

But what if I want to be able to freely distribute the diagrams on the page? E.g. what if I want to have an introduction headline and paragraph, followed by diagram number 1, then some more text, then diagram number 2, etc.

Since I can simply include images myself using the syntax ![diagram](diagram.svg) the easiest solution would probably to have a CLI argument that disables the automatic inclusion of the converted puml files.

Diagrams at arbitrary positions not working for more than one file

When there is more than one ![name](name.puml) in a .md file, build replacing all the file with the first one.

// test.md file

![name1](name1.puml) 
![name2](name2.puml) 

after running build all .puml references are replace with first .svg file,

//afterbuild.md file

![diagram](name1.svg)
![diagram](name1.svg)

expected

//afterbuild.md file

![diagram](name1.svg)
![diagram](name2.svg)

Issue with parsing plantUml files

When i generate my .puml files from structurizr java-api I have got as example following imports on top of the file:

!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4.puml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

It will result in following error:

On the other hand if I will replace those imports manually to be:

!include https://raw.githubusercontent.com/adrianvlupu/C4-PlantUML/latest/C4_Container.puml

Everything generates correctly. Is it possible @adrianvlupu your fork of C4-PlantUML is not up to date?

Cannot install without Java being installed

Recently when trying to install this I ran into an issue where I was unable to install. In the end, the culprit was that I needed to have Java installed and added to PATH. This is because one of the dependent libraries, node-plantuml requires java as a part of it's installation.

Could this be added to the list of dependencies or called out somewhere in the getting started to make it easier for people who are doing a fresh install? Or perhaps I missed something and there is a way to install without install Java. Thanks!

npm install issues

Following the readme guidelines trying to install c4builder via
npm i -g install c4builder
I am running into issue with zlib, has anyone else encountered this on mac?

Error:
npm timing command:i Completed in 72965ms
npm ERR! code 127
npm ERR! path /usr/local/Cellar/nvm/0.37.2/versions/node/v17.4.0/lib/node_modules/c4builder/node_modules/zlib
npm ERR! command failed
npm ERR! command sh -c node-waf clean || true; node-waf configure build
npm ERR! sh: node-waf: command not found
npm ERR! sh: node-waf: command not found
npm timing npm Completed in 73370ms

Support add some hooks before/after/in when build src to docs

Is it possible to add some hooks before and after the build function, as well as before and after converting PUML to PNG, to achieve some effects using additional script processing?
For example, my current project scans all generated markdown files after build is complete, and then

```python @execute
import Demo
text=Demo.SOME_KEY
```
```python @execute
def outout(s:io.StringIO()):
    io.append("test")
```

The content in the API description is output according to the Python script I wrote. If this is used to automatically generate and export some APIs and descriptive text.

In addition, before converting PUML, we can write a script to replace placeholders like '$ABC' to automatically generate some PUML content to prevent a certain degree of document corruption.

At present, my approach is to simply rewrite build.js to achieve my goal, but I think it can be more modular

const {build} = require('c4builder/build')
const {execSync} = require('child_process')
const {existsSync} = require('fs')
const extraBuild = async (options, conf) => {
    await build(options, conf)
    const venv = '../../venv/bin/python'
    const python = existsSync(venv) ? venv : 'python'
    console.log('process markdown python start');
    execSync(`${python} ./scripts/process_md_python.py`, (error, stdout, stderr) => {
        if (error) {
            console.error('execute python error', error)
        }
        if (stdout) {
            console.log(stdout)
        }
        if (stderr) {
            console.error(stderr)
        }
    })
    console.log('process markdown python finish');

}
module.exports = {build: extraBuild}

import glob
import io

import sys

sys.path.append("../../src")
sys.path.append("../")

for file in glob.glob('./docs/**/*.md', recursive=True):
    f = open(file)
    content = f.read()
    find_exec = True
    while find_exec:
        namespace = {}
        word = "```python @execute"
        start = content.find(word)
        if start > 0:
            end = content.find("```", start + len(word))
            script = content[(start + len(word)):end]

            try:
                exec(script, namespace)
                if namespace.get('output') is not None:
                    s = io.StringIO()
                    namespace['output'](s)
                    content = content[:start] + s.getvalue() + content[(end + len("```")):]
                elif namespace.get('pre_text') is not None:
                    pre_text = namespace['pre_text']
                    content = (content[:start] + "```\n" + str(pre_text).replace('```', "").strip() + "\n```" +
                               content[(end + len("```")):])
                elif namespace.get('text') is not None:
                    text = namespace['text']
                    content = content[:start] + text + content[(end + len("```")):]
            except Exception as e:
                print("execute script failed:")
                print(script)
                print(e.with_traceback(None))
        else:
            find_exec = False
    f.close()
    f = open(file, 'w')
    f.write(content)
    f.close()

Allow configuration of the base URL for PlantUML Server

I would like to be able to have the speed of rapid page updates without the dependency on an outside server. It would be nice if that (like the VS Code extension), you could configure the plantUmlServerUrl to use a per-project configured value instead of the default plantuml.com host.

Overview diagram is not displayed on new project

I need to create a C4 diagram models using a personal plantuml server. In this GitHub repository I am trying to get it to work.
I create a docker container for the plantuml server(this is a requirement for my use case), I modified the container to serve also as static files the C4 plantuml core files.

Once the site is generated, the only image that is with error is the first image(context.svg), the one in the Overview section.

I am using by default C4 model example when the project is created initially, my only modification here is to have a local plantuml server and consume core C4 files locally as static files.

This is the preview of the generated file context.svg:

But, if I delete the selected code in the generated file context.svg:

then the image is shown correctly:

So, I need to understand why this is happening, thanks in advance for your help

Provide ability to view diagram caption

It is possible to put multiple diagram in one page.
But hard to explain in the markdown which diagram to tell.

Can we do it?

thank you..

GitHub Action

I've created a GitHub Action for running C4 Builder in CI and generating a documentation website/PDF.

https://github.com/clippings/c4builder-action

I thought I'd share it here in case you might want to link to it from the docs or suggest any improvements.

Cheers!

PDF generation failure from [email protected]

Using [email protected] causes c4builder to hang forever because it fails to close chromium.

This should be verifiable by enabling PDF generation and then running the Dockerfile with it.

I install specifically with [email protected] and all is well.

how to customize sidebar to searchable and foldable?

Is there are any ways to customize the side navbar so it can be searchable and foldable??

Update plantuml jar to the latest version

PUML json file to image conversion is failing in some cases with error message "your data doesn't sound like json data"
probably due to old plantuml jar version. Where as its working okay using vscode plugin and on plantuml site.

Use top-level README file

Repositories typically have a top-level README file that explains what the project is about and how to get started using it. I think it would be helpful to re-use that file when generating the documentation using c4builder:

/README.md       # for website generation, use this as the start page (and assume it has a link to e.g. `doc/all-in-one.md`); for pdf, use this as the intro section
/src/context.md  # this is the "architecture overview" linked to in the top-level readme

Are there already ways to achieve this or any thoughts on alternative approaches? If this sounds like a good idea I could also work on a PR for this.

Using `"generateLocalImages": true` fails without error when server URL is bad

I encountered this when trying out the C4Builder-Demo. Since I was trying out something new, I was expecting problems and wasn't too thrown off, but we're setting up this to be used by all developers on our projects, an error message would be really helpful.

Steps to reproduce

1. Install c4builder
2. Clone C4Builder-Demo && cd C4Builder-Demo
3. Copy pdf.css as per adrianvlupu/C4Builder-Demo#1
4. Make sure .c4builder has "plantumlServerUrl": "https://www.plantuml.com/plantuml",, using https instead of the supported http
5. rm -rf docs && c4builder

Expected result

docs/context.png should be a valid PNG.

Actual result

docs/context.png is 0 bytes, and there is no error message. This is the output from running:

$ rm -rf docs && c4builder
       _  _   _           _ _     _           
   ___| || | | |__  _   _(_) | __| | ___ _ __ 
  / __| || |_| '_ \| | | | | |/ _` |/ _ \ '__|
 | (__|__   _| |_) | |_| | | | (_| |  __/ |   
  \___|  |_| |_.__/ \__,_|_|_|\__,_|\___|_|   
                                              
Blow up your software documentation writing skills

building documentation in ./docs
parsed 7 folders
generating images
processed 8/8 images
generating markdown files
processed 7/7 files
generating docsify site
generating complete pdf file
built in 6.945 seconds

to view the generated website run
> c4builder site

Building PlantUML files that contain relative includes results in broken output diagrams

Frequently I want to share common elements between multiple puml files or use my own local function/procedure library. Instead of copying the element into each file I just move that element into a shared file that both puml files include using a relative path.

For example I might have a shared library of puml in _shared.puml and include it in other puml files like this: !include _shared.puml

These relative paths work when using PlantUML preview IDE plugins or the plantuml JAR itself to create output image files.

When I build my project using C4-Builder the output diagrams contain an error message indicating it "cannot include _shared.puml".

If I switch to using an absolute path in the include it works however this is not an ideal solution when the C4 project is being worked on by multiple developers like ours are. We've been using a bit of a hack where the developers set their local project root directory in an environment variable and our puml files use that in their include statements.

The issue seems to be in the node-plantuml library used by C4-Builder. I tried using that library directly and I get the same error in output diagrams.

I was looking at how to fix this in node-plantuml and noticed that project hasn't been actively developed in a couple years but there is a more recent alternative called plantuml-pipe. That library does seem to handle relative includes properly in my testing so far. I haven't tried to change C4-Builder to use that library, I've just been using the library directly.

default template creates "readme.md" and "README.MD"

installing the tool globally, as described in the documentation, and running

c4builder new

...accepting all defaults, creates 2 (!) readme files:

-rw-r--r-- 1 patrick patrick 3266 Jul 19 22:40 readme.md
-rw-r--r-- 1 patrick patrick 3281 Jul 19 22:40 README.MD

The readme files also have different content (see above file size).

Is this the intended behaviour from the template?

I was expecting "README.md" ;-)

OS: Arch linux
c4builder version: 0.2.16
node: v18.4.0

Ping me if I can help with more detailed infos

"Unknown variable $label" error during the generation

Hello, I have an "Unknown variable $label" error during the generation of the diagram. It seems that something is wrong in the C4.plum $getPerson. Please see the attached screen.

How to reproduce:

• run c4builder new
• run c4builder
  Result:
• no diagrams will be generated because of the error: https://ibb.co/Dzg81f0

Including C4-PlantUML locally with relative path

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?

_sidebar.md gets 404 for any file not in the root of the distFolder

Root issue: _sidebar.md gets 404 for any file not in the root of the distFolder

Context:
We are following the source layout example provided in the readme and using the sidebar=true option. After building, the distFolder has a file called _sidebar.md. The top level index.html and Home.md file renders perfectly and work correctly. However for every page in any subfolders of the distFolder, they fail to find _sidebar.md because those subfolder do not have that file. Looking at the web debugger is that it seems to make requests for _sidebar.md once per level in the tree.. but no request from a page below the root of distFolder makes the request for the topmost.

Its possible that what I am hitting is really docsifyjs/docsify#1713 but wanted to call it out here too.

Sidebar is raw Markdown if source and dist are not in same folder

Title says it all really. Here is a specific example:

project/
├── doc/
│   ├── architecture/
│   │    └── model/
│   │        └── context.md
│   └── dist/
└── .c4builder

.c4builder

{
	"rootFolder": "doc/architecture/model",
	"distFolder": "doc/dist"
}

In this case, everything works normally and the dist is generated where it is expected the c4builder site command works as expected. But the sidebar is served raw as a plain-text Markdown without converting to HTML with links. The correct links are in the sidebar in Markdown and they update when adding new content.

I guess it doesn't look for the pages in the proper place and it cannot find the page and therefore the conversion fails.

snyk vulnerablity on [email protected] (only)

Dependency: NPM - [email protected]
      Type:               VULNERABILITY
      Name:               SNYK-JS-MINIMIST-559764
      CVSS Score v3:      8.4
      Severity:           high
      Description Link:   https://snyk.io/vuln/SNYK-JS-MINIMIST-559764

`.c4builder` keeps getting updated with every change making it hard to check in to Git

I thought it would be a good idea to have .c4builder checked into version control. That way, other team members all work with the same configuration.

However, this means the file keeps getting updated with every change because of the checksums that get written to it. So everyone needs to remember to commit this file with every change in a different image.

Also checksums seem to vary between operating systems (to be confirmed). I have one anecdotal evidence of my colleague's Windows machine generating a different checksum compared to my Mac.

Can we move the checksums to a separate file that can be safely .gitignored and keep the .c4builder file easy to maintain in version control?

The c4-plantuml files in the adrianvlupu cause an error

The template refers to https://raw.githubusercontent.com/adrianvlupu/C4-PlantUML/latest/C4_Deployment.puml

When I use c4builder new and don't change anything I see this error:

With the c4-plantuml files from https://github.com/RicardoNiepel/C4-PlantUML it works (on both master and release-1-0 branches).