1. Installieren Sie sich Visual Studio Code.
2. Installieren Sie die Erweiterungen µJam und Markdown+Math.
3. Erstellen Sie auf Ihrem System einen Projektordner mit einem beliebigen Namen. Zum Beispiel: Mechanismentechnik.
4. In dem Projektordner erstellen Sie einen weiteren Ordner. Diesmal mit dem Namen docs.
5. Nun starten Sie Visual Studio Code und öffnen Sie Ihren Projektordner. (Ctrl + O)
6. Erstellen Sie eine neue Datei. File > New File (Ctrl + N).
7. Kopieren Sie folgenden Text in diese Datei:

{
  "name": "Mechanismentechnik",
  "description": "My first web page using microjam",
  "version": "0.1.0",
  "author": "it's me",
  "microjam": {}
}

8. Speichern Sie die Datei nun unter der Bezeichnung package.json ab. (Ctrl + S)
9. Die Ordnerstruktur sollte bis hierhin so aussehen:

/Mechanismentechnik
|_ package.json
|_ /docs    (empty folder)

10. Erstellen Sie eine weitere Datei und beginnen Sie diesmal beispielsweise mit diesen Text:

---
"layout": "page",
"title": "About"
---

# Überschrift Ihres Webprojekts
  
Ihre persönliche Aufgabenbeschreibung.

11. Speichern Sie die Datei nun unter der Bezeichnung about.md in dem Verzeichnis ./docs ab. Wenn Sie µJam aktiviert haben, müssten einige Dateien automatisch hinzugefügt werden, sodass die Ordnerstruktur jetzt folgendermaßen aussieht:

/Mechanismentechnik
|_ package.json
|_ /docs
    |_ about.md
    |_ about.html
    |_ pages.json
    |_ /theme
        |_ style.css
        |_ template.js

12. Das Arbeitsverzeichnis, das Sie zur Bearbeitung der Webprojekte benötigen ist soweit eingerichtet. Wenn Sie weiterführende Informationen benötigen (zu dem was Sie in den 11 Schritten gemacht haben), dann besuchen und lesen Sie zusätzlich die µJam-Dokumentation.

Im nächsten Schritt sollten Sie das Kapitel, welches Sie zur Lösung Ihrer Aufgaben benötigen, aufmerksam durcharbeiten und gegebenenfalls die Grundlagen bereits dokumentieren. Die gesamte Dokumentation wird im docs-Verzeichnis gespeichert. Ihre Markdown-Files können Sie gerne, wenn sinnvoll, in mehreren .md-Dateien organisieren. Versuchen Sie, die Aufgaben derart zu dokumentieren, als wenn Sie versuchen würden, diese Ihren Kommilitonen zu erklären. Ein passendes Beispiel finden Sie hier.

Wenn Sie nicht weiterkommen oder generell Fragen haben, scheuen Sie sich nicht die Tutoren anzuschreiben!

• kaihenning.lawrence002@stud.fh-dortmund.de
• demetrius.lorenz001@stud.fh-dortmund.de

Zuerst einmal – Warum überhaupt Texte in Markdown schreiben?

Markdown ist einfach und schnell! Es kann innerhalb weniger Minuten erlernt werden. Markdown ist eine “leichtgewichtige“ Auszeichnungssprache, dessen Quelltext jederman lesen kann, ohne die Syntax dahinter zu kennen. Texte die in Markdown geschrieben sind, können problemlos von jedem Endgerät, Editor oder Tool das Textdateien verarbeitet, geöffnet werden. Sie brauchen keine teuren und mit Funktionen überladenen WYSIWYG Anwendungen wie Microsoft Word. Die Texte, die Sie in Markdown schreiben, können leicht in HTML konvertiert und damit auch im Internet publiziert werden.

Also fangen wir mit der Basic-Syntax und einigen Erläuterung dazu an.

• Überschriften
• Paragraphen
• Texthervorhebung
• Blockzitat
• Listen
• Code
• Bilder
• Links
• HTML
• Sonderzeichen
• Tabellen

Überschriften

Um in Markdown eine Überschrift zu erzeugen wird ein oder mehrere hashtags(#) vorangestellt. Auf dieser µJam-Seite wird der Latex-Style verwenden. Die Überschriften sind mittels CSS angepasst. Aus diesem Grund ist die Level 3 Überschrift kursiv und die Level 4 Überschrift mittig ausgerichtet. Die Darstellung von Überschriften kann je nach Anwendung variieren.

# Level 1 Überschrift

## Level 2 Überschrift

### Level 3 Überschrift

#### Level 4 Überschrift

##### Level 5 Überschrift

###### Level 6 Überschrift

Wichtiger Hinweis:

Die Level 1 Überschrift wird in der Regel für jedes Hauptkapitel nur ein einziges Mal verwendet. Level 2 & 3 Überschriften werden für Unterkapitel verwendet. Level 4 ist meistens für die Beschriftung von Abbildungen, Tabellen oder Gleichungen reserviert. Level 5 & 6 sind weniger gebräuchlich.

Ein beispielhafter Aufbau:

# 1 Getriebekinematik
## 1.1 Schleifengleichungen
### 1.1.1 Schleife des Viergelenks     
## 1.2 Lagenanalyse
### 1.2.1 ...

# 2 Krümmungsverhältnisse
## 2.1 ...
### ...

 

Paragraphen

Fließtext kann, wie im folgenden Beispiel gezeigt, durch Einsetzen einer Leerzeile mit Absätzen in Paragraphen unterteilt werden.

Damit ein Text übersichtlich bleibt, sollte dieser in sinnvolle Paragraphen unterteilt werden. Das erleichtert dem Leser das Lesen langer Texte. 

Ein Absatz ist eine Unterbrechung in einem fortlaufend gedruckten oder geschriebenen Text, welcher mit einer Leerzeile in der Auszeichnungssprache Markdown erzeugt wird.

Wichtiger Hinweis:

Um einen Zeilenumbruch zu erzeugen, können am Ende der ersten Zeile zwei Leerzeichen oder ein <br> gesetzt werden. Nach einem return folgt die zweite Zeile. Es sollte die <br>-Variante bevorzugt werden, weil Leerzeichen schwer zu erkennen sind.

Beispiel: Zeilenumbruch

Das ist meine erste Zeile Text.<br>
Das ist meine zweite Zeile Text.

 

Texthervorhebung

Tabelle 1: Übersicht einiger Möglichkeiten zur Texthervorhebung

Blockzitat

Sogenannte blockquotes eignen sich besonders für Zitate, Anmerkungen, Hinweise oder andere Weisheiten. Mit einem Größerzeichen (>) lassen sich Blockzitate erzeugen.

Eingabe

> *People think that computer science is the art of geniuses but the actual reality is the opposite, just many people doing things that build on each other, like a wall of mini stones.*
>
> --- Donald Knuth

Ausgabe

People think that computer science is the art of geniuses but the actual reality is the opposite, just many people doing things that build on each other, like a wall of mini stones.

--- Donald Knuth

Listen

Es gibt zwei Arten von Listen; geordnete und ungeordnete.

Eingabe

* Auf diese Art und Weise
* lässt sich eine ungeordnete
* Liste erstellen.
   * Einrücken ist erlaubt.

Ausgabe

• Auf diese Art und Weise
• lässt sich eine ungeordnete
• Liste erstellen.
  • Einrücken ist erlaubt.

Im Gegensatz dazu eine geordnete Liste:

Eingabe

1) Auf diese Art und Weise
2) lässt sich eine geordnete
3) Liste erstellen.
    1) Einrücken geht auch
    2) muss nur wieder mit der `1)` beginnen.

Ausgabe

1. Auf diese Art und Weise
2. lässt sich eine geordnete
3. Liste erstellen.
   1. Einrücken geht auch
   2. muss nur wieder mit der 1) beginnen.

Code

Für inline-code siehe unter Texthervorhebung.

Es lassen sich zusätzlich Code-Blöcke erzeugen. Dazu werden drei sogenannter backticks (```) am Anfang und am Ende des Code-Blocks platziert.

```JavaScript
const superCoolArrowFunction = (a, b, c) => {
let sum = a + b + c;
return sum;
}
```

Nach den ersten drei backticks lässt sich die verwendete Sprache präzisieren, sodass die Ausgabe unterschiedlich hervorgehoben wird.
Das JavaScript code Beispiel sieht dann entsprechend so aus:

const superCoolArrowFunction = (a, b, c) => {
    let sum = a + b + c;
    return sum;
}

Bilder

Es lassen sich problemlos Bilder einbinden. Das einzige was man dafür wissen muss, ist der relative Pfad zum Ablageort des entsprechenden Bildes. Zum besseren Verständnis ein Beispiel:

Dieser Text ist in der Datei faq.md geschrieben, welche im Ordner docs liegt. In diesem Ordner existiert noch ein weiterer Ordner namens img, in dem momentan vier Bilder zu finden sind. Die Ordnerstruktur ist rechts dargestellt.

Um jetzt z.B. das Bild mec.5.9.png zu erreichen, sieht die Markdown-Syntax wie folgt aus:

![Bildbeschreibung](./img/mec.5.9.png "alternativerText")

Wichtiger Hinweis:

Das ./ bedeutet, dass wir uns im gleichen Ordner befinden. Wenn das gesuchte Bild außerhalb des docs-Verzeichnisses läge, dann ist ../ der Weg aus dem aktuellen Ordner.

Links

Für einen Link wird der Text zum Anklicken in eckigen Klammern eingeschlossen, gefolgt von der Adresse in runden Klammern.

[Link zur g2-Dokumenation](https://goessner.github.io/g2/microjam.md/Getting-Started.html)

Das Ergebnis ist: Link zur g2-Dokumenation.

Wichtiger Hinweis:

Es lassen sich auch Links innerhalb Ihres Textes verteilen. Eine Anwendungsmöglichkeit ist die Verlinkung zu Referenzen. Die Vorgehensweise sieht wie folgt aus:

• Erstellen eines Links mit einer beliebigen ID
  z.B Beispieltext der einer Quellenangabe bedarf [1](#1).
• Ganz unten im Text, wo Referenzen gewöhnlicherweise hingehören, wird ein span-tag mit der zugehörigen ID gesetzt; in unserem Beispiel <span id="1">.

HTML

Viele Markdown Editoren lassen den Einsatz von HTML zu. Das ist sehr hilfreich, weil dadurch viele Gestaltungsmöglichkeiten hinzukommen. Zum Beispiel lassen sich einzelne Attribute von Elementen wie die Farbe eines Textes anpassen.

Tabelle 2: Einige inline Markup-Elemente

Sonderzeichen

Reservierte Sonderzeichen lassen sich mit der Hilfe eines vorangestellten backslashs (\) darstellen.

\* Ohne das backslash würde statt des Sternchens eine ungeordnete Liste dargestellt.

Tabelle 3: Darstellung von Sonderzeichen

Tabellen

Tabellen gehören eigentlich nicht mehr zu der Basic-Syntax von Markdown, aber weil überaus nützlich und häufig verwendet, sollen Tabellen an dieser Stelle trotzdem kurz vorgestellt werden.

#### Beispieltabelle 1: Eingabe

| Pro         | Contra      |
| ----------- | ----------- |
| Schnell     | Zeit        |
| Leicht      | Geld        |

Beispieltabelle 1: Ausgabe

Wichtiger Hinweis:

Die Tabelle muss nicht derart akkurat geschrieben sein. Folgendes Beispiel führt zum gleichen Ergebnis.

#### Beispieltabelle 2: Eingabe

| Pro | Contra |
| --- | --- |
| Schnell | Zeit |
| Leicht | Geld |

Der Text innerhalb einer Tabellenspalte lässt sich auch ausrichten.

#### Beispieltabelle 3: Eingabe

| Links | Mittig | Rechts |
| :--- | :---: | ---: |
| Schnell | Zeit | Höhe |
| Leicht | Geld | Tiefe |

Beispieltabelle 3: Ausgabe

Links	Mittig	Rechts
Schnell	Zeit	Höhe
Leicht	Geld	Tiefe

 

Damit wurden die wichtigsten Markdown-Elemente erläutert. Eine gute Quelle zum Nachschlagen ist dieser Markdownguide.

Oh je...das Bild ist fürchterlich misslungen und darf auf keinen Fall in einem wissenschaftlichen Text verwendet werden...

An dieser Stelle erfahren Sie Schritt für Schritt, wie es besser funktioniert.

Vorabbedingungen:

• VS-Code ist installiert.
• µJam-Erweiterung ist installiert.

Beginnen Sie immer mit dieser 'Schablone':

<aside>
<g-2 width="200" height="300" x0="0" y0="0" cartesian>
{ 
    "main": [
        { "c": " ", "a": { } }   
    ]
}
</g-2>

#### Abb. 1: Bildunterschrift

</aside>

<g2> ist das custom HTML-tag, mit dem Sie eine Skizze erstellen. Innerhalb des tags wird die Abmessungen der Abbildung mit width = "xyz" und height = "zyx" eingestellt. Die Ursprungskoordinaten der Zeichnung sind mit x0 = "50" und y0 = "30" beliebig wählbar.

Die Skizze kann mit dem <aside>-tag am rechten Seitenrand ausgerichtet werden. Im Gegensatz dazu zentriert das <figure>-tag die Skizze. Jede Abbildung muss beschriftet sein! Sie können Markdown verwenden, müssen dann allerdings die Konventionen der Auszeichnungssprache beachten. Vor und nach einer Überschrift wird eine Leerzeile eingesetzt. Andernfalls kann das <h4>-tag genutzt werden.

Im inneren des g2-tags befindet sich ein Array mit dem Namen main, welches eine Befehlskette entgegennimmt. Jedes Argument des Arrays repräsentiert einen Befehl in Form eines Objektes mit verschiedenen Eigenschaften. Die wichtigsten Eigenschaften sind "c" für ein Kommando, z.B. "nodfix" zum Zeichnen eines Festlagers und "a" für eine Vielzahl von Argumente, z.B. {"x":0, "y":0, "label":"A0"} zum Zeichnen des Festlagers in der Position x = 0, y = 0 mit der Beschriftung A0. Es ist wichtig zu beachten, dass die Eigenschaft "a" als Wert wieder ein Objekt beinhaltet.

Um beispielhaft ein Koordinatenkreuz zu erzeugen, wird folgendes Objekt in das main-Array geschrieben.

{ 
"c": "origin",
"a": {
    "x": 0,
    "y": 0,
    "label": "Ursprung",
    "lw": 2,
    "lbloc": 0.6
    }
}

Zum besseren Verständnis soll nachfolgend die missglückte Abbildung reproduziert werden.

Schritt 1: Zeichnen der Festlager $A_0$, $B_0$ und der Gliedpunkte $A$, $B$, $C$.

<figure>
<g-2 width="250" height="300" x0="30" y0="50" cartesian>
{ 
"main": [
    { "c": "origin","a": {"x": 0,"y": 0,"lw": 1.5}},
    { "c": "nodfix", "a": { "x":0, "y":0, "label":{"str":"A0", "loc": "sw", "off": 15 }}},
    { "c": "nodfix", "a": { "x":150, "y":0, "label":{"str":"B0", "loc": "se", "off": 15 }}},
    { "c": "nod", "a": { "x":30, "y":100, "label":{"str":"A", "loc": "nw", "off": 5 }}},
    { "c": "nod", "a": { "x":170, "y":150, "label":{"str":"B", "loc": "ne", "off": 5 }}},
    { "c": "nod", "a": { "x":100, "y":180, "label":{"str":"C", "loc": "ne", "off": 5 }}}
    ]
}
</g-2>

#### Abb. 1: Gliedpunkte

</figure>

Schritt 2: Zeichnen der Gliedlängen $a$, $b$, $c$.

<figure>
<g-2 width="250" height="300" x0="30" y0="50" cartesian>
{ 
"main": [
    { "c": "beam", "a": { "pts":[30,100,100,180,170,150], 
    "fs":"silver", "label":{"str":"b", "off": 5 }}},
    { "c": "bar", "a": { "x1":0, "y1":0, "x2":30, "y2":100, "label":{"str":"a", "off": -5 }}},
    { "c": "bar", "a": { "x1":30, "y1":100, "x2":170, "y2":150, "label":{"str":"b", "off": -5 }}},
    { "c": "bar", "a": { "x1":150, "y1":0, "x2":170, "y2":150, "label":{"str":"b", "off": 5 }}},
    { "c": "origin","a": {"x": 0,"y": 0,"lw": 1.5}},
    { "c": "nodfix", "a": { "x":0, "y":0, "label":{"str":"A0", "loc": "sw", "off": 15 } } },
    { "c": "nodfix", "a": { "x":150, "y":0, "label":{"str":"B0", "loc": "se", "off": 15 } } },
    { "c": "nod", "a": { "x":30, "y":100, "label":{"str":"A", "loc": "nw", "off": 5 } } },
    { "c": "nod", "a": { "x":170, "y":150, "label":{"str":"B", "loc": "ne", "off": 5 } } },
    { "c": "nod", "a": { "x":100, "y":180, "label":{"str":"C", "loc": "ne", "off": 5 } } }
    ]
}
</g-2>

#### Abb. 2: Zeichnen der Gliedlängen

</figure>

Schritt 3: Zeichnen der Hilflinien $d$, $g$ und der Winkel $\varphi$, $\theta$.

<figure>
<g-2 width="250" height="300" x0="30" y0="50" cartesian>
{ 
"main": [
    {"c":"avec","a":{"x":10,"y":0,"r":30,"dw":1.5,"ls":"green","label":{"str":"&varphi;", "off":-2.5 }}},
    {"c":"avec","a":{"x":80,"y":100,"r":40,"dw":0.75,"ls":"green","label":{"str":"&theta;", "off":-5 }}},
    { "c": "lin", "a": { "x1":-20, "y1":0, "x2":170, "y2":0, "ld":[8,4,1,4], "label":{"str":"d", "off": 5 }}},
    { "c": "lin", "a": { "x1":30, "y1":100, "x2":140, "y2":100, "ld":[8,4,1,4], "label":{"str":"g", "off": 5 }}},
    { "c": "beam", "a": { "pts":[30,100,100,180,170,150], "fs":"silver", "label":{"str":"b", "off": 5 }}},
    { "c": "bar", "a": { "x1":0, "y1":0, "x2":30, "y2":100, "label":{"str":"a", "off": -5 }}},
    { "c": "bar", "a": { "x1":30, "y1":100, "x2":170, "y2":150, "label":{"str":"b", "off": -5 }}},
    { "c": "bar", "a": { "x1":150, "y1":0, "x2":170, "y2":150, "label":{"str":"b", "off": 5 }}},
    { "c": "origin","a": {"x": 0,"y": 0,"lw": 1.5}},
    { "c": "nodfix", "a": { "x":0, "y":0, "label":{"str":"A0", "loc": "sw", "off": 15 } } },
    { "c": "nodfix", "a": { "x":150, "y":0, "label":{"str":"B0", "loc": "se", "off": 15 } } },
    { "c": "nod", "a": { "x":30, "y":100, "label":{"str":"A", "loc": "nw", "off": 5 } } },
    { "c": "nod", "a": { "x":170, "y":150, "label":{"str":"B", "loc": "ne", "off": 5 } } },
    { "c": "nod", "a": { "x":100, "y":180, "label":{"str":"C", "loc": "ne", "off": 5 } } }
    ]
}
</g-2>

#### Abb. 3: Zeichnen der Hilfslinien und Winkel

</figure>

Schritt 4: Zeichnen der Vektoren.

<figure>
<g-2 width="250" height="300" x0="30" y0="50" cartesian>
{ 
"main": [
    {"c":"avec","a":{"x":10,"y":0,"r":30,"dw":1.5,"ls":"green","label":{"str":"&varphi;", "off":-2.5 }}},
    {"c":"avec","a":{"x":80,"y":100,"r":40,"dw":0.75,"ls":"green","label":{"str":"&theta;", "off":-5 }}},
    { "c": "lin", "a": { "x1":-20, "y1":0, "x2":170, "y2":0, "ld":[8,4,1,4], "label":{"str":"d", "off": 5 }}},
    { "c": "lin", "a": { "x1":30, "y1":100, "x2":140, "y2":100, "ld":[8,4,1,4], "label":{"str":"g", "off": 5 }}},
    { "c": "beam", "a": { "pts":[30,100,100,180,170,150], "fs":"silver", "label":{"str":"b", "off": 5 }}},
    { "c": "bar", "a": { "x1":0, "y1":0, "x2":30, "y2":100, "label":{"str":"a", "off": -5 }}},
    { "c": "bar", "a": { "x1":30, "y1":100, "x2":170, "y2":150, "label":{"str":"b", "off": -5 }}},
    { "c": "bar", "a": { "x1":150, "y1":0, "x2":170, "y2":150, "label":{"str":"b", "off": 5 }}},
    { "c": "origin","a": {"x": 0,"y": 0,"lw": 1.5}},
    { "c": "nodfix", "a": { "x":0, "y":0, "label":{"str":"A0", "loc": "sw", "off": 15 } } },
    { "c": "nodfix", "a": { "x":150, "y":0, "label":{"str":"B0", "loc": "se", "off": 15 } } },
    { "c": "nod", "a": { "x":30, "y":100, "label":{"str":"A", "loc": "nw", "off": 5 } } },
    { "c": "nod", "a": { "x":170, "y":150, "label":{"str":"B", "loc": "ne", "off": 5 } } },
    { "c": "nod", "a": { "x":100, "y":180, "label":{"str":"C", "loc": "ne", "off": 5 } } },
    {"c":"vec","a":{"x1":30,"y1":100,"x2":120,"y2":132,"ls":"darkred","lw":3 }},
    {"c":"vec","a":{"x1":120,"y1":132,"x2":100,"y2":180,"ls":"darkred","lw":3 }}
    ]
}
</g-2>

#### Abb. 4: Zeichnen der Vektoren

</figure>

Zum Schluss noch einige Anmerkungen und Hinweise:

1. Die Befehlskette muss nicht immer wieder neu formuliert werden. Wenn Sie z.B. mehrere Gliedpunkte erzeugen möchten, dann kopieren Sie das Objekt und verändern Sie die jeweiligen Parameter.
2. Die Befehlskette wird von oben nach unten ausgeführt. Das bedeutet wiederum, dass gezeichnete Elemente unter Umständen “übermalt“ werden. Aus diesem Grund wurden die beiden roten Vektoren ganz unten in der Befehlskette eingesetzt. Andernfalls wären die Vektoren von der Koppel verdeckt.
3. Die Befehle müssen nicht alle auswendig gelernt werden. In Kürze soll dazu noch ein cheatsheet entstehen. In der Zwischenzeit kann die g2-Dokumentation helfen oder eine Mail an die Tutoren.

Vorbedingungen:

1. µJam muss installiert und aktiv sein.
2. Sie haben das Arbeitsverzeichnis für Ihr Projekt erfolgreich erstellt (vgl. FAQ: Wie fange ich mit der Bearbeitung der Webprojekt an?).
3. Es befinden sich die Dateien style.css und template.js im ./docs/theme Ihres Projektverzeichnisses.

Das Styling Ihrer HTML-Seiten wird von den Dateien style.css und template.js, welche sich im ./docs/theme-Verzeichnis befinden müssen, gesteuert. Diese dürfen angepasst werden, allerdings empfiehlt sich dies nur bei ausreichender CSS und JavaScript Kenntnis. Während Änderungen an der style.css-Datei sich nur geringfügig und hauptsächlich auf die Darstellung im Browser auswirken, können Änderungen an der template.js-Datei den Aufbau der HTML-Dateien verhindern.

Alternativ können Sie das gesamte ./docs/theme-Verzeichnis, bzw. die darin befindlichen style.css und template.js Dateien, mit den von uns bereitgestellten Gestaltungen ersetzen.

• LaTeX Style
• Docs Style
• g2 Style
• Simple Style
• Tufte Style