Markdoc

Translate Markdoc prose and selected string attributes while preserving annotations, variables, and code.

Markdoc annotations connect document prose to custom components and variables. The markdoc file handler translates supported prose and selected string-valued tag attributes while retaining the annotations your renderer needs.

Select visible tag properties #

A document can combine visible metadata, a fixed layout identifier, and a callout:

markdown
---
title: Delivery options
description: Understand the available delivery methods.
layout: article
---

{% callout title="Delivery deadline" type="warning" %}
Confirm your address before checkout.
{% /callout %}

The paragraph and default-selected title and description frontmatter are text. The tag's title becomes translation work when a property rule selects it. type="warning" and layout: article are structural identifiers; leave them unselected unless their consumer explicitly expects translated values.

Rules can apply a property name to all tags or restrict it to named tags. Prefer the restricted form when different tags use the same attribute for different purposes. Numeric, boolean, variable-derived, and other non-string attributes are not literal prose units.

What stays protected #

Fenced and inline code stay outside translation. Links retain their destinations while labels can change. Inline annotations and images are protected constructs in surrounding prose. Tag names and unselected attributes remain in the document. The handler escapes translated string attributes for Markdoc quoting, but that does not supply your renderer's custom-tag schema.

Frontmatter title and description are selected by default. An empty frontmatter selection leaves them unchanged. Selecting a map or sequence includes its scalar descendants. Choose precise paths such as seo.title when neighboring routing fields or content IDs must stay fixed.

Preserve source-and-target alignment #

Reconstruction replaces text spans in the current source and can reuse wording from an aligned previous source and target. If their protected inline structures do not correspond safely, reuse can fail. Keep the source revision that accompanied the accepted translation, especially after moving tags or changing links.

Do not assume a .md document containing Markdoc annotations selected this handler. The CLI infers Markdown for .md; use explicit format selection when the document language requires Markdoc behavior.

Configure Markdoc translation #

The CLI infers markdoc from .mdoc; key scope is unavailable. Use CLI configuration for frontmatter, tag-property selection, and destination layout, or GitHub for the repository workflow.

Validate with the site's schema #

The file handler does not configure framework routes, content loading, or your application's Markdoc transforms. After retrieval, parse and render the target with the same schemas as the source. Inspect visible attributes, link destinations, variables, and selected frontmatter alongside the translated paragraphs.