Docs (mermaid)

It’s important that you document the details of your project. There are two primary tools that we use: Markdown, a plain-text markup language, and Mermaid, a text-based diagramming language that works with markdown.

Markdown and Mermaid are both supported by GitLab, IntelliJ with the markdown plugin and other development tools like VS Code e.g., you can produce a Markdown document containing Mermaid diagams, and those tools can display it correctly.

Markdown

Markdown was originally designed as a quick way of authoring web pages and was meant to be transpiled to HTML. Since its debut in 2004, it’s been quickly adopted as a standard for technical documentation. It’s far from a perfect specification, but it’s useful and human-readable.

Markdown uses simple text annotation in a text document to indicate the structure. e.g., here’s the Markdown from the beginning of this section: The ## symbols denote a heading, and the * indicate bullet points. The []() syntax is for an external link. See the Markdown Guide for syntax details.

## Example: Getting Started

We will use two fundamental technologies to write our documentation:
* [Markdown](https://www.markdownguide.org): a plain-text markup language, and 
* [Mermaid](https://mermaid.js.org/intro/): a text-based diagramming language.

Mermaid

Mermaid is a text format for producing diagrams. It’s declarative: you describe the componets of the diagram, and the mermaid engine handles layout. Mermaid diagrams are supported by your toolchain, and you can embed diagram syntax directly in a Markdown document.

Mermaid supports a large number of diagram types, including basic flowcharts, sequence diagrams, class diagrams and even project diagrams like timelines and Gantt charts. See the Mermaid documentation for examples.

Here’s some simple examples taken from the documentation:

Embedded in a Markdown document:

```mermaid
graph TD;
    A-->B;
    A-->C;

  graph TD;
    A-->B;
    A-->C;

---
title: Animal example
---
classDiagram
    note "From Duck till Zebra"
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }

  ---
title: Animal example
---
classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }

Where These Are Used

Markdown is used in multiple places in your project.

README.md

The first document you will need to produce is the README.md file for your GitLab project. This is a Markdown file that should be in the root of your Git project (and it will be the page displayed when your Gradle project page opens). Creating this file is discussed on the Setup Your Project page.

Wiki pages

You will be asked to store major project documents e.g., project proposal in a Wiki page. This is simply a standalone page where you can enter markdown and mermaid content.

You can add Wiki pages in your project by using the project menu: Plan > Wiki.

• Give all pages meaningful names.
• If you are adding project documents, make sure to link the wiki page to the top-level README file so that the TA can find it.
• Feel free to add any additional useful documents as Wiki pages.

UML Diagrams

Mermaid.js can be used to crate UML diagrams in a markdown file or a Wiki page. They cannot be added to source code directly, but can certainly be placed in a markdown-based design document for that code.

The following diagrams are particularly useful when documenting a system:

• Flowcharts or Block diagrams can be used to document a system structure e.g., modules or components.
• Class diagram for documenting classes and relationships.
• State diagram demonstrating transitions between states.

These diagrams can be useful for documenting a project.

• Gantt chart to show a plan or schedule.
• Timeline illustrates a chronology of events. Alternative to a Gantt chart.
• User journey diagrams show important workflows (sequences of actions) from the user’s perspective. They can be decomposed into a set of related requirements.

  gantt
    title A Gantt Diagram
    dateFormat YYYY-MM-DD
    section Section
        A task          :a1, 2014-01-01, 30d
        Another task    :after a1, 20d
    section Another
        Task in Another :2014-01-12, 12d
        another task    :24d

An example of a Gantt chart from the Mermaid documentation.