Markdown / MDX

Markdown is a document, not a list of strings, so it works differently from every other format: transglot splits the document into blocks, one key per block, and rebuilds a document with the same structure on export.

How a document becomes keysCopy Anchor Link

Each block gets a key made of its type and its position in the document. This file:

---
title: Getting started
---

# Getting started

Install the **CLI** with [npm](https://npmjs.com).

- Create a project
- Push your files

```bash
npx transglot push
```

| Command | What it does |
| --- | --- |
| push | Uploads files |

> Tip: run pull after push.

imports as:

• Translatable blocks: headings, paragraphs, list items, table cells and blockquote text. Inline markup (**bold**, links, `code`) stays inside the text, so translators keep it in place.
• Blocks kept verbatim: YAML (---) or TOML (+++) front matter, fenced code blocks, raw HTML and MDX JSX blocks, and MDX import and export statements. They are stored with their exact text so export can put them back. Text inside front matter, such as a title, is part of that verbatim block.

Because keys are positions, they only make sense for that document. Adding a paragraph near the top of the source shifts the keys of every block after it.

ExportCopy Anchor Link

Export rebuilds the document from the keys, in position order. The result has the same structure, written in a canonical style:

• one blank line between blocks, LF line endings, no trailing whitespace,
• ordered lists renumbered from 1,
• table delimiter rows written as --- (column alignment is dropped),
• thematic breaks written as ---.

Running the output through transglot again gives the same document, but it is not byte-for-byte your original file.

Only a project whose keys all came from a Markdown document can be exported as Markdown. The export screen blocks the format for any other project.

LimitationsCopy Anchor Link

• Setext headings (text underlined with === or ---) are not recognized. They become a paragraph followed by a thematic break; use # headings.
• Indented (four-space) code blocks are read as paragraph text. Use fenced code blocks.
• Lazy continuation lines in lists and blockquotes become blocks of their own.
• Hard-wrapped paragraphs keep their line breaks; they are not re-wrapped.
• The file must be UTF-8, and an unclosed code fence is an import error naming the line it opened on.
• Markdown has no plurals.

RelatedCopy Anchor Link

• Import content
• File formats