@diglot/mdast

remark / mdast adapter for diglot, for markdown parsed with remark-parse, remark-gfm, remark-frontmatter and remark-mdc, and for MDX. Suitable for Astro, Docusaurus, Starlight or plain markdown sources.

pnpm add @diglot/mdast @diglot/core

Usage

import { apply, extract } from '@diglot/mdast'

const segments = await extract(markdown, { file: 'docs/intro.md' })

const { markdown: translated, report } = await apply(markdown, new Map([[segments[0].hash, 'Introduction']]))

• extract(source, { file, format, parser, policy }) returns the same segments (and hashes) as @diglot/comark for the same document, with node-precise line positions. Protected spans are sliced from the source.

• apply(source, translations, { format, parser, policy }) validates each translation and splices it into the source, so everything outside translated units is preserved byte for byte. Frontmatter and YAML props are rewritten as YAML scalars; inline props keep their attribute syntax; code comments keep their indentation and comment syntax. Units that cannot be located in the source are reported as unaddressable and keep their source text.

• apply(source, translations, { onSegment }) calls onSegment with an ApplySegmentEvent for each segment. Attributes set with target.setAttribute(name, value) on headings, paragraphs and table cells are returned as annotations, located in the applied markdown; other segments have a null target. annotate(tree, annotations) sets them as data.hProperties on a tree parsed from that markdown, and renders paragraphs of tight list items as <span> so their attributes reach the HTML.

  const { markdown: translated, annotations } = await apply(markdown, segment => records.get(segment.hash), {
    onSegment(event) {
      if (event.outcome === 'missing' || event.outcome === 'rejected')
        event.target?.setAttribute('lang', 'en')
    },
  })
  const tree = processor.parse(translated)
  annotate(tree, annotations)
  

• parse(source, { format, parser }) exposes the pipeline the adapter uses.

Parsers

extract, apply and parse take a parser option. remark is the default. satteri uses Sätteri, a Markdown parser written in Rust, which is much faster:

pnpm add satteri

const segments = await extract(markdown, { parser: 'satteri' })

Sätteri reads directives the same way as remark-directive, which Starlight uses. ::: blocks such as asides are translated like components with either parser, and with Sätteri their titles (:::tip[Title]) are translated too. Inline directives with a label or attributes, such as :badge[New], are kept as placeholders. Sätteri has no MDC support, so block components such as ::card are not parsed and their markers can end up in translated text. Keep remark for MDC sources. For other markdown, both parsers produce the same segments and hashes, so existing translations keep applying. One exception: Sätteri skips TOML frontmatter (+++), which remark reads as a paragraph. Pass the same parser to extract and apply.

MDX

MDX is markdown with JSX components, {expressions} and import and export statements. The adapter reads a document as MDX when file ends in .mdx, or when you pass format: 'mdx':

const segments = await extract(source, { file: 'docs/cards.mdx' })

Both parsers read MDX, remark with remark-mdx and Sätteri with its own MDX parser, and they produce the same segments and hashes. MDX is never read as MDC, but ::: directives such as Starlight asides are read in both formats. One exception: Docusaurus admonitions with a title after a space (:::tip Title). Sätteri reads them as directives and drops the title, while remark only reads titles in brackets and keeps these lines as text.

The text inside a JSX element is translated like the content of an MDC component. The string props that the policy lists for a component are translated too, matched by the kebab-case name of the element, so <LinkCard title="…"> uses the props of link-card. Props with an expression value, such as title={name}, are left alone. A JSX element inside a sentence, such as <kbd>Ctrl</kbd>, and an expression such as {count} become placeholders. import and export statements and expressions on their own lines, comments included, aren't translated.

Validation rejects a translation that contains an unescaped { or HTML, and apply escapes every other < that MDX would read as a tag, so an applied translation can't add JSX or expressions to the page. A translated prop keeps the quote character of the source, unless the value contains that character and not the other one. When the value contains both, the quote character is written as " or '.

Heading anchors are generated by the renderer from the heading text, so translated headings get translated anchors unless the renderer supports explicit ids.