Ich beschäftige mich in letzter Zeit intensiv mit Fumadocs. Der Funktionsumfang ist von Haus aus bereits solide, aber ich habe ein paar Anpassungen vorgenommen, um die Handhabung noch komfortabler zu machen. Hoffentlich ist das ein oder andere davon nützlich, wenn du dein eigenes Setup verbessern möchtest.

Fumadocs anpassen: Einige neue Funktionen, die ich hinzugefügt habe

Eine YouTube-Embed-Komponente

Mit der Komponente <YouTubeEmbed> kannst du YouTube-Videos sicher einbinden.

mdx
<YouTubeEmbed videoId="LX6A3OmY4uk" title="Video Title" />

Diese Komponente bietet einige praktische Eigenschaften:

  • Responsive (behält ein Seitenverhältnis von 16:9 bei)
  • Setzt automatisch die korrekten Sicherheitsattribute
  • Leistungsoptimiert (Lazy Loading)

Eine UI-Pfad-Anzeige-Komponente

Die Komponente <UiPath> ermöglicht es dir, eine Abfolge von UI-Schritten visuell darzustellen.

mdx
<UiPath>Email activity > Has a hard bounced delivery > Yes</UiPath>

Diese Komponente bietet einige praktische Eigenschaften:

  • Parst automatisch Pfade, die durch > getrennt sind
  • Rendert jeden Schritt als Badge (Chip)
  • Hebt den letzten Schritt mit einem „aktiven“ Stil hervor (blauer Hintergrund)
  • Trennt Schritte mit einem Pfeil (›)

Das Styling ist in app/globals.css definiert und verwendet die folgenden Klassen:

  • .ui-chip: der Standard-Chip-Stil (grauer Hintergrund)
  • .ui-chip.is-active: der aktive Chip-Stil (blauer Hintergrund)
  • .ui-sep: Styling für das Trennzeichen (›)

Artikeldatumsanzeige und Warnungen für veraltete Artikel

Wenn du in den Frontmatter-Daten einer MDX-Datei created und updated festlegst, zeigt die Artikel-Seitenansicht automatisch das Erstellungs- und Aktualisierungsdatum an.

mdx
---
title: Article Title
created: 2021-04-18
updated: 2024-02-28
---
  • created: das Erstellungsdatum des Artikels
  • updated: das Datum der letzten Aktualisierung des Artikels (wird nicht angezeigt, wenn es mit dem Erstellungsdatum übereinstimmt)

Außerdem zeigt jeder Artikel, der seit über einem Jahr nicht mehr aktualisiert wurde, automatisch die folgende Warnung an:

Dieser Artikel wurde seit über einem Jahr nicht mehr aktualisiert. Die Informationen hier sind möglicherweise nicht mehr aktuell…

Dies ist in components/article-dates.tsx implementiert und wird direkt unter dem Artikeltitel gerendert.

Anzeige verwandter Artikel

Mit der Komponente <RelatedArticles> kannst du verwandte Artikel innerhalb eines Beitrags anzeigen.

mdx
<RelatedArticles related="blog-japanese,css,embed-html" />

Funktionen:

  • Dateinamen-Slugs (z. B. blog-japanese) durch Kommas getrennt angeben
  • Funktioniert sowohl mit Ordnern in Klammern ((pagecreate)/blog-japanese.mdx) als auch mit regulären Ordnern (payment/cant-free-trial.mdx)
  • Zeigt den Titel jedes Artikels und ein Kategorie-Badge an
  • Kartendesign im Codeblock-Stil mit weißem Hintergrund
  • Ein Zap-Symbol neben der Überschrift und ein NotebookText-Symbol neben jedem Artikel
  • Keine Unterstreichung bei Links, dafür ein Farbwechsel beim Hovern

Beispielverwendung:

mdx
---
title: Creating a Blog Post
---

## Body

Here are some related articles.

<RelatedArticles related="blog-japanese,css,embed-html" />

Es funktioniert auch problemlos mit Leerzeichen um die Kommas herum:

mdx
<RelatedArticles related="blog-japanese, css, embed-html" />

Implementierungsdateien:

  • components/related-articles.tsx: die Komponente zur Anzeige verwandter Artikel
  • lib/getPageBySlug.ts: eine Hilfsfunktion zum Abrufen einer Seite anhand ihres Slugs
    • getPageBySlug(slug): ruft eine einzelne Seite von einem Slug ab
    • getPagesBySlugs(slugs): ruft mehrere Seiten von einer Liste von Slugs ab
    • getCategoryTitleFromPage(page): ermittelt den Kategorietitel von einer Seite

Technische Details:

  • Zwischenspeicherung (Caching) der Slug-zu-Seite-Zuordnung zur Leistungsoptimierung
  • Ermittelt die Kategorie automatisch aus dem Dateipfad (einschließlich Ordnern in Klammern)
  • Kategorieinformationen werden aus meta.json oder index.mdx über einen In-Memory-Cache bezogen

Funktionen der Startseite

Auf der Startseite (content/docs/index.mdx) sind die folgenden Funktionen implementiert.

Kürzlich hinzugefügte und kürzlich aktualisierte Artikel

Zeigt Artikel an, bei denen created oder updated im Frontmatter gesetzt ist, sortiert nach Datum.

mdx
import { RecentCreatedPosts, RecentUpdatedPosts } from '@/components/recent-posts';

## Recently Added Articles

<RecentCreatedPosts limit={10} />

## Recently Updated Articles

<RecentUpdatedPosts limit={10} />

Funktionen:

  • Jeder Artikel wird als Karte mit Hover-Effekt angezeigt
  • Vor jedem Artikeltitel erscheint ein FileText-Symbol
  • Kategorie-Badges werden angezeigt (z. B. Abrechnung, Produkte/Lektionen)
  • Daten werden nicht angezeigt – es handelt sich um ein einfaches Listenformat

Implementierungsdateien:

  • components/recent-posts.tsx: die Artikellisten-Anzeigekomponente
  • lib/recent-posts.ts: die Funktionen zum Abrufen von Artikeln (getRecentCreatedPosts, getRecentUpdatedPosts)

Ausgewählte Themen & Artikel (Kategoriebasierte Anzeige)

Eine Shortcode-Komponente, die bis zu 5 Artikel pro Kategorie anzeigt.

mdx
import { CategoryPosts } from '@/components/category-posts';

## Featured Topics & Articles

<CategoryPosts category="payment" limit={5} />

<CategoryPosts category="product" limit={5} />

<CategoryPosts category="students" limit={5} />

Funktionen:

  • Kategorienamen werden als Links angezeigt, und ein Klick darauf leitet zur Kategorieseite weiter
  • Vor jedem Artikel erscheint ein BookText-Symbol
  • Artikel werden nach der aktuellsten Aktualisierung sortiert (oder nach dem Erstellungsdatum, falls kein Aktualisierungsdatum vorhanden ist)
  • Du kannst die Reihenfolge der Abschnitte ändern, indem du die Reihenfolge der <CategoryPosts />-Aufrufe in der MDX-Datei anpasst

Ein gemeinsamer Footer wird auf der gesamten Website angezeigt. Dieser ist in components/footer.tsx implementiert.

Layout:

  • Ein responsives Design mit zwei Spalten (nebeneinander auf großen Bildschirmen, untereinander auf Mobilgeräten)
  • Linke Spalte: Website-Logo, Beschreibung, Social-Media-Symbole und Infos zum angemeldeten Benutzer
  • Rechte Spalte: Website-Hinweise (Nutzungsbedingungen, Update-Informationen usw.)

Inhalt der linken Spalte:

  • Website-Titel (verlinkt auf /docs)
  • Website-Beschreibung
  • Social-Media-Symbole (GitHub, Discord, YouTube, Twitter/X)
  • Infos zum angemeldeten Benutzer (Platzhalter)
    • „Angemeldet“-Status
    • Anzeige des Benutzernamens
    • Schaltflächen zum Abmelden / Passwort ändern

Inhalt der rechten Spalte:

  • Website-Beschreibung und Hinweise
  • Ein Hinweis darauf, wie Informationen aktualisiert werden
  • Ein Hinweis darauf, wie neue Artikel hinzugefügt werden

Implementierungsdateien:

  • components/footer.tsx: die Footer-Komponente
  • app/layout.tsx: fügt den Footer zum Root-Layout hinzu

Der Footer wird automatisch auf jeder Seite angezeigt und verwendet die Theme-Variablen von Fumadocs für das Styling.