smileham

JArchi Scripting: Export to Markdown

I discovered and fell in love (a bit) with Markdown whilst working for the University of Sussex. My previous employer (which is now my current employer, long story) used Google Drive/Docs, and the University subscribed to Office 365. I ended up getting particularly frustrated with having to go back and use Microsoft Word, so decided to go back to basics (plus, Markdown feels techy, and I miss being a “proper” techie). Markdown allows you to style and structure a plain text file, it’s a useful tool to write in a simple way, concentrating on the content, not the design. I use Microsoft Visual Code Studio to write/preview Markdown, although other editors are available.

JArchi is the scripting language for Archi, the open source, open implementation of the ArchiMate language. Users can download JArchi by supporting Archi on Patreon. It allows a user to develop JavaScript like scripts to interact with an Archi model.

I had been looking at how I can produce documentation directly from Archi, rather than have to copy and paste and manually write the documentation, and was exploring what I could achieve when combining Markdown, Archi and JArchi.

I have developed a JArchi script to Export to Markdown, and have uploaded this to GitHub Gists.

Currently sitting at version 3.4 (at the time of writing this), this script will:

  • iterate through each element added to a view to build a table of contents,
  • export a PNG,
  • include the content of any “note” elements which don’t have relationships to other elements as an Introduction
  • iterate through each element (again) to:
    • use the name of the element and it’s type as a header
    • build a table of all properties on the element,
    • build a table of all relationships on the element, their types and hyperlinks to their related elements (as well as name and documentation on the links),
    • include the element’s documentation,
    • include any related “note” elements as quotes and then
    • iterate through any nested elements.
  • prompt the user to save the files in a location of their choosing.

It’s probably (definitely) not the most efficient code out there, but it does the job! Hopefully others may find it useful.

Example Output

Export to Markdown[^1]

Introduction

Export to Markdown

Export to Markdown: JArchi Script Example

Export to Markdown.ajs <<Script>> (Artifact)

Relationships

From Relationship To Name Description
Export to Markdown.ajs <<Script>> Realization Relationship [archi] Export to Markdown (Application Function)

C:\Users\steve\AppData\Roaming\Archi4\scripts\Import-Export\Export to Markdown.ajs

Can be downloaded from Github Gist:

[archi] jArchi Plugin (Application Function)

Properties

Website Licence
https://www.archimatetool.com/blog/2018/07/02/jarchi/ Open Source (HUMANS)

Relationships

From Relationship To Name Description
[archi] jArchi Plugin Composition Relationship [archi] Export to Markdown (Application Function)
[archi] jArchi Plugin Influence Relationship Support Archi on Patreon (Requirement)

jArchi is a JavaScript-based scripting plug-in built on the Nashorn engine. This means that the end-user can write code, or simple scripts, using JavaScript, and this is then translated into the underlying Java code that drives Archi.

jArchi Plugin <<Software>> (Artifact)

Relationships

From Relationship To Name Description
jArchi Plugin <<Software>> Realization Relationship [archi] jArchi Plugin (Application Function)

C:\Program Files\Archi4\plugins\com.archimatetool.script.commandline_0.4.3.201902121146.jar C:\Program Files\Archi4\plugins\com.archimatetool.script.premium_0.4.1.201902121146.jar C:\Program Files\Archi4\plugins\com.archimatetool.script_0.4.3.201902121146.jar

[archi] Export to Markdown (Application Function)

Properties

Website Licence
https://gist.github.com/smileham/578bbbb88dc0ed5a1403f3b98711ec25 Open Source

Relationships

From Relationship To Name Description
[archi] Export to Markdown Access Relationship Export to Markdown.md <<Markdown>> (Artifact)
[archi] Export to Markdown Access Relationship Export to Markdown.png <<Image>> (Artifact)
[archi] Export to Markdown Influence Relationship Automatic documentation generation (Goal)

Microsoft VSCode (Application Component)

Properties

Website Licence
https://code.visualstudio.com/ Open Source (MIT)

Relationships

From Relationship To Name Description
Microsoft VSCode Access Relationship Export to Markdown.md <<Markdown>> (Artifact)
Microsoft VSCode Access Relationship Export to Markdown.png <<Image>> (Artifact)

Visual Studio Code is a streamlined code editor with support for development operations like debugging, task running and version control. It aims to provide just the tools a developer needs for a quick code-build-debug cycle and leaves more complex workflows to fuller featured IDEs.

MS VSCode <<Software>> (Artifact)

Relationships

From Relationship To Name Description
MS VSCode <<Software>> Realization Relationship Microsoft VSCode (Application Component)

C:\Program Files\Microsoft VS Code

Automatic documentation generation (Goal)

Support Archi on Patreon (Requirement)

Only supporters of ArchiTool on Patreon can access the binary download of the jArchi plugin (as well as other exclusive content)

Documentation <<Folder>> (Artifact)

Relationships

From Relationship To Name Description
Documentation <<Folder>> Composition Relationship Export to Markdown.png <<Image>> (Artifact)
Documentation <<Folder>> Composition Relationship Export to Markdown.md <<Markdown>> (Artifact)

Local folder to store EA documentation.

Export to Markdown.md <<Markdown>> (Artifact)

Markdown formatted documentation of the Export to Markdown Archi view.

Export to Markdown.png <<Image>> (Artifact)

PNG format image of Export to Markdown Archi view.

Core Archi (Diagram Model Group)

Develop Enterprise Architecture Model (Business Process)

[archi] Archi 4.3.3 (Application Component)

Properties

Website Licence
https://www.archimatetool.com/ Open Source (MIT)

Relationships

From Relationship To Name Description
[archi] Archi 4.3.3 Assignment Relationship [archi] jArchi Plugin (Application Function) Plugin
[archi] Archi 4.3.3 Serving Relationship Develop Enterprise Architecture Model (Business Process)

Archi fulfils the needs of most Enterprise Architects and associated stakeholders, and has been designed to elegantly provide the main features required for ArchiMate modelling and is used globally by banks, insurance companies, industry, EA consultants, training organisations, universities, and students. It is the world’s most popular ArchiMate modelling tool and is downloaded between two and three thousand times every month.

Desktop Computer (Device)

Relationships

From Relationship To Name Description
Desktop Computer Assignment Relationship Archi 4.3.3 <<Software>> (Artifact)
Desktop Computer Assignment Relationship jArchi Plugin <<Software>> (Artifact)
Desktop Computer Assignment Relationship Export to Markdown.ajs <<Script>> (Artifact)
Desktop Computer Assignment Relationship MS VSCode <<Software>> (Artifact)
Desktop Computer Assignment Relationship Documentation <<Folder>> (Artifact)

A device is a physical IT resource upon which system software and artifacts may be stored or deployed for execution. — ArchiMate 3

Smileham: The usage of ArchiMate and Archi models should be derived from the questions that you want to answer. When I first began modelling, I wanted to seperate the logical server (node) from the physical or virtual server (device) on which they were executing. This seperation allows an architect to query the model to find where all particular makes/models/configurations of physical devices are used in the architecture.

Archi 4.3.3 <<Software>> (Artifact)

Relationships

From Relationship To Name Description
Archi 4.3.3 <<Software>> Realization Relationship [archi] Archi 4.3.3 (Application Component)

C:\Program Files\Archi4

[^1]: Generated: Sat Mar 09 2019 19:56:49 GMT+0000 (GMT)

Code

/*
* Export View to Markdown
*
* Requires jArchi – https://www.archimatetool.com/blog/2018/07/02/jarchi/
*
* Markdown – https://www.markdownguide.org/
*
* Version 2: Updated to support Diagram Groups
* Version 2.1: Add check for Selected View
* Version 2.2: Change to regex, added date of export
* Version 2.3: Include notes in documentation
* Version 3: Updated to include Relationships
* Version 3.1: Include name and description
* Version 3.2: Support repeated elements
* Version 3.3: Fix for relationships table
* Version 3.4: Fix for connected notes,
* Quotes in documenation,
* Embed view (experimental)
* Version 3.5: Added support for jArchi 4.4 (additional attributes)
*
* (c) 2018 Steven Mileham
*
*/
var debug = true;
var embed = false;
var tocMap = [];
var bodyMap = [];
function convertToText(type) {
var theString = type.replaceAll("-"," ").split(" ");
var theResult = "";
for (var i=0; i<theString.length; i++){
theResult+= theString[i][0].toUpperCase()+theString[i].substring(1,theString[i].length) + " ";
}
return theResult.trim();
}
function escapeMD(theString){
var newString = theString.replaceAll("<","&lt;").replaceAll("\n>","\n~QUOTE~");
return newString.substring(0,1)+newString.substring(1).replaceAll(">","&gt;").replaceAll("~QUOTE~",">");
}
function generateLink(theString) {
var regex = /[\[\]\(\)\#\\\/\"]/gi;
return "#"+theString.toLowerCase().replace(regex,"")
.replaceAll(" ","-")
.replaceAll("\<","lt")
.replaceAll("\>","gt");
}
function toc(d, element){
$(element).children().not("relationship").each(function(e) {
if (e.name) {
headerDepth="";
for (var i=0; i<d; i++){
headerDepth+=" ";
}
var theHash = generateLink(e.name +" ("+ convertToText(e.type)+")");
if (tocMap[theHash]==null) {
tocMap[theHash]=1;
}
else {
tocMap[theHash]+=1;
}
var linkNum="";
if (tocMap[theHash]>1) {
linkNum = "-"+tocMap[theHash];
}
theTOC+="\n"+headerDepth +"* ["+ escapeMD(e.name) +" ("+ convertToText(e.type) +")"+linkNum.replace("-"," ")+"]("+theHash+linkNum+")";
if ($(e).children().not("relationship").length>0) {
d++;
toc(d, e);
d–;
}
}
});
}
function propertiesTable(element) {
var theProperties = element.prop();
var theHeader="";
var theLine="";
var theBody="";
for (var i=0; i<theProperties.length;i++){
theHeader+="|"+theProperties[i];
theLine+="|—";
theBody+="|"+element.prop(theProperties[i]);
}
return "**Properties**\n"+theHeader+"|\n"+theLine+"|\n"+theBody+"|\n";
}
function documentRelationships(element) {
var theHeader = "|From|Relationship|To|Name|Description|"
var theLine = "|—|—|—|—|—|";
var theBody = "";
$(element).outRels().each(function(r){
var q= r.concept;
if (r.type!="diagram-model-connection") {
theBody+="|"+r.source.name;
theBody+="|"+convertToText(r.type);
if (q.accessType) {
theBody+=" ("+q.accessType+")";
}
if (q.influenceStrength) {
theBody+=" ("+q.influenceStrength+")";
}
theBody+="|["+ escapeMD(r.target.name) +" ("+ convertToText(r.target.type) +")]("+generateLink(r.target.name +" ("+ convertToText(r.target.type)+")")+")";
theBody+="|"+r.name;
theBody+="|"+r.documentation+"|\n";
}
});
return "**Relationships**\n"+theHeader+"\n"+theLine+"\n"+theBody;
}
function nestedDocumentation(d, element) {
$(element).children().not("relationship").each(function(e) {
if (e.name) {
var headerDepth ="##";
for (var i=0; i<d; i++) {
headerDepth+="#";
}
var theHash = generateLink(e.name +" ("+ convertToText(e.type)+")");
if (bodyMap[theHash]==null) {
bodyMap[theHash]=1;
}
else {
bodyMap[theHash]+=1;
}
var linkNum="";
if (bodyMap[theHash]>1) {
linkNum = " "+bodyMap[theHash];
}
theDocument+="\n"+headerDepth +" "+ escapeMD(e.name) +" ("+ convertToText(e.type) +")"+linkNum+"\n";
e.prop().length > 0 ? theDocument+="\n"+escapeMD(propertiesTable(e)):true;
$(e).outRels().length>0?theDocument+="\n"+escapeMD(documentRelationships(e)):true;
e.documentation ? theDocument+="\n"+escapeMD(e.documentation)+"\n":true;
$(e).rels().ends().each(function(r) {
if (r.text) {
theDocument+="\n> "+escapeMD(r.text).replaceAll("\n","\n> ")+"\n";
}
});
debug? console.log(e.name+":"+$(e).children().not("relationship")+":"+e):true;
if ($(e).children().length>0) {
d++;
nestedDocumentation(d, e);
d–;
}
}
});
}
console.show();
console.clear();
console.log("Export to Markdown");
var theDocument = "";
var theTOC = "* [Introduction](#introduction)";
var theView = $(selection).filter("archimate-diagram-model").first();
if (theView) {
theDocument+="# "+theView.name+"[^1]\n";
toc(0,theView);
theDocument+="\n"+theTOC+"\n";
theDocument+="\n## Introduction\n";
if (embed==true){
var bytes = $.model.renderViewAsBase64(theView, "PNG", {scale: 2, margin: 10});
theDocument+="\n!["+theView.name+"](data:image/png;base64,"+bytes+")\n";
}
else {theDocument+="\n!["+theView.name+"][embedView]\n";}
theView.documentation!=""?theDocument+="\n"+theView.documentation+"\n":true;
// Notes with no relationships
$(selection).find().not("element").not("relationship").each(function(c){
if (c.text) {
if ($(c).rels().length==0) {
theDocument+="\n"+escapeMD(c.text).replaceAll("\n","\n> ")+"\n";
}
};
})
nestedDocumentation(0, theView);
var defaultFileName = theView.name ? model.name + "-" + theView.name + ".md" : "Exported View.md"; // Default file name
var exportFile = window.promptSaveFile({ title: "Export to Markdown", filterExtensions: [ "*.md" ], fileName: defaultFileName } );
if(exportFile != null) {
if (!embed) {
imageURL = exportFile.substring(0,exportFile.length-3).replaceAll(" ","%20")+".png";
relativeURL = imageURL.split("\\");
var bytes = $.model.renderViewAsBase64(theView, "PNG", {scale: 2, margin: 10});
$.fs.writeFile(exportFile.substring(0,exportFile.length-3) +".png", bytes, "BASE64");
theDocument+="\n[embedView]: "+relativeURL[relativeURL.length-1];
}
theDocument+="\n[^1]: Generated: "+ new Date().toLocaleString()+"\n";
$.fs.writeFile(exportFile, theDocument);
console.log("> Export done");
}
else {
console.log("> Export cancelled");
}
}
else {
console.log("> Please Select a View");
}
view raw Export to Markdown.ajs hosted with ❤ by GitHub

2 comments

Leave a Reply

Fill in your details below or click an icon to log in:

Gravatar
WordPress.com Logo

You are commenting using your WordPress.com account. ( Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. ( Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. ( Log Out /  Change )

Cancel

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.