Nasdanika Templates
    Drawio Site

Drawio Site

This is a template repository for web sites generated from Drawio diagrams with GitHub Actions and Nasdanika CLI Drawio Command.

Demos

Below is a list of sites created from this template:

Steps

  • On the repository page click “Use this template” button in the top right.
  • Once you create a new repository, go to the Settings > Pages and select “GitHub Actions” as source.
  • Click on the Acitons tab. You should see a failed deployment. Manually trigger Generate HTML Site from a Drawio diagram with Nasdanika CLI action. Once it is successful, open the pages site.
  • Customize the diagram, root action, and page template to your needs as explained below.

The deployment action can be triggered manually from the actions page. It can be useful if your site references external resources.

For example:

  • The diagram file may link to pages in external diagrams (federated diagrams)
  • The diagram file may reference external documentation resources

Deployment process

Diagram file

You may rename diagram.drawio to something more meaningful, e.g.my-system.drawio. Or you may use a pre-existing drawio diagram and delete diagram.drawio. You can also use an external diagram and reference it by URL. If you do rename/replace the diagram, open .github/workflows/site.yml and update line 42 with a new diagram file name.

You can edit the diagram directly on GitHub using Draw.io online editor

Page template

In the page template file you can:

  • Modify the theme on line 3 - choose one of 20+ Bootswatch themes or the default theme. Please note that generated sites look good with light themes, and not so good (in my personal opinion) with dark themes.
  • Highly recommended: remove out-of-the-box Google analytics script at lines 23-33 - replace it with your own or remove the header section (lines 22-33) altogether.
  • Remove line 36 or set fluid to false.
  • Modify navigation panel style at line 38

See Bootstrap Page Load Specification for supported confiuration keys.

Root action

The root action defines:

  • The header (root action1). You may modify the icon and the title.
  • Root navigation actions - lines 6 - 20. Glossary and search are functional, but not perfect - they need TLC, which I don’t have capacity for at the moment. You may use them AS-IS, remove/replace, or improve and create a pull request. Their advantage is that they are standalone - no external dependencies. For public web sites you may consider something like Algolia - they have a free tier and a Vue.js search component, InstantSearch
  • Footer (root navigation) at lines 21+. Out of the box is links to the template repository site - update or remove.

See Action Load Specification for supported configuration keys.

Diagram elements

You can add documentation to diagram elements, title and icon property, customize element ID, and link elements to pages or other elements, including pages and elements in other diagram files.

You can also define action/label prototypes for diagram elements with prototype and proto-ref properties.

Site pages are generated only for elements with documentation, prototypes, or both.

Important: Pages are not generated for diagram elements without labels or title property! It may lead to broken links.

Documentation

You can add inline documentation in documentation property as it is done for Alice.

Documentation is by default treated as Markdown. Use doc-format property to specify documentation format. Out of the box there are 3 formats supported:

  • markdown
  • html
  • text

You can add support for more formats, e.g. Asciidoc using AsciidoctorJ - see “Adding support for documentation format” below.

You may reference an external documentation resources with doc-ref property - this how it is done for the diagram root (click on the diagram canvas and then on “Edit Data” button in the right panel). Documentation reference is a URL resolved relative to the diagram file location.

If you use doc-ref property, the documentation format is inferred from the extension. You may override the inferred value using doc-format property.

Title

By default the element label is used as action text. For elements with long labels it may be desirable to use shorter text. To do so use title property.

Icon

By default element icons are derived from element images where possible. Otherwise a default icon is used. You may use icon property to customize element icon. The icon can be a URL (including data URL) or a CSS style e.g. fas fa-user.

ID

Element ID’s are used to construct element page URL’s. Element ID’s are generated as long random strings. They are editable - double-click on the ID at the top of the data dialog. So, if you’d like to have semantic URL’s - customize the ID’s.

Prototypes

With prototypes you can:

  • Generate complex site pages (actions) with children, navigation, sections, …
  • Reuse action models. For example, generate an action model from one diagram and use it as a prototype for an element of another diagram.

prototype property value shall be a YAML prototype specification. For example:

Action:
    navigation:
      - Action:
          location: about-wendy.html
          icon: fas fa-help
          text: About
          content:
            Interpolator:
              source:
                exec.content.Text: |    
                  This is an example of a page from an action prototype.

proto-ref property value is a URI of the prototype action or label resolved relative to the element base URI. For example bob-prototype.yml#/.

If both properties are specified, prototype takes precedence over proto-ref.

If a diagram element without a prototype definition is linked to a page and the page root has a prototype definition, then that definition is used.

Prototype can also be used to modify top level page location from the default index.html - it is needed if the root action has a link:

Action:
  location: temp://e91c7149-ae29-4fd5-ada8-00a09f704e7d/fc5bbf4a-0f85-4bc3-be3b-fe0d0bc68958/index.html

Role

You can use role property to specify where the diagram element page appears in the page structure. Valid values:

  • anonymous - a page is generated, but not linked from generated navigation elements - it has to be explicitly referenced. This is the default for connections. Diagram links are generated for anonymous elements.
  • child - a page link is generated in the navigation panel under the parent element. This is the default for nodes.
  • navigation - a page link is generated in the parent page navigation bar.
  • section - diagram element is generated as a section of its parent. Diagram link is not generated.

Parent

You can use parent property with values source or target to generate sites from mind maps where page parent/child relationship is defined by connections instead of containment and page links.

Sort key

By default pages are sorted alphabetically by title in the navigation panel. You can use sort-key property to customize sorting order - pages are sorted alphabetically by the key value and then alphabetically by title within the same key. Pages without a sort key are considered greater than pages with a key.

Page and element links

You may link elements to pages and other element using the extended link syntax.

When an element links to a page, the page root2 is logically merged with the linking element and page elements (except elements liking to other elements) become logical children of the linking element.

If an element links to another element, then that element is not considered a logical child of the page/root/page linking element. The link chain is traversed and the diagram element on the generated site is linked to the page of the link target element if that element has a page (i.e. it is documented). Otherwise there is no link.

Multiple top-level pages

A top-level diagram page is a page that is not linked from any diagram element. If there is more than one top-level page, then you may want to add a principal action to the root-action.yml and link pages to the principal action by removing --add-to-root option from the command line in site.xml.

Examples:

site.yml

Change the command at line 42 to:

./nsd drawio ../diagram.drawio html-app -r ../root-action.yml site -r=-1 -F ../page-template.yml ../docs

root-action.yml

Add a child action at the first position. Page actions will be added to this action as children. Example:

Action:
    icon: https://docs.nasdanika.org/images/nasdanika-logo.png
    text: Nasdanika Demos
    location: https://github.com/Nasdanika-Demos
    children:
      - Action:
          location: temp://e91c7149-ae29-4fd5-ada8-00a09f704e7d/fc5bbf4a-0f85-4bc3-be3b-fe0d0bc68958/index.html
          text: Beyond Diagrams Illustrations
          content:
            Interpolator:
              source:
                Markdown:
                  style: true
                  source:
                    exec.content.Resource: README.md
    navigation:
      - Action:
          text: Source
          icon: fab fa-github
          location: https://github.com/Nasdanika-Demos/beyond-diagrams

Icons

Drawio has more than two thousand built-in icons. You can find more icons on the below sites:

  • FlatIcons - 16.8 million icons. Free with attribution, a paid plan is available - no attribution. In-browser editor. PNG and SVG (premium) formats.
  • IconFinder - the world’s largest marketplace for icons, … 6 million icons at your fingertips including free icons. Multiple subscription levels.
  • Icons8 - more than a million icons in 47 styles. Free and subscription. Icons can be edited in-place before downloading.
  • Iconduck - more than 250 000 free open source icons
  • Techicons - SVG and PNG tech icons, sourced from https://github.com/devicons/devicon. 473 icons.
  • Cloud providers:

Markdown

This section demonstrates advanced capabilities of Markdown documentation.

Embedded images

You can embed PNG and JPEG using fenced blocks.

PNG resource

```png-resource
isa.png
```

Resource location is resolved relative to the diagram file location.

JPEG resource

```jpeg-resource
my.jpeg
```

PNG

```png
Base 64 encoded png 
```

JPEG

```jpeg
Base 64 encoded jpeg
```

Embedded diagrams

You can also embed PlantUML, Drawio, and Mermaid diagrams using fenced blocks.

Drawio

```drawio-resource
aws.drawio
```

Resource location is resolved in the same way as for image files as explained above.

PlantUML

PlantUML diagrams can be defined inline or loaded from resources.

Loading from a resource
```uml-resource
sequence.plantuml
```
Inline

The following language specifications (dialects) are supported:

UML

Sequence

Fenced block:

```uml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
```

Diagram:

Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response

Component

Component diagram with links to component pages.

Fenced block:

```uml
package Core {
   component Common [[https://github.com/Nasdanika/core/tree/master/common]]
}

package HTML {
   component HTML as html [[https://github.com/Nasdanika/html/tree/master/html]]
   [html] ..> [Common]
}
```

Diagram:

package Core { component Common [[https://github.com/Nasdanika/core/tree/master/common]] } package HTML { component HTML as html [[https://github.com/Nasdanika/html/tree/master/html]] [html] ..> [Common] }

Wireframe

Fenced block:

```wireframe
{
  Just plain text
  [This is my button]
  ()  Unchecked radio
  (X) Checked radio
  []  Unchecked box
  [X] Checked box
  "Enter text here   "
  ^This is a droplist^
}
```

Diagram:

{ Just plain text [This is my button] () Unchecked radio (X) Checked radio [] Unchecked box [X] Checked box "Enter text here " ^This is a droplist^ }

Gantt

Fenced block:

```gantt
[Prototype design] lasts 15 days and links to [[https://docs.nasdanika.org/index.html]]
[Test prototype] lasts 10 days
-- All example --
[Task 1 (1 day)] lasts 1 day
[T2 (5 days)] lasts 5 days
[T3 (1 week)] lasts 1 week
[T4 (1 week and 4 days)] lasts 1 week and 4 days
[T5 (2 weeks)] lasts 2 weeks
```

Diagram:

[Prototype design] lasts 15 days and links to [[https://docs.nasdanika.org/index.html]] [Test prototype] lasts 10 days -- All example -- [Task 1 (1 day)] lasts 1 day [T2 (5 days)] lasts 5 days [T3 (1 week)] lasts 1 week [T4 (1 week and 4 days)] lasts 1 week and 4 days [T5 (2 weeks)] lasts 2 weeks

Mind Map

Fenced block:

```mindmap
* Debian
** [[https://ubuntu.com/ Ubuntu]]
*** Linux Mint
*** Kubuntu
*** Lubuntu
*** KDE Neon
** LMDE
** SolydXK
** SteamOS
** Raspbian with a very long name
*** <s>Raspmbc</s> => OSMC
*** <s>Raspyfi</s> => Volumio
```

Diagram:

* Debian ** [[https://ubuntu.com/ Ubuntu]] *** Linux Mint *** Kubuntu *** Lubuntu *** KDE Neon ** LMDE ** SolydXK ** SteamOS ** Raspbian with a very long name *** <s>Raspmbc</s> => OSMC *** <s>Raspyfi</s> => Volumio

WBS

WBS elements can have links. This type of diagram can also be used to display organization structure.

```wbs
* [[https://docs.nasdanika.org/index.html Business Process Modelling WBS]]
** Launch the project
*** Complete Stakeholder Research
*** Initial Implementation Plan
** Design phase
*** Model of AsIs Processes Completed
**** Model of AsIs Processes Completed1
**** Model of AsIs Processes Completed2
*** Measure AsIs performance metrics
*** Identify Quick Wins
** Complete innovate phase
```

Fenced block:

Diagram:

* [[https://docs.nasdanika.org/index.html Business Process Modelling WBS]] ** Launch the project *** Complete Stakeholder Research *** Initial Implementation Plan ** Design phase *** Model of AsIs Processes Completed **** Model of AsIs Processes Completed1 **** Model of AsIs Processes Completed2 *** Measure AsIs performance metrics *** Identify Quick Wins ** Complete innovate phase

Mermaid

You can define Mermaid diagrams in mermaid fenced blocks:

flowchart LR
   Alice --> Bob & Chuck --> Deb

results in this diagram:

flowchart LR Alice --> Bob & Chuck --> Deb

Loading from a resource

It is also possible to load a diagram definition from a resource resolved relative to the model resource:

```mermaid-resource
sequence.mermaid
```

Extensions

  • Table of contents - add [TOC] to the document as explained in the documentation. This extension will create a table of contents from markdown headers.
  • Footnotes
  • Strikethrough: ~~strikethrough~~-> strikethrough
  • Subscript: H~2~O -> H20
  • Superscript: 2^5^ = 32 -> 25 = 32

Failing on errors

-r=-1 command line option means “don’t fail on page errors” such as:

  • Blank pages
  • Broken internal links
  • Missing resources

Missing resources are reported on pages using danger alert blocks.

If you want to prevent deployment of a site with page errors, remove the option or set it to the expected number of errors - there might be “known errors” which you are OK to live with.

Upgrading NSD CLI version

When a new version of Nasdanika CLI is released you may update lines 33 and 35 in site.yml to point to the new distribution.

Adding support for a new documentation format

To add a new documentation format:

  • Create a Maven module
  • Create a documentation capability factory class, see MarkdownDocumentationFactory
  • Register it in module-info.java - example
  • Build a custom CLI with the above module as a dependency. See Demo CLI for an example.
  • Build a distribution, deploy to a web location, and update site.yml lines 33 and 35.

Interoperability with Confluence Drawio plugin

If you use Confluence you may keep diagrams on Confluence with diagram-level descriptions and generate detailed element-level documentation sites with Nasdanika CLI. To do so:

  • Create a personal access token
  • On the page which hosts your diagram go to attachments and copy the download link for your diagram file
  • Use curl -H "Authorization: Bearer <Your token>" <download URL> -o diagram.drawio command to download the diagram before generating a documentation site

Note: I tested this approach with on-prem Confluence - it worked fine, but I couldn’t make it work with the Cloud Confluence free plan.

Next steps

This section outlines possible next steps once you have a site generated from a diagram or a set of diagrams.

Executable diagrams

You may make the diagrams executable.

Stories:

Demos:

Semantic mapping

Semantic mapping allows to create Ecore models from data sources such as Drawio diagrams.

The goal of Drawio site generation explained above is to provide a quick simple way to start with generating web sites from Drawio diagrams. It is a form of a lightweight semantic mapping which uses just a few properties.

You can use the approach explained here with executable diagrams and semantic mapping. You can also “upgrade” to semantic mapping if you need more features. For example, geometric sorting.

Resources:

  1. See Action types

    ↩

  2. See Drawio API

    ↩