Skip to content

Editing This Guide

This guide uses MkDocs + Material for MkDocs ⧉. The markdown version is Python-Markdown. This page ⧉ contains the reference for the material theme. Install extra MkDocs plugins in build.gradle + mkdocs.yml.

If you are using IntelliJ for editing, it is recommended to install the plugin Grazie Professional ⧉ for spell-checking.

Editing

  • The first header should be #.
  • Inserted images with Markdown, not HTML: ![description](url){width="600px"}. Set the with to 600px or 300px, depending on how big or small the image is
  • footnotes syntax ⧉
  • The target=_blank attribute and an icon for external links get automatically added to links.

The following symbols must be escaped:

  • $ is $ because it collides with inline Latex blocks.

Trees can be created with the terminal command tree. It supports the -I parameter for excluding folders.

Extensions

Besides the Material extensions, the project used the following Pymdown ⧉ extensions:

Macros

The plugin mkdocs-macros-plugin ⧉ is activated. You can add variables to the extra section of mkdocs.yml (example: mps_latest) and use the available macros:

  • contribution_by(GitHub_username)
  • question_by(GitHub_username)
  • answer_by(GitHub_username)
  • mps_url(identifier)
  • image_popup()
  • iets3()
  • mbeddr()
  • mbeddr_platform()
  • mps_extensions()
  • mps

Look through main.py to see how they are implemented.

The identifier can start with one of the following special identifiers:

The special identifiers get translated to the corresponding package names. Only the last part of the identifier has to be the correct name. The identifier can reference classes, interfaces, concepts, and interface declarations in Base Language, MPS Extensions ⧉, mbeddr, and iets3. The rest of the identifier only helps to find the correct node and doesn't have to be exact.

Example: @mps.ClassConcept will find jetbrains.mps.baseLanguage.structure.ClassConcept. When the wrong node is selected, enter more parts of the full qualified name of the node.

Diagrams

Kroki enables support for diagrams (examples ⧉). It supports the following diagrams:

They can be embedded by creating a code block and the text kroki-[diagramtype].

The following sections contain ideas for diagrams.

blockdiag¶ ⧉

Diagram 1

Kroki

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
blockdiag {
orientation = portrait

    R -> A
    R -> B
       B -> C
            C -> E
       B -> D
            D -> F
                 F -> E
            D -> G
       A <- C    
       B -> D

}

Diagram 2

Kroki

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
blockdiag {   
    default_node_color = 'yellow' 

    if [shape="roundedbox", color='white']
    condition [numbered = 1, shape="roundedbox", description="the condition"]
    true_block [numbered = 1, shape="roundedbox"]
    false_block [numbered = 0-1, shape="roundedbox"]

    if -> condition
    if -> true_block
    if -> false_block
}

SeqDiag¶ ⧉

Kroki

1
2
3
4
5
6
7
seqdiag {
    MPS -> Clipboard [label = "Copy Node Reference as URL"]
    Clipboard -> Browser [label = "Paste URL"]
    http_server [label="MPS HTTP Server"]
    Browser -> http_server [label = "Send request"]
    http_server -> MPS [label = "Open Node"]
}

ActDiag¶ ⧉

Kroki

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
actdiag {
  createConcept -> createEditor -> createNodes

  lane language {
    label = "Language"
    createConcept [label = "Create concept"]
    createEditor [label = "Create editor"]
  }

  lane solution {
    label ="Solution"
    createNodes [label = "Create nodes"]
  }
}

Graphviz¶ ⧉

Kroki

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
digraph finite_state_machine {
    rankdir=LR;
        planning -> analysis
        analysis -> design
        design -> implementation
    ti [label="testing & integration"]
        implementation -> ti
        ti -> maintenance
        maintenance -> planning
}

Ditaa

Kroki

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
      +--------+
      |        |
      |  User  |
      |        |
      +--------+
          ^
  request |
          v
  +-------------+
  |             |
  |    Kroki    |
  |             |---+
  +-------------+   |
       ^  ^         | inflate
       |  |         |
       v  +---------+
  +-------------+
  |             |
  |    Ditaa    |
  |             |----+
  +-------------+    |
             ^       | process
             |       |
             +-------+

mermaid.js¶ ⧉

Kroki

1
2
3
4
5
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

nomnoml¶ ⧉

Kroki

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
[Pirate|eyeCount: Int|raid();pillage()|
  [beard]--[parrot]
  [beard]-:>[foul mouth]
]

[<table>mischief | bawl | sing || yell | drink]

[<abstract>Marauder]<:--[Pirate]
[Pirate]- 0..7[mischief]
[jollyness]->[Pirate]
[jollyness]->[rum]
[jollyness]->[singing]
[Pirate]-> *[rum|tastiness: Int|swig()]
[Pirate]->[singing]
[singing]<->[rum]

[<start>st]->[<state>plunder]
[plunder]->[<choice>more loot]
[more loot]->[st]
[more loot] no ->[<end>e]

[<actor>Sailor] - [<usecase>shiver me;timbers]

plantUML¶ ⧉

Diagram 1

Kroki

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
@startuml
left to right direction
skinparam packageStyle rectangle
skinparam monochrome true
actor customer
actor clerk
rectangle checkout {
  customer -- (checkout)
  (checkout) .> (payment) : include
  (help) .> (checkout) : extends
  (checkout) -- clerk
}
@enduml

Diagram 2

Kroki

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
@startwbs
skinparam monochrome true

* 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
@endwbs

BPMN¶ ⧉

Kroki

``` <?xml version="1.0" encoding="UTF-8"?> OrderReceivedEvent _6-652 _6-674 CalmCustomerTask _6-463 _6-514 _6-565 _6-616 _6-630 _6-630 _6-691 _6-693 _6-691 _6-746 _6-748 _6-748 _6-746 _6-693 _6-632 _6-632 _6-634 _6-634 _6-636 _6-636 _6-125 _6-125 _6-178 _6-178 _6-420 _6-420 _6-430 _6-422 _6-424 _6-422 _6-428 _6-424 _6-426 _6-426 _6-430 _6-428 _6-434 _6-434 _6-436 _6-436

Comments