Polyglot 패턴 — front matter, MDX, 임베디드 JSON · Markup Quest

한 파일에 포맷이 공존할 때

Markdown front matter (재방문)

가장 먼저 만난 공존 패턴이야. 위에는 YAML 이나 TOML, JSON 메타데이터를 두고 아래에는 Markdown 본문을 둬. 본문은 사람 몫이고 front matter 는 구조 몫이지. 정적 사이트 생성기는 둘 다 읽고. GFM 트랙 lesson 6 에서 다뤘어.

MDX — Markdown + JSX

MDX 는 Next.js 와 Astro, Docusaurus 가 쓰는 포맷인데, React component 를 Markdown 안으로 불러올 수 있게 해줘. 그래서 <Chart data={[1,2,3]} /> 를 문단 하나처럼 툭 떨어뜨린 Markdown 본문이 나와. component 는 눌러지는 HTML 로 렌더되고 그 주변 글은 계속 Markdown 이야. 두 층에서 좋은 것만 가져온 셈이지.

YAML string 의 임베디드 JSON

CI 에서 흔히 봐. YAML 필드의 값이 JSON 을 문자열로 감싼 형태인 거야. config: '{"key":"value"}' 처럼. 뒤에서 받는 도구가 딱 JSON 을 원할 때 쓸모가 있어. 대신 값을 치러. YAML 을 읽는 쪽에는 그게 그냥 문자열로만 보이고 안쪽 구조는 안 보여. YAML schema validator 도 그 안으로 못 들어가고.

JSON string 의 임베디드 YAML (드물지만 존재)

OpenAPI 생성기가 가끔 x-extension: "yaml-encoded" 같은 덩어리를 뱉어. 훨씬 드물지만 치르는 값은 똑같아. 바깥 파서가 안쪽 구조를 못 봐.

'구조를 문자열에 우겨넣기' 안티패턴: 도구가 중첩 구조를 원래부터 지원한다면 그쪽을 써. JSON 덩어리를 YAML 문자열로 인코딩하는 순간 schema 검증도, autocomplete 도, pretty-print 도 다 죽어. 한 겹을 손으로 벗겨내지 않는 모든 도구에게 그 데이터는 그냥 불투명한 덩어리가 되는 거야. 받는 쪽이 대놓고 그걸 요구할 때만 써.

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>

YAML 의 임베디드 JSON (CI 변형)·yaml

# GitHub Actions 예시 — JSON-인코딩 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() 이 JSON-인코딩 string unwrap; 요구 안 되면 native YAML 고려.

polyglot 인코딩 없는 같은 데이터 (선호)·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

관리 중인 Markdown 파일 중에 데이터가 많은 걸 골라. 표와 코드 블록, 예시가 잔뜩 든 docs 페이지 같은 거. 여기에 눌러볼 수 있는 component 를 하나 얹는다고 상상해봐. 차트든 계산기든 config 를 실시간으로 보여주는 미리보기든. 그 MDX 버전을 머릿속으로 그려봐. 구조가 있는 조각은 JSON 이나 YAML 을 import 하고 싶어 하고, 글은 계속 Markdown 으로 남고. 두 포맷이 공존해서 이기는 게 딱 그 모양이야.

Polyglot 패턴 — front matter, MDX, 임베디드 JSON

한 파일에 포맷이 공존할 때

Markdown front matter (재방문)

MDX — Markdown + JSX

YAML string 의 임베디드 JSON

JSON string 의 임베디드 YAML (드물지만 존재)

Code

External links

Exercise

Progress

댓글 0