Polyglot Patterns — Front Matter, MDX, Embedded JSON

When formats coexist in one file

Markdown front matter (revisited)

The first polyglot pattern you met. YAML/TOML/JSON metadata at the top, Markdown body below. The body is human; the front matter is structured. Static-site generators read both. We covered this in lesson 6 of the GFM track.

MDX — Markdown + JSX

MDX (the Next.js / Astro / Docusaurus format) lets you import React components inside Markdown. The result: a Markdown body where you drop in <Chart data={[1,2,3]} /> as if it were a paragraph. The component renders to interactive HTML; the surrounding text stays Markdown. Best of two layers.

Embedded JSON in YAML strings

Common in CI: a YAML field whose value is a JSON-encoded string. config: '{"key":"value"}'. Useful when downstream tooling expects JSON exactly. The trade-off: the YAML reader sees a string, not the structure — so YAML schema validators can't reach in.

Embedded YAML in JSON strings (rarer, but it exists)

OpenAPI generators sometimes emit x-extension: "yaml-encoded" blobs. Less common; same trade-off — the outer parser doesn't see the inner structure.

The 'string-encoded structure' anti-pattern: if your tooling supports nested structure natively, prefer it. Encoding a JSON blob as a YAML string defeats schema validation, autocomplete, and pretty-printing — you've just made the data opaque to every tool that doesn't unwrap one layer manually. Use it only when the receiving end demands it.

Code

MDX — Markdown + React·markdown

---
title: "Server Architecture"
author: "C.W.K."
---

import { Chart } from '../components/Chart'
import notes from './architecture.json'

# Server Architecture

The request flow looks like this:

<Chart data={notes.requestFlow} />

React components render inline; the surrounding prose stays Markdown.

- Bullet lists work
- Headings work
- All standard Markdown still applies

<details>
  <summary>Click to expand</summary>
  HTML-style elements work too, with JSX semantics inside.
</details>

Embedded JSON in YAML (CI variant)·yaml

# GitHub Actions example — passing a JSON-encoded matrix
jobs:
  test:
    strategy:
      matrix:
        config: ['{"name":"linux","runner":"ubuntu-latest"}', '{"name":"mac","runner":"macos-latest"}']
    runs-on: ${{ fromJson(matrix.config).runner }}
    name: ${{ fromJson(matrix.config).name }}
    steps:
      - run: echo running on ${{ matrix.config }}
# fromJson() unwraps the JSON-encoded string; consider native YAML unless required.

Same data without polyglot encoding (preferred)·yaml

jobs:
  test:
    strategy:
      matrix:
        config:
          - { name: linux, runner: ubuntu-latest }
          - { name: mac,   runner: macos-latest  }
    runs-on: ${{ matrix.config.runner }}
    name: ${{ matrix.config.name }}
    steps:
      - run: echo running on ${{ matrix.config.name }}

Exercise

Pick a deeply data-rich Markdown file you maintain (a docs page with tables, code blocks, examples). Imagine extending it with one interactive component (a chart, a calculator, a live-config preview). Sketch the MDX version mentally. Notice that the structured pieces want to be JSON/YAML imports, the prose stays Markdown — that's the polyglot win.

Polyglot Patterns — Front Matter, MDX, Embedded JSON

When formats coexist in one file

Markdown front matter (revisited)

MDX — Markdown + JSX

Embedded JSON in YAML strings

Embedded YAML in JSON strings (rarer, but it exists)

Code

External links

Exercise

Progress

Comments 0