Dieser Beitrag soll alle wichtigen Elemente auflisten, die in Beiträgen auf diesem Blog zum Einsatz kommen können und entsprechend visuell ansprechend dargestellt werden sollten. Er dient mir selbst einerseits als Referenz um später schnell die Syntax für Elemente nachzuschlagen und andererseits dazu, die Elemente während der Entwicklung des Blogs mit den korrekten CSS Styles zu versehen.

Einleitung

Als Blogging Engine setze ich den Static Site Generator Hugo ein. Ein Static Site Generator funktioniert nach einem simplen Grundprinzip: Er nimmt Daten als Input und generiert daraus eine komplette Webseite, die zur Laufzeit ganz ohne das Laden von dynamischen Daten auskommt.

Normallerweise liegen die Daten die Hugo zum Generieren der Webseite nimmt im Markdown Format vor. So auch für diesen Blog. Deshalb beschreibe ich im folgenden, welche Syntax verwendet werden muss um die beschriebenen Elemente zu generieren.

Damit Hugo zum Beispiel den Einleitungstext zu einem Beitrag korrekt generiert, muss nach der Einleitung das Tag <!--more--> verwendet werden. Wird dies nicht gemacht nimmt Hugo einfach die ersten 70 Wörter des Beitrags als Einleitungstext.

Überschriften (H2)

Überschriften können in Markdown definiert werden, indem eine Zeile mit einem # begonnen wird. Verwendet man zwei ## wird daraus eine Überschrift zweiter Ordnung und so weiter. Das sieht dann zum Beispiel so aus:

1
2
3
4
5
6
7
8
9

# Überschriften (H1)

## Überschriften (H2)

### Überschriften (H3)

#### Überschriften (H4)

##### Überschriften (H5)

Überschriften (H3)

Überschriften (H4)

Überschriften (H5)

Ich versuche zudem zu vermeiden Überschriften erster Ordnung in meinen Beiträgen zu verwenden, da der Titel eines Beitrags automatisch als Überschrift erster Ordnung durch meine Templates hinzugefügt wird und zusätzliche Überschriften gleicher Ordnung in der Struktur somit wenig Sinn ergeben würden.

Textelemente / Paragraphen (P)

Textblöcke in Markdown werden automatisch zu Paragraphen im generierten HTML. Ein einfacher Zeilenumbruch bewirkt zudem nicht automatisch, dass ein neuer Paragraph begonnen wird. Dazu müssen mindestens zwei Zeilenumbrüche zwischen Textblöcken verwendet werden.

Zitate (Blockquote)

Ein Zitat kann ganz einfach erstellt werden, indem eine Zeile mit einem > begonnen wird. Hier zum Beispiel eines meiner Lieblings-Zitate:

We build our computer (systems) the way we build our cities: over time, without a plan, on top of ruins.

Ellen Ullman

Damit lange Zitate nicht auf eine einzelne Zeile gebracht werden müssen, kann auch jede Zeile einzeln mit einem > begonnen werden. Das sieht dann zum Beispiel so aus:

1
2
3
4

> We build our computer (systems) the way we build our cities:
> over time, without a plan, on top of ruins.
>
> Ellen Ullman

Auflistungen

Unsortierte Auflistungen (Ul)

Um eine Auflistung zu generieren können einzelne Listenelemente mittels -, * oder + nach einander aufgelistet werden:

1
2
3

- Element 1
- Element 2
- Element 3

Dies generiert die folgende Auflistung:

• Element 1
• Element 2
• Element 3

... mit Verschachtelung

Werden Elemente einer Auflistung eingerückt, entsteht eine verschachtelte Auflistung:

• Element 1
  • Element 2
    • Element 3

Sortierte Auflistungen (Ol)

Wenn Listenelemente hingegen durch eine Nummerierung aufgelistet werden, entsteht daraus eine sortierte Auflistung:

1. Element 1
2. Element 2
3. Element 3

... mit Verschachtelung?

Bis jetzt habe ich leider noch nicht herausgefunden wie verschachtelte sortierte Auflistungen gemacht werden können (ausser durch die direkte Verwendung von HTML Syntax innerhalb des Markdown Dokuments selbst, was auch möglich ist).

Quellcode (Code)

Für einen Blog der sich mit Entwicklungs-Themen beschäftigt ist es natürlich auch wichtig, dass Quellcode-Beispiele eingebunden werden können. In Markdown funktioniert dies ganz einfach indem ein Block mit ``` begonnen und beendet wird.

Das folgende Beispiel

1
2
3
4
5
6
7

```
export class Greeter {
  public greet(name: string): void {
    console.log(`Hello ${name}!`);
  }
}
```

wird also zu

1
2
3
4
5

export class Greeter {
  public greet(name: string): void {
    console.log(`Hello ${name}!`);
  }
}

... mit Syntax-Highlighting

Genauso wichtig wie das Einbinden von Quellcode ist auch die Hervorhebung der Syntax. Dies wird erreicht indem die Programmiersprache direkt zu Begin des Blocks angegeben wird:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

```typescript
import { Pipe, PipeTransform } from '@angular/core';
import { ActivatedRoute } from '@angular/router';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

/**
 * A pipe that serves as example.
 */
@Pipe({
  name: 'example',
  pure: true,
})
export class ExamplePipe implements PipeTransform {
  constructor(private readonly service: ExampleService) {}

  public transform(value: string): Observable<any> {
    return this.service.data.pipe(map(data => `value = ${data[value] ?? 0}`));
  }
}
```

Das Resultat sieht dann so aus:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

import { Pipe, PipeTransform } from '@angular/core';
import { ActivatedRoute } from '@angular/router';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

/**
 * A pipe that serves as example.
 */
@Pipe({
  name: 'example',
  pure: true,
})
export class ExamplePipe implements PipeTransform {
  constructor(private readonly service: ExampleService) {}

  public transform(value: string): Observable<any> {
    return this.service.data.pipe(map(data => `value = ${data[value] ?? 0}`));
  }
}

... oder inline

Zusätzlich zu Quellcode-Blöcken können Quellcode-Elemente auch inline markiert werden indem sie in ` gesetzt werden, wie z.B. diese console.log() Methode.

Links (A)

Links können ganze einfach in den Textfluss eingebaut werden, wie z.B. dieser externe Link zu Google oder dieser interne Link zu den Kategorien. Die Markdown Syntax dazu sieht übrigens so aus:

1
2
3

Links können ganze einfach in den Textfluss eingebaut werden,
wie z.B. dieser [externe Link](https://google.ch) zu Google
oder dieser [interne Link](/categories) zu den Kategorien.

Referenzen

Anstatt Links direkt im Textfluss zu definieren, können auch Referenzen verwendet werden. Hier zum Vergleich externe Link und der interne Link als Referenzen. Optisch ändert sich an den Links nichts. Dies hat den Vorteil dass die Markdown Syntax etwas aufgeräumter daher kommt und Links zum Beispiel am Ende des Dokuments aufgelistet werden können:

1
2
3
4
5

Hier zum Vergleich [externe Link][extern]
und der [interne Link][intern] als Referenzen.

[extern]: https://google.ch
[intern]: /categories/

Hervorhebungen (Em / Strong / Del)

Selbstverständlich ist es auch möglich Text kursiv oder fettgedruckt hervorzuheben. Dazu wird der Text entweder durch _ umgeben um in kursiv darzustellen oder durch ** um eine fettgedruckte Darstellung zu erreichen. Beides gleichzeitig geht übrigens auch indem der Text mit **_ und _** umgeben wird! Weniger oft Verwendung finden wird wohl durchgestrichener Text, was mittels ~~ erreicht wird.

Bilder (Img)

Um Bilder einzufügen habe ich einen eigenen Hugo-Shortcode erstellt. Ich verwende diesen anstelle der Markdown Syntax um den daraus generierten HTML Code selbst zu definieren.

Ausserdem kann ich den Shortcode mit einem zweiten selbst-erstellten Shortcode kombinieren um so mehrere Bilder sauber nebeneinander zu platzieren.