Asciidoc Includes does not work correctly

[Heiss]

Hey,

i saw #336 and #307 which implements this feature. Now i wanted to reuse my arc42 documentation, written in asciidoc, in your fantastic tool. But my includes breaks, because of "baseDir" Stuff, i think. The corresponding comment is already in your code.

https://github.com/jp7677/structurizr-site-generatr/blob/45efb9b7e15f7d3708ca56bb6baef1f50a3135f6/src/main/kotlin/nl/avisi/structurizr/site/generatr/site/model/ToHtml.kt#L63-67

        // Docs dir needs to be exposed from structurizr using `.baseDir(File("./docs/example/workspace-docs"))`,
        // which is not the case at the moment.
        // Needed for partial include `include::partial.adoc[]`, which structurizr also does not support.
        // see https://docs.asciidoctor.org/asciidoc/latest/directives/include/
        // another option could be https://docs.asciidoctor.org/asciidoctorj/latest/locating-files/#globdirectorywalker-class

The following errors shows up:

....
structurizr-1  | SEVERE: <stdin>: line 55: include file not found: /var/model/src/01_introduction_and_goals.adoc
structurizr-1  | Jul 12, 2024 3:48:05 PM  
structurizr-1  | SEVERE: <stdin>: line 59: include file not found: /var/model/src/02_architecture_constraints.adoc
structurizr-1  | Jul 12, 2024 3:48:05 PM  
structurizr-1  | SEVERE: <stdin>: line 63: include file not found: /var/model/src/03_system_scope_and_context.adoc
structurizr-1  | Jul 12, 2024 3:48:05 PM  
...

and so on. I am using the official template https://arc42.org/download for asciidoc with helptexts. Take a look into that and you have a lot of includes and files which can be placed in the workspace-docs. :) In my case, i copy the stuff into /workspace-docs and the includes are in /workspace-docs/src. In my editor, everything can be rendered without an issue.

As you see in my log excerpt, i am using docker-compose with the following config:

services:
  structurizr:
    image: ghcr.io/avisi-cloud/structurizr-site-generatr
    user: root
    volumes:
      - .:/var/model:ro
    ports:
      - "8667:8080"
    command:
      - "serve"
      - "-w"
      - "workspace.dsl"
      - "--site-dir"
      - "/tmp/serve"

(Maybe there is also something you should handle aswell... A dev-server should not need to write into the same folder to getting things done. It was a little bit odd to me. But got it handled with your --help texts. :) Also your user generatr is not available in my linux setup, so it cannot read some files like pictures. And i think it is totally fine to run as root as long as you do not overwrite any permissions in local setup. Just my 2 cents.)

So. You asked in #307 for consequeneces for missing baseDir in asciidoc implementation... (https://github.com/avisi-cloud/structurizr-site-generatr/pull/307#discussion_r1354273910) I think this is one. I can work around this with a single config.adoc, but it is not as handy as expected. Also the includes are only valid in your generatr environment, so any asciidoc editor (like intellij with asciidoc plugin) cannot resolve the includes anymore, because the baseDir is not equal as long as the baseDir stuff is not fixed, which is a bummer for development, i think. Because baseDir needs to change in regards of the primary file, which gets currently be parsed, it cannot be a single path provided by a new parameter...

So i hope i provided all needed insides to you. And maybe, it is a quick fix for you. :) It would helps alot and would make the transition to your software easier, because it is more likely the official flow of asciidoctor.

So. Thanks for your great software. ❤️

edit: the parameter "--assets-dir assets" is necassary to use assets folder for favicon etc. :) Maybe should be a default value, because it is your example.

edit2: Also source code includes does some weird stuff.

[source]
----
include::https://raw.githubusercontent.com/avisi-cloud/structurizr-site-generatr/main/docs/example/workspace.dsl[lines=5..10]
----

generates link:https://raw.githubusercontent.com/avisi-cloud/structurizr-site-generatr/main/docs/example/workspace.dsl[role=include] which is obviously wrong. Local resolutions are working as expected.

[jenspav]

Thanks for the issue. Looking into the includes, unfortunately we cannot do much at the moment. We are not reading the asciidoc files directly. This is done by the structurizr libraries itself which provides decisions and sections within its own models (see Decision.java and Section.java in https://github.com/structurizr/java/tree/master/structurizr-core/src/main/java/com/structurizr/documentation). So the only info we have at the time of rendering is the file content and the filename, but unfortunately not the location/path of the original asciidoc file, which would be needed to set the baseDirfor each file separately.

the parameter "--assets-dir assets" is necassary to use assets folder for favicon etc. :) Maybe should be a default value, because it is your example.

Which default value would you propose? May be we can also improve our documentation. Do you have an idea how we could make this more obvious?

Also source code includes does some weird stuff.

Would you mind creating a separate issue about this which includes what you expect as a result. We are unfortunately not that familiar with asciidoc.

[Heiss]

Which default value would you propose? May be we can also improve our documentation. Do you have an idea how we could make this more obvious?

--assets-dir assets would my assumption as the default, because it is taken from your example. If you use your command from your README.md, it does not work correctly without the assets-dir parameter, at least at my end. So at least you should mention this in your example cli commands or (better) define it as default and if it is omitted, use the default value. The second one would be my preferred way.

Would you mind creating a separate issue about this which includes what you expect as a result. We are unfortunately not that familiar with asciidoc.

Done at #582

Have a great day.

[jenspav]

Thanks for the issue. Looking into the includes, unfortunately we cannot do much at the moment. We are not reading the asciidoc files directly. This is done by the structurizr libraries itself which provides decisions and sections within its own models (see Decision.java and Section.java in https://github.com/structurizr/java/tree/master/structurizr-core/src/main/java/com/structurizr/documentation). So the only info we have at the time of rendering is the file content and the filename, but unfortunately not the location/path of the original asciidoc file, which would be needed to set the baseDirfor each file separately.

This matches what has been found in https://github.com/avisi-cloud/structurizr-site-generatr/issues/448#issuecomment-1991023675