← Zurück

Knowledge Bases

Grundlagen, Aufbau und technische Funktionsweise von Knowledge Bases.

Was ist eine Knowledge Base?

Eine Einführung in Knowledge Bases.

Wie die Knowledge Base funktioniert

Die Knowledge Base trennt die Verwaltung der Inhalte von deren Darstellung.

Das grundlegende Prinzip ist:

Navigation
     │
     ▼
 Artikel-ID
     │
     ▼
 Markdown-Datei
     │
     ▼
 Markdown Parser
     │
     ▼
 HTML
     │
     ▼
 Webseite

1. Navigation laden

Beim Aufrufen einer Knowledge Base wird zunächst deren Navigation geladen.

Die Navigation beschreibt die vorhandenen Sections und die darin enthaltenen Artikel.

Beispiel:

sections:
  - id: basics
    title:
      de: Grundlagen
      en: Basics
    items:
      - id: what-is-phishing
      - id: why-phishing-works

2. Artikel auswählen

Wählt der Benutzer einen Artikel aus, wird dessen ID verwendet.

Beispielsweise:

what-is-phishing

Die Anwendung kann anhand dieser ID den entsprechenden Artikel ermitteln.

3. Markdown laden

Der Artikel wird anschließend als Markdown geladen.

Beispiel:

# Was ist Phishing?

Phishing bezeichnet den Versuch, Benutzer durch Täuschung zur
Preisgabe vertraulicher Informationen zu bewegen.

4. Markdown verarbeiten

Der Markdown-Inhalt wird von der Anwendung verarbeitet und in HTML umgewandelt.

Dadurch kann der Inhalt innerhalb der Webseite dargestellt werden.

5. Darstellung

Das erzeugte HTML wird anschließend in das Layout der Knowledge Base eingebettet.

Damit bleiben Navigation, Header und andere Bestandteile der Webseite von den eigentlichen Artikeln getrennt.

Warum diese Trennung?

Die Architektur ermöglicht es, die gleiche Knowledge-Base-Logik für unterschiedliche Quellen zu verwenden.

Heute können die Artikel beispielsweise aus Dateien kommen:

Markdown-Dateien
      │
      ▼
Knowledge Base

Später können die gleichen Inhalte aus einer Datenbank kommen:

Datenbank
   │
   ▼
Knowledge Base

Die Darstellung der Artikel muss sich dadurch nicht grundsätzlich ändern.

Dies ist besonders relevant, wenn Knowledge Bases später von Benutzern erstellt und bearbeitet werden können.

Aufbau einer Knowledge Base

Wie man eine neue Knowledge Base aufbaut und strukturiert.

Aufbau einer Knowledge Base

Eine Knowledge Base besteht aus mehreren Ebenen.

Knowledge Base
│
├── Navigation
│   ├── Section
│   │   ├── Article
│   │   ├── Article
│   │   └── Article
│   │
│   └── Section
│       ├── Article
│       └── Article
│
└── Inhalte
    ├── Markdown
    ├── Metadaten
    └── weitere Informationen

Knowledge Base

Die Knowledge Base ist der übergeordnete Container.

Sie definiert beispielsweise:

  • Namen
  • Beschreibung
  • Sprache
  • Navigation
  • Bereiche
  • enthaltene Artikel

Eine Anwendung kann mehrere Knowledge Bases bereitstellen.

Beispielsweise:

Knowledge Bases
├── IT Security
├── Development
├── Home Server
└── Project Documentation

Sections

Sections gruppieren Artikel thematisch.

Eine Section kann beispielsweise Basics, Detection oder Protection heißen.

Sections enthalten selbst keine eigentlichen Inhalte. Sie verweisen auf die zugehörigen Artikel.

Articles

Artikel enthalten den eigentlichen Inhalt.

Die Artikel werden als Markdown-Dateien gespeichert bzw. verarbeitet.

Ein Artikel kann beispielsweise so aussehen:

what-is-phishing.md

Die Navigation verweist anschließend über eine ID auf diesen Artikel.

Trennung von Navigation und Inhalt

Die Trennung von Navigation und Inhalt hat einen wichtigen Vorteil:

Die Reihenfolge und Gruppierung der Artikel kann geändert werden, ohne den Artikel selbst bearbeiten zu müssen.

Dadurch können Inhalte wiederverwendet und einfacher verwaltet werden.

Knowledge Base erstellen

Wie man eine neue Knowledge Base erstellt.

Eine Knowledge Base erstellen

Eine neue Knowledge Base besteht grundsätzlich aus einer Beschreibung und einer Navigation.

1. Knowledge Base anlegen

Zunächst wird die Knowledge Base selbst definiert.

Dazu gehören beispielsweise:

  • eindeutige ID
  • Titel
  • Beschreibung
  • verfügbare Sprachen
  • Navigation

2. Sections definieren

Anschließend werden die thematischen Bereiche angelegt.

Beispiel:

sections:
  - id: basics
    title:
      de: Grundlagen
      en: Basics

  - id: security
    title:
      de: Sicherheit
      en: Security

3. Artikel hinzufügen

Anschließend werden Artikel erstellt.

Beispiel:

what-is-phishing.md
suspicious-links.md
fake-login-pages.md

Jeder Artikel besitzt eine eindeutige ID.

4. Artikel der Navigation zuordnen

Die Artikel werden anschließend in der Navigation referenziert:

sections:
  - id: basics
    title:
      de: Grundlagen
      en: Basics
    items:
      - id: what-is-phishing
      - id: why-phishing-works

Die Navigation entscheidet damit, wo ein Artikel angezeigt wird.

Ergebnis

Die fertige Knowledge Base besteht somit aus:

Knowledge Base
│
├── Konfiguration
│
├── Navigation
│
└── Artikel
    ├── Artikel 1
    ├── Artikel 2
    └── Artikel 3

Diese Struktur kann später sowohl für fest hinterlegte Knowledge Bases als auch für von Benutzern erstellte Knowledge Bases verwendet werden.

Artikel hinzufügen

Wie man neue Artikel zu einer Knowledge Base hinzufügt.

Artikel hinzufügen

Artikel sind die eigentlichen Inhalte einer Knowledge Base.

Die Inhalte werden in Markdown geschrieben.

Markdown verwenden

Markdown eignet sich besonders gut für Knowledge Bases, weil Inhalte einfach geschrieben und gleichzeitig strukturiert werden können.

Beispiel:

# Verdächtige Links erkennen

Phishing-Nachrichten enthalten häufig Links, die auf gefälschte Webseiten führen.

## Worauf sollte man achten?

- unbekannte Domains
- ungewöhnliche Schreibweisen
- verkürzte URLs
- unerwartete Login-Seiten

Die Anwendung verarbeitet den Markdown-Inhalt und stellt ihn als HTML dar.

Artikel-ID

Jeder Artikel benötigt eine eindeutige ID.

Beispiel:

suspicious-links

Diese ID wird verwendet, um den Artikel mit der Navigation zu verbinden.

Die ID sollte stabil bleiben, da andere Teile der Knowledge Base auf sie verweisen können.

Mehrsprachige Inhalte

Eine Knowledge Base kann mehrere Sprachen unterstützen.

Titel und Navigation können beispielsweise über Sprachvarianten definiert werden:

title:
  de: Verdächtige Links
  en: Suspicious Links

Damit kann die gleiche Knowledge Base unterschiedliche Sprachen bereitstellen.

Artikel organisieren

Wie man Artikel in einer Knowledge Base strukturiert.

Artikel organisieren

Eine Knowledge Base sollte Artikel thematisch strukturieren.

Dafür werden Sections verwendet.

Beispiel

Grundlagen
├── Was ist Phishing?
├── Warum funktioniert Phishing?
└── Arten von Phishing

Phishing erkennen
├── Verdächtige E-Mails
├── Verdächtige Links
└── Gefälschte Login-Seiten

Schutz
├── Passwörter
├── Multi-Faktor-Authentifizierung
└── Browser-Sicherheit

Die Struktur wird über die Navigation definiert.

Reihenfolge

Die Reihenfolge der Artikel in einer Section entspricht grundsätzlich der Reihenfolge in der Navigation.

Dadurch kann die Knowledge Base beispielsweise einen Lernpfad vorgeben:

1. Grundlagen
2. Erkennung
3. Schutz
4. Reaktion

Artikel mehrfach verwenden

Ein Artikel muss nicht zwingend nur an einer Stelle verwendet werden.

Durch die Trennung von Inhalt und Navigation kann ein bestehender Artikel bei Bedarf an mehreren Stellen referenziert werden.

Das vermeidet doppelte Inhalte und erleichtert die Pflege.

Markdown und Darstellung

Wie man Markdown-Inhalte in einer Knowledge Base verarbeitet.

Markdown und Darstellung

Die Inhalte einer Knowledge Base werden in Markdown geschrieben.

Markdown dient dabei als Format für die Speicherung und Bearbeitung der Inhalte.

Speicherung

Ein Artikel kann beispielsweise als Datei gespeichert werden:

articles/
└── suspicious-links.md

Der Inhalt könnte so aussehen:

# Verdächtige Links

Nicht jeder Link in einer E-Mail ist vertrauenswürdig.

## Prüfen

Achte insbesondere auf:

- die Domain
- Schreibfehler
- unerwartete Weiterleitungen

Verarbeitung

Die Anwendung liest den Markdown-Inhalt und übergibt ihn an einen Markdown-Parser.

Markdown
   │
   ▼
Parser
   │
   ▼
HTML

Das erzeugte HTML wird anschließend auf der Webseite dargestellt.

Warum Markdown?

Markdown hat mehrere Vorteile:

  • leicht lesbar
  • einfach zu bearbeiten
  • gut für Versionskontrolle geeignet
  • unabhängig von der eigentlichen Darstellung
  • unterstützt Überschriften, Listen, Tabellen, Links und weitere Elemente

Diagramme

Für Flowcharts und ähnliche Grafiken kannst du Mermaid-Blöcke verwenden. Details und ein Live-Beispiel stehen unter Mermaid-Diagramme.

Zukünftige Erweiterungen

Die Knowledge Base kann später weitere Eingabe- und Ausgabeformate unterstützen.

Beispielsweise:

Markdown → HTML
Markdown → Unicode
Markdown → PDF
Markdown → weitere Formate

Die aktuelle Knowledge Base verwendet zunächst Markdown als Eingabeformat und HTML als Darstellungsformat.

Navigation und Metadaten

Wie man Navigation und Metadaten in einer Knowledge Base definiert.

Die Navigation einer Knowledge Base beschreibt, welche Inhalte verfügbar sind und wie diese strukturiert werden.

Eine Navigation kann beispielsweise so aussehen:

sections:
  - id: basics
    title:
      de: Grundlagen
      en: Basics
    items:
      - id: what-is-phishing
      - id: why-phishing-works

  - id: detection
    title:
      de: Phishing erkennen
      en: Recognizing Phishing
    items:
      - id: suspicious-emails
      - id: suspicious-links

Jede Section besitzt eine eindeutige ID.

id: detection

Die ID wird intern verwendet und sollte nach Möglichkeit stabil bleiben.

Auch jeder Artikel besitzt eine eindeutige ID.

- id: suspicious-links

Über diese ID kann die Anwendung den zugehörigen Inhalt ermitteln.

Titel können sprachabhängig definiert werden:

title:
  de: Verdächtige Links
  en: Suspicious Links

Damit kann die gleiche Knowledge Base mehrere Sprachen unterstützen.

Die technische ID sollte möglichst unabhängig vom sichtbaren Titel sein.

Beispielsweise:

id: suspicious-links

title:
  de: Verdächtige Links
  en: Suspicious Links

Wird der deutsche Titel später geändert, muss die ID nicht geändert werden.

Das verhindert, dass bestehende Verweise auf den Artikel ungültig werden.

Code Provider

Provider-basierte Code-Elemente in Knowledge Bases verwenden.

Code Provider

Knowledge Bases können spezielle Code-Elemente über eine einheitliche Provider-Syntax verwenden.

Die allgemeine Syntax lautet:

{provider:value}

Der erste Teil bestimmt den Provider, der zweite Teil enthält den Wert, der an diesen Provider übergeben wird.

Beispiel:

{material:shield}

Hier ist material der Provider und shield der Wert.

Verwendung

Provider-Code kann an verschiedenen Stellen einer Knowledge Base verwendet werden.

Knowledge-Base-Definition

Provider-Code kann beispielsweise für das Icon einer Knowledge Base verwendet werden:

id: phishing

title:
  de: Phishing Awareness
  en: Phishing Awareness

icon: "{material:security}"

Navigation

Auch Navigationselemente können Provider-Code verwenden:

sections:
  - id: basics
    icon: "{material:menu_book}"
    title:
      de: Grundlagen
      en: Basics
    items:
      - id: what-is-phishing

  - id: detection
    icon: "{material:search}"
    title:
      de: Phishing erkennen
      en: Recognizing Phishing
    items:
      - id: suspicious-emails

Artikel

Auch das Frontmatter eines Artikels kann Provider-Code enthalten:

<!---
id: what-is-phishing
title: Was ist Phishing?
language: de
icon: "{material:help}"
description: Grundlagen und typische Merkmale von Phishing-Angriffen.
date: 2026-10-07
--->

Markdown-Inhalte

Provider-Code kann auch direkt innerhalb des Markdown-Inhalts verwendet werden:

## {material:shield} Schutzmaßnahmen

Mit einigen einfachen Maßnahmen kannst du das Risiko eines erfolgreichen Phishing-Angriffs reduzieren.

Vor der Markdown-Konvertierung wird der Provider-Code aufgelöst.

Provider-Syntax

Die allgemeine Syntax lautet:

{provider:value}

Der Provider wird anhand des Präfixes vor dem : erkannt.

Beispiele:

{material:shield}
{material:search}
{nav:code-provider}

Welcher Inhalt hinter dem : erlaubt ist, hängt vom jeweiligen Provider ab.

Ein Provider kann beispielsweise einfache Namen erwarten:

{material:shield}

oder komplexere Werte:

{nav:code-provider#provider-implementation|Provider implementieren}

Die genaue Syntax wird deshalb in der Dokumentation des jeweiligen Providers beschrieben.

Code Provider

Die Verarbeitung erfolgt zentral über den CodeProvider.

{provider:value}
       │
       ▼
 CodeProvider
       │
       ├── Provider A
       ├── Provider B
       └── Provider C
       │
       ▼
    Ergebnis

Der CodeProvider sucht den registrierten Provider, der die jeweilige Syntax verarbeiten kann.

Dadurch müssen die einzelnen Stellen der Knowledge Base nicht wissen, wie ein bestimmtes Code-Element dargestellt oder verarbeitet wird.

Provider implementieren

Ein Provider implementiert ICodeProvider:

public interface ICodeProvider
{
    string Name { get; }

    bool CanHandle(string value);

    string Process(string value);
}

CanHandle entscheidet, ob der Provider für einen bestimmten Wert zuständig ist.

Process verarbeitet den Wert und erzeugt das entsprechende Ergebnis.

Beispielsweise kann ein Provider anhand seines Präfixes entscheiden:

public bool CanHandle(string value)
{
    return value.StartsWith(
               "{example:",
               StringComparison.OrdinalIgnoreCase)
           && value.EndsWith("}", StringComparison.Ordinal);
}

Der Provider wird anschließend über Dependency Injection registriert:

builder.Services.AddSingleton<ICodeProvider, ExampleProvider>();

Der zentrale CodeProvider erhält alle registrierten Provider und wählt automatisch den passenden Provider aus.

Mehrere Provider

Das System ist bewusst nicht auf einen bestimmten Anwendungsfall beschränkt.

Es können beliebig viele Provider registriert werden.

Beispielsweise:

{material:shield}
{nav:code-provider}
{bootstrap:shield}
{fontawesome:shield}

Jeder Provider kann seine eigene Syntax und Verarbeitung implementieren.

Dadurch bleibt die eigentliche Knowledge-Base-Struktur unabhängig von den konkreten Implementierungen.

Code escapen

Wenn Provider-Code nicht verarbeitet werden soll, kann die öffnende geschweifte Klammer mit einem Backslash escaped werden:

\{material:shield}

Das Ergebnis ist:

{material:shield}

Der Backslash wird bei der Verarbeitung entfernt.

Das ist insbesondere hilfreich, wenn Provider-Syntax selbst dokumentiert oder als Beispiel dargestellt werden soll.

Beispiel

Die Syntax lautet:

\{material:shield}

Dadurch wird die Syntax als normaler Text dargestellt und nicht als Provider verarbeitet.

Codeblöcke und Inline-Code

Provider-Code wird innerhalb von Markdown-Codeblöcken nicht verarbeitet.

Beispiel:

```text
<span class="material-symbols-outlined">shield</span>
<a href="/knowledge/de/HowTo/code-provider">code-provider</a>
```

Die Inhalte bleiben unverändert:

{material:shield}
{nav:code-provider}

Das gilt auch für Inline-Code:

Verwende `{material:shield}` für ein Shield-Icon.

Hier wird {material:shield} ebenfalls als Code dargestellt und nicht verarbeitet.

Damit können Provider-Syntax und Beispiele problemlos innerhalb von Dokumentationen beschrieben werden.

Nicht unterstützte Provider

Wenn kein registrierter Provider die angegebene Syntax unterstützt, kann der Code nicht verarbeitet werden.

Beispiel:

{unknown:shield}

Ein entsprechender Provider muss zunächst implementiert und registriert werden.

Verfügbare Provider

Die konkreten Provider und deren Syntax werden in eigenen Artikeln beschrieben:

  • Material Icons
  • Navigation Provider

Weitere Provider können später ergänzt werden.

Zusammenfassung

Provider-Code verwendet grundsätzlich die Syntax:

{provider:value}

Welcher Provider für einen Wert zuständig ist, wird automatisch anhand der registrierten Provider ermittelt.

Provider können für unterschiedliche Bereiche einer Knowledge Base verwendet werden, beispielsweise für:

  • Knowledge-Base-Metadaten
  • Navigation
  • Artikel-Metadaten
  • Markdown-Inhalte
  • zukünftige Erweiterungen

Soll Provider-Code nur als Text dargestellt werden, kann die Syntax escaped werden:

\{material:shield}

Innerhalb von Inline-Code und Codeblöcken wird Provider-Code nicht verarbeitet.

Neue Provider können hinzugefügt werden, ohne die bestehende Knowledge-Base-Struktur ändern zu müssen.

Material Icons Provider

Google Material Symbols über den Material Provider verwenden.

Material Icons Provider

Der material Provider ermöglicht die Verwendung von Google Material Symbols innerhalb einer Knowledge Base.

Die Syntax lautet:

{material:icon-name}

Beispiel:

{material:shield}

Dabei ist material der Provider und shield der Name des gewünschten Symbols.

Verwendung

Material Icons können an verschiedenen Stellen verwendet werden.

Navigation

sections:
  - id: basics
    icon: "{material:menu_book}"
    title:
      de: Grundlagen
      en: Basics

Artikel

Ein Artikel kann ein Icon im Frontmatter definieren:

<!---
id: what-is-phishing
title: Was ist Phishing?
language: de
icon: "{material:help}"
--->

Markdown

Material Icons können direkt im Markdown verwendet werden:

## {material:shield} Schutzmaßnahmen

Das erzeugt ein entsprechendes Material-Symbol innerhalb der Überschrift.

Verfügbare Symbole

Der Wert hinter material: entspricht dem Namen des gewünschten Symbols.

Beispiele:

{material:home}
{material:search}
{material:menu_book}
{material:shield}
{material:warning}
{material:help}
{material:settings}
{material:info}
{material:code}

Google Material Symbols bietet eine große Auswahl weiterer Symbole.

Symbole finden

Die verfügbaren Symbole können direkt über die Google-Material-Symbols-Dokumentation gesucht werden.

Wichtig ist dabei der Name bzw. die Referenz des Symbols. Dieser Name wird hinter material: verwendet.

Beispiel:

{material:security}

Technische Umsetzung

Der Provider implementiert ICodeProvider:

public sealed class MaterialIconProvider : ICodeProvider
{
    public string Name => "material";

    public bool CanHandle(string value)
    {
        return value.StartsWith(
                   "{material:",
                   StringComparison.OrdinalIgnoreCase)
               && value.EndsWith("}", StringComparison.Ordinal);
    }

    public string Process(string value)
    {
        var name = value["{material:".Length..^1].Trim();

        if (string.IsNullOrWhiteSpace(name))
            return string.Empty;

        return $"""
            <span class="material-symbols-outlined">{name}</span>
            """;
    }
}

Der Provider wird über Dependency Injection registriert:

builder.Services.AddSingleton<ICodeProvider, MaterialIconProvider>();

Google Material Symbols einbinden

Damit die erzeugten Icons dargestellt werden können, muss die Material-Symbols-Schriftart in der Website eingebunden sein:

<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined" rel="stylesheet">

Der Provider selbst kümmert sich nur um die Erzeugung des entsprechenden HTML-Elements.

Beispiele

{material:check}
{material:close}
{material:info}
{material:warning}
{material:security}
{material:shield}
{material:search}

Beispielsweise:

{material:shield}

wird zu:

<span class="material-symbols-outlined">shield</span>

Escaping

Soll ein Provider-Ausdruck nur als Text dargestellt werden, kann er escaped werden:

\{material:shield}

Das Ergebnis ist:

{material:shield}

Innerhalb von Codeblöcken und Inline-Code wird die Syntax ebenfalls nicht verarbeitet.

Navigation Provider

Mit dem Navigation Provider auf andere Artikel und Abschnitte verlinken.

Der nav Provider ermöglicht es, innerhalb von Knowledge-Base-Artikeln auf andere Artikel zu verlinken.

Die grundlegende Syntax lautet:

{nav:article-id}

Beispiel:

{nav:code-provider}

Der Link verweist auf den Artikel code-provider innerhalb der aktuellen Knowledge Base.

Der Linktext kann nach einem | angegeben werden:

{nav:code-provider|Code Provider}

Dadurch wird nicht die Artikel-ID als Linktext verwendet, sondern:

Code Provider

Die allgemeine Syntax lautet:

{nav:article-id|Linktext}

Der Navigation Provider unterstützt auch Links auf einen bestimmten Anchor innerhalb eines Artikels.

Dazu wird der Anchor mit # an die Artikel-ID angehängt:

{nav:code-provider#provider-implementation}

Damit kann beispielsweise direkt auf den Abschnitt Provider implementieren verwiesen werden.

Artikel und Linktext können kombiniert werden:

{nav:code-provider#provider-implementation|Provider implementieren}

Das ist besonders praktisch für Verweise innerhalb von Fließtext.

Beispiel:

Weitere Informationen findest du unter
{nav:code-provider#provider-implementation|Provider implementieren}.

Ein einfacher Verweis auf einen Artikel:

Siehe auch {nav:code-provider|Code Provider}.

Oder ohne eigenen Linktext:

Siehe auch {nav:code-provider}.

Der Provider implementiert ICodeProvider:

public sealed class NavigationCodeProvider : ICodeProvider
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public NavigationCodeProvider(
        IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public string Name => "nav";

    public bool CanHandle(string value)
    {
        return value.StartsWith(
                   "{nav:",
                   StringComparison.OrdinalIgnoreCase)
               && value.EndsWith("}", StringComparison.Ordinal);
    }

    // ...
}

Der Provider ermittelt die aktuelle Knowledge Base aus der aktuellen Route und erzeugt daraus die entsprechende URL.

Dadurch muss in einem Artikel keine vollständige URL angegeben werden.

Ohne Provider müsste ein Artikel beispielsweise eine vollständige URL enthalten:

[Code Provider](/knowledge/language/phishing/code-provider)

Das hat einige Nachteile:

  • die Knowledge-Base-ID ist fest im Inhalt enthalten
  • URLs müssen manuell gepflegt werden
  • Änderungen an der Routing-Struktur müssen in Artikeln angepasst werden
  • Inhalte sind stärker an die konkrete Website gebunden

Mit dem Navigation Provider reicht:

{nav:code-provider|Code Provider}

Der Provider erzeugt die URL automatisch.

Für einen Abschnitt kann beispielsweise verwendet werden:

{nav:code-provider#provider-implementation|Provider implementieren}

Der resultierende Link verweist auf:

/knowledge/{knowledgeBaseId}/code-provider#provider-implementation

Damit bleiben die eigentlichen Markdown-Inhalte unabhängig von der konkreten Knowledge-Base-URL.

Die wichtigsten Varianten sind:

{nav:article-id}
{nav:article-id|Linktext}
{nav:article-id#anchor}
{nav:article-id#anchor|Linktext}

Beispiele:

{nav:code-provider}
{nav:code-provider|Code Provider}
{nav:code-provider#provider-implementation}
{nav:code-provider#provider-implementation|Provider implementieren}

Der Navigation Provider eignet sich damit sowohl für einfache Artikelverweise als auch für Querverweise auf konkrete Abschnitte innerhalb anderer Artikel.

SEO für Knowledge-Base-Inhalte

SEO-Metadaten für Knowledge-Base-Seiten und Artikel definieren und automatisch für Seitenkopf und Sitemap verwenden.

SEO für Knowledge-Base-Inhalte

Knowledge Bases können eigene SEO-Definitionen für Seiten und Artikel verwenden.

Die SEO-Definitionen werden als JSON-Dateien direkt neben den jeweiligen Inhalten abgelegt. Beim Start der Anwendung werden diese automatisch geladen.

Die Definitionen werden anschließend für:

  • den <head> der Seite
  • den Seitentitel
  • die Meta Description
  • Canonical URLs
  • Open Graph
  • JSON-LD
  • die Sitemap
  • Sprachalternativen über hreflang

verwendet.

SEO-Dateien

Für mehrsprachige Inhalte wird für jede Sprache eine eigene SEO-Datei angelegt.

Bei einer Knowledge-Base-Seite wie phishing sieht die Struktur beispielsweise so aus:

Content/
└── Knowledge/
    └── Phishing/
        ├── seo.de.json
        ├── seo.en.json
        ├── suspicious-emails.md
        ├── suspicious-emails.de.seo.json
        └── suspicious-emails.en.seo.json

Die Dateinamen folgen dabei diesen Regeln.

Knowledge-Base

seo.<language>.json

Beispiele:

seo.de.json
seo.en.json

Artikel

<article-id>.<language>.seo.json

Beispiele:

suspicious-emails.de.seo.json
suspicious-emails.en.seo.json

SEO-Format

Eine SEO-Definition verwendet Schema.org als Grundlage.

Beispiel: seo.de.md ► seo.de.seo.json

{
  "@context": "https://schema.org",
  "@type": "Article",
  "language": "de",
  "key": "knowledge/de/HowTo/seo",
  "groupKey": "knowledge/HowTo/seo",
  "headline": "SEO für Knowledge-Base-Inhalte",
  "description": "Erfahren Sie, wie SEO-Metadaten für Knowledge-Base-Seiten und Artikel definiert und automatisch für Seitenkopf, strukturierte Daten und Sitemap verwendet werden.",
  "url": "https://robin-peters.dev/knowledge/de/HowTo/seo",
  "author": {
    "@type": "Person",
    "name": "Robin Peters",
    "url": "https://robin-peters.dev/"
  },
  "publisher": {
    "@type": "Person",
    "name": "Robin Peters",
    "url": "https://robin-peters.dev/"
  },
  "inLanguage": "de",
  "keywords": [
    "SEO",
    "Knowledge Base SEO",
    "Knowledgebase SEO",
    "SEO Metadaten",
    "SEO JSON",
    "Schema.org",
    "JSON-LD",
    "Sitemap",
    "hreflang",
    "mehrsprachige Webseiten",
    "SEO für Artikel",
    "Suchmaschinenoptimierung"
  ]
}

Eigenschaften

@context

Gibt den verwendeten Schema.org-Kontext an.

"@context": "https://schema.org"

Dieser Wert sollte normalerweise nicht verändert werden.

@type

Definiert den Typ des Inhalts.

"@type": "Article"

Für Knowledge-Base-Inhalte kann beispielsweise Article verwendet werden.

language

Gibt die Sprache der SEO-Definition an.

"language": "de"

Beispiele sind de und en.

key

Der eindeutige Schlüssel der konkreten Seite.

"key": "knowledge/de/phishing"

Bei einem Artikel kann der Schlüssel beispielsweise so aussehen:

"key": "knowledge/de/phishing/suspicious-emails"

Der Key muss innerhalb der Knowledge Base eindeutig sein.

groupKey

Der groupKey verbindet verschiedene Sprachversionen derselben Seite.

Die deutsche Version verwendet beispielsweise:

"groupKey": "knowledge/phishing"

Die englische Version verwendet denselben Wert:

"groupKey": "knowledge/phishing"

Die konkreten key-Werte unterscheiden sich dagegen:

knowledge/de/phishing
knowledge/en/phishing

Der groupKey bleibt gleich.

Dadurch kann die Anwendung automatisch erkennen, dass beide Seiten zusammengehören und entsprechende hreflang-Verweise erzeugen.

Für einen Artikel kann der groupKey beispielsweise so aussehen:

"groupKey": "knowledge/phishing/suspicious-emails"

headline

Der Titel der Seite.

"headline": "Phishing erkennen"

Der Wert wird unter anderem für den HTML-<title> und Open Graph verwendet.

Der Titel sollte den Inhalt der Seite möglichst präzise beschreiben.

description

Eine kurze Beschreibung des Inhalts.

"description": "Erfahren Sie, wie Sie Phishing erkennen und sich vor Phishing-Angriffen schützen."

Die Beschreibung sollte den tatsächlichen Inhalt der Seite zusammenfassen und relevante Suchbegriffe natürlich enthalten.

url

Die öffentliche URL der Seite.

"url": "https://robin-peters.dev/knowledge/de/Phishing"

Diese URL wird unter anderem als Canonical URL und für die Sitemap verwendet.

Die URL muss der tatsächlich erreichbaren öffentlichen URL entsprechen.

author

Der Autor des Inhalts.

"author": {
  "@type": "Person",
  "name": "Robin Peters",
  "url": "https://robin-peters.dev/"
}

publisher

Der Herausgeber des Inhalts.

"publisher": {
  "@type": "Person",
  "name": "Robin Peters",
  "url": "https://robin-peters.dev/"
}

inLanguage

Die Sprache des eigentlichen Inhalts.

"inLanguage": "de"

Sie sollte mit language übereinstimmen.

keywords

Relevante Suchbegriffe für den Inhalt.

"keywords": [
  "Phishing",
  "Phishing erkennen",
  "verdächtige E-Mails",
  "Cybersecurity"
]

Die Keywords werden als Bestandteil der strukturierten Daten verwendet.

Es ist nicht notwendig, jedes mögliche Suchwort aufzunehmen. Relevante und zum Inhalt passende Begriffe sind sinnvoller.

Mehrsprachige Inhalte

Für jede Sprache wird eine eigene SEO-Datei angelegt.

Beispiel:

Phishing/
├── seo.de.json
└── seo.en.json

Beide Definitionen haben unterschiedliche key- und Sprachwerte:

knowledge/de/phishing
knowledge/en/phishing

Der groupKey ist identisch:

knowledge/phishing

Dadurch kann die Anwendung die Sprachversionen automatisch miteinander verknüpfen.

Artikel

Artikel verwenden dieselbe Struktur.

Beispiel:

Phishing/
├── suspicious-emails.md
├── suspicious-emails.de.seo.json
└── suspicious-emails.en.seo.json

Die deutsche Definition verwendet:

"key": "knowledge/de/phishing/suspicious-emails"
"groupKey": "knowledge/phishing/suspicious-emails"

Die englische Definition verwendet:

"key": "knowledge/en/phishing/suspicious-emails"
"groupKey": "knowledge/phishing/suspicious-emails"

Der groupKey verbindet beide Artikel miteinander.

Sitemap

SEO-Definitionen werden automatisch für die Sitemap verwendet.

Eine Seite wird in die Sitemap aufgenommen, sobald eine gültige SEO-Definition mit einer url vorhanden ist.

Die Sitemap muss dadurch nicht manuell gepflegt werden.

Bei mehrsprachigen Seiten werden anhand des groupKey automatisch die verfügbaren Sprachalternativen erkannt und als hreflang-Links in der Sitemap ausgegeben.

Eine neue öffentlich zugängliche Seite benötigt daher lediglich eine passende SEO-Definition.

Zusammenfassung

Für eine mehrsprachige Knowledge-Base-Seite:

seo.de.json
seo.en.json

Für einen mehrsprachigen Artikel:

article.de.seo.json
article.en.seo.json

Dabei gilt:

key      = konkrete Seite
groupKey = gemeinsame Seite über mehrere Sprachen
language = Sprache der Definition
url      = öffentliche URL

Die SEO-Dateien werden automatisch geladen und müssen nicht zusätzlich in einer zentralen Konfiguration registriert werden.