Astro Markdown Fortgeschritten: 7 Praxis-Tipps für ein 10x professionelleres Blog

Sie haben gerade Ihr Blog mit Astro aufgesetzt und schreiben den ersten Tech-Artikel. Eine bestimmte Codezeile hervorheben? Geht nicht. Einen einklappbaren Warnhinweis einfügen? Unmöglich. Eine mathematische Formel in der Algorithmus-Erklärung? Keine Ahnung, wie.

Mir ging es genauso. Nach ein paar Artikeln in reinem Markdown merkte ich: Der Ausdrucksspielraum ist viel zu klein. Andere Tech-Blogs zeigen hervorgehobene Codezeilen, Vorher-Nachher-Vergleiche und interaktive Komponenten – ich konnte nur trockenen Code einfügen.

Zum Glück bietet Astro MDX als „erweitertes Markdown“. Kurz gesagt: Mit MDX nutzen Sie beim Schreiben Komponenten und JSX – die Möglichkeiten vervielfachen sich.

In diesem Artikel teile ich 7 fortgeschrittene Astro Markdown/MDX-Techniken: vom Basis-Setup über Code-Highlighting und eigene Komponenten bis zu Formeln und Diagrammen. Jeder Tipp kommt mit vollständigem Code und Konfigurationsschritten. Danach hebt sich Ihr Tech-Blog von „brauchbar“ auf „professionell“.

Teil 1: Basis-Upgrade – von Markdown zu MDX

Warum MDX?

Der Unterschied zwischen Markdown und MDX ist wie zwischen Fahrrad und E-Bike – beide fahren, das Erlebnis ist aber ganz anders.

Reines Markdown erlaubt nur statische Inhalte: Text, Codeblöcke, Bilder. Einen Hinweis-Kasten? Nur mit HTML-Hardcoding. Eine interaktive Komponente im Artikel? Praktisch unmöglich.

MDX ist anders – „Markdown + JSX“. Sie können:

• Komponenten importieren und nutzen: In .mdx-Dateien beliebige Astro-, React- oder Vue-Komponenten importieren
• JSX-Ausdrücke schreiben: Mit {variable} Variablen einfügen, sogar Schleifen und Bedingungen
• Element-Stile anpassen: Standard-<h1> durch eigene gestylte Komponenten ersetzen

Ein konkretes Beispiel. Sie wollen einen Warnhinweis – mit reinem Markdown so:

<div class="warning">
  <p>Achtung: Dieser Vorgang löscht alle Daten!</p>
</div>

Mit MDX so:

import Alert from '@/components/Alert.astro';

<Alert type="warning">
  Achtung: Dieser Vorgang löscht alle Daten!
</Alert>

Der Unterschied? Mit MDX bauen Sie Artikel wie aus Bausteinen – statt ständig HTML zu schreiben.

MDX in 5 Minuten einrichten

Die Einrichtung ist denkbar einfach – drei Schritte.

Schritt 1: Integration installieren

Im Astro-Projekt im Terminal:

npx astro add mdx

Die Astro-CLI installiert @astrojs/mdx und aktualisiert die Config. Bei den Rückfragen (Config aktualisieren, Abhängigkeiten installieren) einfach Yes wählen.

Schritt 2: Konfiguration prüfen

In astro.config.mjs sollte etwa Folgendes stehen:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
});

Falls nicht automatisch ergänzt, manuell hinzufügen.

Schritt 3: MDX testen

Unter src/pages/ oder src/content/ eine test.mdx anlegen:

---

title: MDX-Test

---

# Das ist ein MDX-Test

Normaler Markdown-Text.

export const greeting = "Hallo";

Jetzt mit Variable: {greeting}!

<div style="padding: 1rem; background: #f0f0f0;">
  Das ist ein JSX-Element
</div>

npm run dev starten und die Seite aufrufen. Wenn Variable und JSX-Element sichtbar sind, funktioniert MDX.

Koexistenz von .md und .mdx

Nach der MDX-Integration funktionieren .md-Dateien weiterhin normal. Astro wählt anhand der Endung:

• .md: Standard-Markdown
• .mdx: MDX mit Komponenten und JSX

Mein Tipp: Normale Artikel als .md, Artikel mit Komponenten als .mdx. Nicht jeder Artikel braucht MDX.

Teil 2: Fortgeschrittenes Code-Highlighting

Highlighting-Theme konfigurieren (Shiki)

Astro nutzt standardmäßig Shiki – schon sehr gut. Das Default-Theme ist github-dark; vielleicht passt ein anderes besser zu Ihrem Blog.

Shiki oder Prism?

Ich empfehle Shiki. Es ist Astros Standard, unterstützt über 100 Sprachen und Themes und rendert serverseitig – ohne extra JavaScript. Prism geht auch, braucht aber CSS-Dateien und ist etwas aufwändiger.

Built-in-Theme wechseln

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

In astro.config.mjs unter markdown shikiConfig setzen:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    shikiConfig: {
      theme: 'dracula', // z. B. github-dark, nord, monokai, dracula
    },
  },
});

Beliebte Themes:

• github-dark / github-light – GitHub-Stil
• dracula – klassisches Lila-Schwarz
• nord – kühler Nordstil
• one-dark-pro – VSCode-Dark-Default

Themes finden Sie in der Shiki-Theme-Vorschau.

Hell/Dunkel mit zwei Themes

Bei Hell-Dunkel-Umschaltung können Sie zwei Themes konfigurieren:

markdown: {
  shikiConfig: {
    themes: {
      light: 'github-light',
      dark: 'github-dark',
    },
  },
},

Shiki wendet dann je nach prefers-color-scheme oder Ihrer Theme-Logik das passende Highlighting an.

Bestimmte Zeilen und Code-Kommentare hervorheben

In Tutorials markieren Sie oft wichtige Zeilen oder zeigen Änderungen. Shiki Transformers machen das möglich.

Wichtige Zeilen hervorheben

Shiki Transformers installieren:

npm install shiki

In der Config transformerNotationHighlight aktivieren:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { transformerNotationHighlight } from '@shikijs/transformers';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    shikiConfig: {
      theme: 'github-dark',
      transformers: [transformerNotationHighlight()],
    },
  },
});

Im Codeblock mit // [!code highlight] markieren:

```javascript
function hello() {
  console.log('Normale Zeile');
  console.log('Diese Zeile wird hervorgehoben'); // [!code highlight]
}
```

Code-Änderungen im Diff-Stil

Für Vorher/Nachher transformerNotationDiff:

import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers';

markdown: {
  shikiConfig: {
    theme: 'github-dark',
    transformers: [
      transformerNotationHighlight(),
      transformerNotationDiff(),
    ],
  },
},

Verwendung:

```javascript
function calculate(a, b) {
  return a + b; // [!code --]
  return a * b; // [!code ++]
}
```

Zeilen mit -- erscheinen rot (entfernt), mit ++ grün (neu). Sehr praktisch für Code-Tutorials.

Fokus auf bestimmten Code

Mit transformerNotationFocus wird der Rest ausgegraut:

import { transformerNotationFocus } from '@shikijs/transformers';

// Zum transformers-Array hinzufügen
transformers: [
  transformerNotationFocus(),
],

Mit // [!code focus] markieren:

```javascript
function process() {
  console.log('Diese Zeile wird ausgegraut');
  console.log('Diese Zeile normal'); // [!code focus]
  console.log('Auch ausgegraut');
}
```

Upgrade auf Expressive Code (optional)

Wenn Shiki nicht reicht: Expressive Code – Community-Erweiterung mit mehr Features out of the box:

• Codeblock-Titel
• Kopieren-Button
• Zeilennummern
• Terminal-Fenster-Stil
• Side-by-Side-Vergleich

Installation

npx astro add astro-expressive-code

Die CLI konfiguriert alles automatisch – Codeblöcke haben danach diese Features ohne Extra-Setup.

Wann Expressive Code?

Ich startete mit Shiki, wechselte zu Expressive Code, als Leser oft Code kopieren wollten. Für Tutorial-Blogs mit viel Code deutlich bessere UX.

Bei gelegentlichem Code reicht Shiki + Transformers – weniger Abhängigkeiten.

Teil 3: Eigene Komponenten einbetten

Komponenten in MDX importieren und nutzen

MDXs Stärke: Komponenten direkt im Artikel. Ich nutze das für Hinweis-Boxen, Code-Vergleiche, einklappbare Bereiche.

Warnbox-Komponente erstellen

Unter src/components/ eine Alert.astro:

---

interface Props {
  type?: 'info' | 'warning' | 'error';
}

const { type = 'info' } = Astro.props;

const styles = {
  info: 'bg-blue-50 border-blue-200 text-blue-800',
  warning: 'bg-yellow-50 border-yellow-200 text-yellow-800',
  error: 'bg-red-50 border-red-200 text-red-800',
};

---

<div class={`border-l-4 p-4 ${styles[type]}`}>
  <slot />
</div>

In MDX-Artikel verwenden

In der .mdx-Datei importieren und nutzen:

---

title: Mein Tech-Artikel

---

import Alert from '@/components/Alert.astro';

# Artikel-Titel

Normaler Artikeltext.

<Alert type="warning">
  Achtung: Vor diesem Befehl Daten sichern!
</Alert>

<Alert type="info">
  Tipp: In der Komponente funktioniert auch **Markdown** – sehr praktisch.
</Alert>

In <Alert> können Sie weiter Markdown (Fett, Links usw.) nutzen – MDX verarbeitet das automatisch.

React/Vue-Komponenten

MDX unterstützt nicht nur Astro, sondern auch React, Vue usw. – mit client:-Direktive:

import Counter from '@/components/Counter.tsx';

<Counter client:load initialCount={0} />

client:load lädt die Komponente beim Seitenaufruf im Client. Ohne Direktive nur SSR – Interaktion funktioniert nicht.

Komponenten-Organisation

Ich lege Artikel-Komponenten unter src/components/mdx/:

src/
├── components/
│   ├── mdx/
│   │   ├── Alert.astro
│   │   ├── CodeCompare.astro
│   │   ├── Callout.astro
│   │   └── Tabs.astro
│   └── ...weitere Komponenten

Markdown-Syntax auf eigene Komponenten mappen

Etwas „Magie“: Standard-Markdown-Elemente (h1, a, img) durch eigene Komponenten ersetzen.

Warum?

Allen Überschriften Anker-Icons geben oder externen Links automatisch „↗“ – manuell zu mühsam. Mit Mapping gilt es beim normalen Markdown-Schreiben automatisch.

Praxis: Eigene Überschrift-Komponente

Railway - Moderne Deployment-Plattform, ohne DevOps-Aufwand, in Minuten live

Jetzt starten →Anzeige

CustomHeading.astro erstellen:

---

interface Props {
  level: 1 | 2 | 3 | 4 | 5 | 6;
  id?: string;
}

const { level, id } = Astro.props;
const Tag = `h${level}` as any;

---

<Tag id={id} class="group relative">
  <slot />
  {id && (
    <a href={`#${id}`} class="ml-2 opacity-0 group-hover:opacity-100 transition-opacity">
      #
    </a>
  )}
</Tag>

Mapping in MDX

In der .mdx-Datei ein components-Objekt exportieren:

---

title: Artikel-Titel

---

import CustomHeading from '@/components/CustomHeading.astro';

export const components = {
  h2: (props) => <CustomHeading level={2} {...props} />,
  h3: (props) => <CustomHeading level={3} {...props} />,
};

## Das ist eine H2-Überschrift

Beim Hover erscheint der #-Anker.

### Das ist eine H3-Überschrift

Alle h2 und h3 nutzen automatisch das Custom-Styling.

Praxis: Icon bei externen Links

ExternalLink.astro:

---

interface Props {
  href?: string;
}

const { href } = Astro.props;
const isExternal = href?.startsWith('http');

---

<a href={href} target={isExternal ? '_blank' : undefined} rel={isExternal ? 'noopener noreferrer' : undefined}>
  <slot />
  {isExternal && <span class="ml-1 text-xs">↗</span>}
</a>

Mapping:

import ExternalLink from '@/components/ExternalLink.astro';

export const components = {
  a: ExternalLink,
};

[Interner Link](/about)
[Externer Link](https://example.com) ← automatisch mit ↗

Globales Mapping (fortgeschritten)

Für alle MDX-Dateien dasselbe Mapping: in astro.config.mjs per Custom-MDX-Plugin – etwas komplexer; meist reicht Mapping pro Datei.

Teil 4: Formeln und Diagramme

KaTeX für mathematische Formeln

Bei Algorithmen, Mathe oder Data Science brauchen Sie Formeln. KaTeX ist schneller als MathJax und unterstützt SSR.

KaTeX installieren

Drei Pakete:

npm install remark-math rehype-katex katex

• remark-math: LaTeX-Syntax parsen
• rehype-katex: Formeln als HTML rendern
• katex: KaTeX-Kernbibliothek

Astro konfigurieren

In astro.config.mjs beide Plugins:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
});

KaTeX-CSS einbinden

Wichtig – sonst keine Darstellung. Im Layout (z. B. src/layouts/MarkdownLayout.astro) im <head>:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"
  crossorigin="anonymous"
/>

Formeln im Artikel

Inline (ein $):

Massen-Energie-Äquivalenz: $E = mc^2$

Quadratische Gleichung: $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

Block (doppeltes $$):

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

Häufiges Problem: Formeln fehlen

Prüfen Sie:

1. KaTeX-CSS korrekt eingebunden? (F12 → Network)
2. rehype-katex-Version kompatibel? (ggf. 6.x testen)
3. LaTeX-Syntax korrekt? (KaTeX-Unterstützung)

Mermaid für Fluss- und Diagramme

Mermaid zeichnet Flussdiagramme, Sequenzdiagramme, Gantt-Charts per Code – ideal für Tech-Docs.

Drei Integrationsoptionen

Empfehlung: rehype-mermaid – SSR, SEO-freundlich, statisches SVG.

rehype-mermaid installieren

npm install rehype-mermaid

Konfiguration

In astro.config.mjs:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import rehypeMermaid from 'rehype-mermaid';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    rehypePlugins: [
      [rehypeMermaid, { strategy: 'img-svg' }]
    ],
  },
});

strategy: 'img-svg' erzeugt SVG-Bilder – stabilste Variante.

Diagramme im Artikel

Mit mermaid-Codeblock:

Flussdiagramm:

```mermaid
graph TD
    A[Start] --> B{MDX installiert?}
    B -->|Ja| C[Code-Highlighting konfigurieren]
    B -->|Nein| D[MDX installieren]
    D --> C
    C --> E[Fertig]
```

Sequenzdiagramm:

```mermaid
sequenceDiagram
    Nutzer->>Browser: Seite aufrufen
    Browser->>Server: HTML anfordern
    Server->>Browser: Gerenderte Seite
    Browser->>Nutzer: Inhalt anzeigen
```

Beim Build

Bei npm run build werden Mermaid-Diagramme als SVG generiert – statische Bilder, schnell, ohne Client-JavaScript.

Hinweise

Build-Fehler „Puppeteer nicht gefunden“? Playwright installieren:

npm install -D playwright

Oder astro-diagram mit eingebauter Browser-Umgebung.

Vultr - Hochleistungs-NVMe-Cloud-Server mit 32 Standorten weltweit, Docker per Klick

Preise ansehen →Anzeige

Teil 5: Fortgeschrittene Tipps und Best Practices

MDX-Optimierung in Content Collections

Mit Astros Content Collections (stark empfohlen) erhalten MDX-Dateien bessere Typen und DX.

Was sind Content Collections?

Artikel unter src/content/, Astro erkennt und validiert Frontmatter und bietet typsichere APIs.

Content Collections konfigurieren

In src/content/config.ts:

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content', // Markdown/MDX-Inhalt
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    tags: z.array(z.string()).optional(),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

In MDX nutzen

Frontmatter wird automatisch validiert:

---

title: Astro MDX Fortgeschritten
description: MDX-Advanced-Features lernen
pubDate: 2025-12-02
tags: [Astro, MDX, Tutorial]

---

import Alert from '@/components/Alert.astro';

# {frontmatter.title}

<Alert type="info">
  Veröffentlichung: {frontmatter.pubDate.toLocaleDateString()}
</Alert>

Inhaltsverzeichnis automatisch

Content Collections bietet getHeadings() für alle Überschriften:

---

import { getEntry } from 'astro:content';

const entry = await getEntry('blog', 'my-mdx-article');
const { Content, headings } = await entry.render();

---

<aside>
  <h2>Inhaltsverzeichnis</h2>
  <ul>
    {headings.map(h => (
      <li style={`margin-left: ${(h.depth - 1) * 1}rem`}>
        <a href={`#${h.slug}`}>{h.text}</a>
      </li>
    ))}
  </ul>
</aside>

<article>
  <Content />
</article>

Besonders bei langen Artikeln – Leser springen schnell zu Kapiteln.

Performance und typische Fallstricke

MDX ist mächtig, aber falsch genutzt bremst die Site.

Client-Komponenten nicht überstrapazieren

React/Vue in MDX brauchen client:*. Ohne Direktive nur SSR – keine Interaktion. Zu viel client:load lädt viel JavaScript und verlangsamt den Seitenaufbau.

Empfehlung:

• Statisches: Astro-Komponenten (Alert, Callout)
• Interaktiv: client:visible (sichtbar) oder client:idle (Leerlauf)
• client:load nur wenn nötig

Bilder optimieren

In MDX nicht rohes <img>, sondern Astros Image-Komponente:

---

title: Mein Artikel

---

import { Image } from 'astro:assets';
import cover from './cover.jpg';

<Image src={cover} alt="Cover-Bild" width={800} height={600} />

Astro komprimiert, erzeugt WebP, Lazy Loading – deutlich bessere Performance.

MDX optimize-Option

Viele MDX-Dateien und langsamer Build? optimize testen:

export default defineConfig({
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});

Interne rehype-Optimierung beschleunigt den Build – kann HTML-Struktur ändern, vorher testen.

Häufige Fehler und Lösungen

Fazit

Kurz die 7 Kerntipps:

1. MDX einrichten – ein Befehl, 5 Minuten
2. Highlighting-Theme – Shiki nach Geschmack
3. Code hervorheben – Transformers für Fokus und Diff
4. Eigene Komponenten – von Alert bis interaktivem Demo
5. Markdown-Mapping – Überschriften, Links global stylen
6. Formeln – KaTeX für professionelle Mathe
7. Diagramme – Mermaid per Code, SSR

Lernpfad:

Nicht alles auf einmal. Mein Vorschlag:

• Schritt 1: MDX + eine einfache Komponente
• Schritt 2: Code-Highlighting bei viel Code
• Schritt 3: KaTeX und Mermaid für Algorithmen/Architektur
• Schritt 4: Component-Mapping als „Fortgeschritten“

Checkliste:

• MDX rendert korrekt
• Code-Highlighting aktiv
• Eigene Komponenten sichtbar
• Formeln (falls konfiguriert)
• Mermaid (falls konfiguriert)
• Build-Zeit akzeptabel

Weiter erkunden:

• Astro Integrations – weitere Plugins
• Community MDX-Komponentenbibliotheken
• Astro View Transitions für flüssige Seitenwechsel

Wählen Sie eine Funktion und probieren Sie sie auf Ihrem Blog. Probleme? Doku und Community helfen meist schnell.

Am Ende zählt der Inhalt. Diese Tools machen Ausdruck klarer und professioneller – Leser binden Ihre Ideen und Erfahrung. Viel Erfolg mit Ihrem Astro-Blog!