FS IN Kanton Bern

Markdown wurde 2004 von John Gruber und Aaron Swartz erfunden. Die beiden wollten eine Markup-Sprache, die auch als Quellcode leserlich ist.

Markdown lässt sich in diverse andere Formate übersetzen, unter anderem auch in Latex oder in ein Word-Dokument. Für uns steht aber das Web im Zentrum und somit die Übersetzung von Markdown in HTML.

Der in Vitepress verwendete Markdown-Interpreter «markdown-it» ist in Javascript geschrieben und bietet zahlreiche Erweiterungen mittels Plugins.

Im Folgenden sind die wichtigsten Elemente und ihre Übersetzung vorgestellt.

Playground

Unter https://markdown-it.github.io/ kann markdown-it online ausprobiert werden.

Überschriften ​

Die HTML-Überschriften h1, h2, … werden in Markdown wie folgt dargestellt:

  • Markdown
  • Vorschau
md
# Überschrift 1
## Überschrift 2
### Überschrift 3
Text

Inline-Formatierungen ​

Die Inline-Formatierungen kursiv, fett und monospaced sind standardmässig dabei. Weitere sind durch Plugins verfügbar. (z.B. hochgestellt, tiefgestellt, durchgestrichen, angestrichen, …)

  • Markdown
  • Vorschau
md
*kursiv*, **fett** und `monospaced`

Links können relativ oder absolut angegeben werden. Die Dateiendung .md bei relativen Links wird automatisch in .html übersetzt.

  • Markdown
  • Vorschau
md
interner Link: [nächstes Kapitel](./vue.md)
externer Link: [mein Gymer](https://www.gymkirchenfeld.ch)

Listen ​

Es sind sowohl nummerierte Listen <ol> als auch Listen mit Aufzählungspunkten <ul> möglich. Listen lassen sich durch Einrücken verschachteln:

  • Markdown
  • Vorschau
md
1. erster Punkt
2. zweiter Punkt

* erster Punkt
* zweiter Punkt
  * erster Unterpunkt
  * zweiter Unterpunkt
* dritter Punkt

Bilder ​

Bilder können durch absolute oder relative Links eingebettet werden. Die Syntax sieht wie folgt aus:

  • Markdown
  • Vorschau
md
![Screenshot Vitepress](../images/vitepress-screenshot.png)

Praktisch ist die Erweiterung markdown-it-implicit-figures. Damit wird das Bild in ein figure-Element gepackt welches dann automatisch als Bildbeschreibung (figcaption) das alt-Attribut des img-Elementes erhält.

Tabellen ​

Tabellen bestehen aus einer Kopfzeile und beliebig vielen Inhalts-Zeilen. Die Text-Ausrichtung der Spalten kann mittels Doppelpunkt in der zweiten Zeile angegeben werden:

  • Markdown
  • Vorschau
md
[einfache Tabelle]
| Spalte normal | Spalte links | Spalte zentriert | Spalte rechts |
| ------------- |:------------ |:----------------:| -------------:|
| Inhalt        | Inhalt       | Inhalt           | Inhalt        |
| Inhalt        | Inhalt       | Inhalt           | Inhalt        |

Praktisch ist die Tabellen-Erweiterung markdown-it-multimd-table. Diese lässt Tabellen nach der MultimarkDown-Definition zu. Dort ist es möglich, mehrere Kopfzeilen zu haben, Zellen zu gruppieren und mehrere tbody-Elemente zu definieren. Dadurch lassen sich komplexere Tabellen darstellen.

  • Markdown
  • Vorschau
md
|             |          Grouping           ||
First Header  | Second Header | Third Header |
 ------------ | :-----------: | -----------: |
Content       |          *Long Cell*        ||
Content       |   **Cell**    |         Cell |
											  
New section   |     More      |         Data |
And more      | With an escaped '\\|'       ||
[Beispiel nach MultimarkDown-Syntax]

Code-Blöcke ​

Code-Blöcke werden durch drei ``` eingeleitet und auch wieder beendet. Fürs Syntax-Highlightning kann die Sprache angegeben werden. Diese wird beim HTML-Code-Block als css-Klasse mitgeben.

  • Markdown
  • Vorschau
v-pre
		```python
		def hello_world():
			print("Hello World!")
		
		hello_world()
		```

Syntax-Highlightning ​

Vitepress setzt bei der Darstellung von Code auf prism.js. Es werden zahlreiche Sprachen unterstützt. Einige Beispiele:

java
class HelloWorld {
	public static void main(String[] args) {
		System.out.println("Hello, World!"); 
	}
}
html
<img src="images/hello.png" alt="Hallo Welt" />
css
body.dark {
	background-color: black;
	color: #f2f2f2;
}
js
const top_students = students.filter(student => (student.grade >= 5));
sql
SELECT * FROM students JOIN grades
    ON student.id = grade.student_id;
latex
\documentclass[12pt]{article}
\begin{document}
Hello world!
$Hello world!$ %math mode 
\end{document}
json
items: [
	{
		id: 1,
		code: "R"
	},
	{
		id: 2,
		code: "S"
	}
]

Markdown-It-Erweiterungen ​

Die folgenden Erweiterungen kann ich empfehlen:

sup
hochgestellter Text mit <sup>
sub
tiefgestellter Text mit <sub>
mark
Elemente Hervorheben mit <mark>
kbd
Tastenkürzel mit <kbd>
abbr
Beschreibung für Abkürzungen mittels <abbr>
deflist
erlaubt Definition Lists mit <dl>, <dt> und <dd>
fancy-lists
flexiblere Listen (alphanumerisch, numerisch, …)
multimd-table
Tabellen nach MultimarkDown-Syntax
implicit-figures
<figure> und <figcaption> automatisch um <img>
footnote
Fussnoten einfügen
video
externe Videos einbetten (Youtube, Vimeo, Vine und Prezi)

Weitere Erweiterungen findet man in der NPM-Registry, einfach nach markdown-it suchen!

Kantonale Fachschaft Informatik – Gymnasien Bern