Markdoc
Übersetze Markdoc-Fließtext und ausgewählte Attribute mit Zeichenfolgenwerten, ohne Annotationen, Variablen oder Code zu verändern.
Markdoc-Annotationen verknüpfen den Fließtext eines Dokuments mit benutzerdefinierten Komponenten und Variablen. Der Dateihandler für markdoc übersetzt unterstützten Fließtext und ausgewählte Tag-Attribute mit Zeichenfolgenwerten. Dabei bleiben die Annotationen erhalten, die dein Renderer benötigt.
Sichtbare Tag-Eigenschaften auswählen #
Ein Dokument kann sichtbare Metadaten, eine feste Layout-Kennung und einen Hinweisblock kombinieren:
---
title: Delivery options
description: Understand the available delivery methods.
layout: article
---
{% callout title="Delivery deadline" type="warning" %}
Confirm your address before checkout.
{% /callout %}Der Absatz und die standardmäßig ausgewählten Frontmatter-Felder title und description enthalten Text. Das Tag-Attribut title wird übersetzt, sobald eine Eigenschaftsregel es auswählt. type="warning" und layout: article sind strukturelle Kennungen. Lass sie unausgewählt, sofern die verarbeitende Komponente nicht ausdrücklich übersetzte Werte erwartet.
Regeln können eine Eigenschaft für alle Tags auswählen oder die Auswahl auf Tags mit bestimmten Namen beschränken. Bevorzuge die beschränkte Variante, wenn verschiedene Tags dasselbe Attribut für unterschiedliche Zwecke verwenden. Numerische, boolesche, aus Variablen abgeleitete und andere Attribute ohne Zeichenfolgenwerte sind keine wörtlich vorliegenden Fließtexteinheiten.
Was geschützt bleibt #
Codeblöcke und Inline-Code sind von der Übersetzung ausgeschlossen. Linkziele bleiben unverändert, während Linkbeschriftungen übersetzt werden können. Inline-Annotationen und Bilder bleiben als geschützte Elemente im umgebenden Fließtext erhalten. Auch Tag-Namen und nicht ausgewählte Attribute bleiben im Dokument unverändert. Der Handler maskiert übersetzte Zeichenfolgenattribute passend zur Markdoc-Syntax für Anführungszeichen. Das Schema deines Renderers für benutzerdefinierte Tags stellt er jedoch nicht bereit.
Die Frontmatter-Felder title und description sind standardmäßig ausgewählt. Bei einer leeren Frontmatter-Auswahl bleiben sie unverändert. Wenn du eine Zuordnung oder Sequenz auswählst, werden auch deren untergeordnete skalare Werte einbezogen. Wähle gezielte Pfade wie seo.title, wenn benachbarte Routing-Felder oder Inhalts-IDs unverändert bleiben müssen.
Zuordnung zwischen Quelle und Ziel beibehalten #
Bei der Rekonstruktion werden Textabschnitte in der aktuellen Quelle ersetzt. Dabei lassen sich Formulierungen aus einer früheren, einander zugeordneten Quell- und Zielversion wiederverwenden. Wenn deren geschützte Inline-Strukturen nicht sicher einander zugeordnet werden können, kann die Wiederverwendung fehlschlagen. Bewahre die Quellversion auf, die zur akzeptierten Übersetzung gehört – besonders nach dem Verschieben von Tags oder dem Ändern von Links.
Gehe nicht davon aus, dass ein .md-Dokument mit Markdoc-Annotationen automatisch diesen Handler verwendet. Für .md erkennt die CLI Markdown als Format. Wähle das Format ausdrücklich aus, wenn die Dokumentsprache eine Verarbeitung als Markdoc erfordert.
Markdoc-Übersetzung konfigurieren #
Die CLI leitet markdoc aus .mdoc ab; eine Einschränkung auf bestimmte Schlüssel ist nicht verfügbar. Nutze die CLI-Konfiguration für Frontmatter, die Auswahl von Tag-Eigenschaften und das Ziellayout oder GitHub für den Repository-Workflow.
Mit dem Schema der Website validieren #
Der Dateihandler konfiguriert weder Framework-Routen noch das Laden von Inhalten oder die Markdoc-Transformationen deiner Anwendung. Parse und rendere das Zieldokument nach dem Abrufen mit denselben Schemas wie das Quelldokument. Sieh dir neben den übersetzten Absätzen auch sichtbare Attribute, Linkziele, Variablen und ausgewählte Frontmatter-Felder an.