OrchidDiagrams documentation page has some missing information

[gciatto]

The OrchidDiagrams page does not properly shows how to import UML diagrams into an Orchid page.

I was only able to use the OrchidDiagrams plugin after reading this readme of yours.

However, the information therein reported in not sufficient to properly visualize diagrams. In fact, the readme suggests that PlantUML source code should either be written in line, e.g. through

<!-- md file -->
{% filter compileAs('md') %}
<plant uml code here>
{% endfilter %}

or imported from a file, e.g. through

<!-- md file -->
{{ load('diagram.uml') | raw }}

However no method worked for me. (Yes, I properly installed graphviz in my system).

After some try-and-error, I was finally able to import a diagram by writing the PlantUML code inline, as follows:

{% filter compileAs('uml') %}     <!-- notice `uml` instead of `md` -->
<plant uml code here>
{% endfilter %}

So, I suppose that either the implementation or the documentation of the OrchidDiagrams plugin are wrong.

Furthemore, I failed in importing a PlantUML file in any way. Of course I prefer to import file instead of in-line writing PlantUML code. What can I do?

[cjbrooks12]

The plugin specifically adds support for .uml and .puml file extensions, which is recognized as PlantUML syntax and converted using PlantUML as described in the compilers docs page.

When including the content inline, the {% filter compileAs() %} block processes its contents according to the file extension given. So when the block is {% filter compileAs('md') %} it compiles it as if it were Markdown. When it is {% filter compileAs('uml') %}, it treats it as a PlantUML diagram.

For using the load() function to import a diagram by file, it should be an absolute path to a file in your site resources (or relative to your config.yml file). See example directory structure below for more clarification:

. / (resources root)
├── homepage.md
├── config.yml
├── diagram.uml <-- {{ load('diagram.uml') | raw }} loads and processes this file as PlantUML
└── assets/
    ├── css/
    ├── js/
    ├── diagrams/
    |   └── diagram2.puml <-- {{ load('assets/diagrams/diagram2.puml') | raw }} loads and processes this file as PlantUML
    └── media/

Sorry for the README file not being so clear. It actually has each diagram in there twice, with one filter compileAs() block to show the syntax, and another compiling it as UML to show the rendered diagram. I will update it to be more clear, thank you for the feedback!

[cjbrooks12]

I realized the Pebble markup in the README that was intended as documentation, was actually being precompiled instead. This has been updated in the latest docs

https://orchid.run/plugins/orchiddiagrams