Sample Family

This site was generated as explained below:

A Drawio diagram of family relationships was created based on images from the Eclipse Sirius BasicFamily Tutorial. The diagram uses free icons from Icons8 to provide visual distinction between architecture elements.
The diagram was mapped the Family model using properties of the diagram elements.
Then the family model was transformed to the HTML Application model and a static web site was generated from that model. Icons were generated from the diagram images of the respective elements.
The web site is deployed by GitHub Pages.

Notes:

A click on a diagram element (family member) navigates to the element page.
Search provides full-text search which also searches for text in diagrams
- Search for a family member name finds it in the diagram on the home page
- Search for ethnicity finds ethnicities on the Paul page
There is a link to the source code on GitHub in the footer.

Mapping
Generation
- Representation element filtering
Markdown documentation

Mapping

Root -> Family

The root of the diagram is mapped to Family with the type property set to Family

This documentation was generated from family.md markdown file with the diagram embedded using drawio fenced block with representations/drawio/diagram expansion token.

Diagram semantic elements are mapped to the root semantic element (Family) using the following feature-map:

container:
  self: 
    members:
      argument-type: Person
      comparator: label

The above mapping means that use the semantic element of this diagram element (root) and add semantic elements of its descendants to the members reference ordering by label. argument-type specifies that only instances of Person shall be added to the members reference. This is not really necessary to specify argument-type in this case because the members reference type is Person.

page-element set to true specifies that the root semantic element shall also be the page’s semantic elements. Because this is the top-level page (not linked from diagram elements), it also becomes the document’s semantic element and as such the contents element of the diagram’s Ecore resource.

Page name “Sample Family” is used to set the name of the family semantic element.

Diagram elements -> Man or Woman

Diagram elements are mapped either to Man or Woman. They have semantic-id property to demonstrate its usage. Another way to provide meaningful semantic ID’s and URL’s is to edit diagram element ID’s.

Connections -> Father or Mother

Connections establish family relationships using feature-map property:

source: father specifies that father feature of the connection source semantic element shall be set to the connection target semantic element.
source: mother specifies that mother feature of the connection source semantic element shall be set to the connection target semantic element.
source: parentsspecifies that the connection target semantic element shall be added to the parents reference of the source semantic element.
target: childrenspecifies that the connection source semantic element shall be added to the children reference of the target semantic element.

Generation

This site was generated with 82 lines of Java code in a JUnit test.

Representation element filtering

Border of Isa is set during the generation with the following code:

@Override
protected void filterRepresentationElement(
		Element representationElement, 
		EObject semanticElement,
		Map<EObject, EObject> registry,
		ProgressMonitor progressMonitor) {
				
	// Demo of representation filtering - adding a black border to Isa
	if (representationElement instanceof org.nasdanika.drawio.ModelElement) {
		org.nasdanika.drawio.ModelElement rme = (org.nasdanika.drawio.ModelElement) representationElement;
		if ("isa".equals(rme.getProperty("semantic-id"))) {
			rme.getStyle().put("imageBorder", "default");
		}
	}
}

Border of Fiona is also set during generation by FamilyRepresentationElementFilter class which is loaded using the Capability framework. This approach allows to decouple representation filtering logic from the generation logic.

Representation filtering may be used to inject information which is not available during diagram creation or dynamic, but is available during generation.

Markdown documentation

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 base-uri.

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, Draw.io, and Mermaid diagrams using fenced blocks. Draw.io diagrams can be edited in a desktop editor or Online editor.

Draw.io

```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 - for the following diagram types:
- Sequence,
- Use Case,
- Class,
- Activity,
- Component,
- State,
- Object,
- Deployment,
- Timing,
- Network.
wireframe - for Wireframe diagrams
gantt - for Gantt diagrams
mindmap - for Mind Maps
wbs - for Work Breakdown Structures

UML

Sequence

Fenced block:

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

Diagram:

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:

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:

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:

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:

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:

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 -> H₂0
Superscript: 2^5^ = 32 -> 2⁵ = 32