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

한 파일에 포맷이 공존할 때

Markdown front matter (재방문)

처음 만난 polyglot 패턴. 위에 YAML/TOML/JSON 메타데이터, 아래 Markdown 본문. 본문이 사람; front matter 가 구조화. 정적 사이트 생성기가 둘 다 읽음. GFM 트랙 lesson 6 에서 다룸.

MDX — Markdown + JSX

MDX (Next.js / Astro / Docusaurus 포맷) 가 React component 를 Markdown 안에 import 가능하게 함. 결과: <Chart data={[1,2,3]} /> 를 문단처럼 떨어뜨리는 Markdown 본문. component 가 인터랙티브 HTML 로 렌더; 둘러싼 텍스트는 Markdown 유지. 두 layer 의 best.

YAML string 의 임베디드 JSON

CI 에 흔함: 값이 JSON-인코딩 string 인 YAML 필드. config: '{"key":"value"}'. downstream 도구가 정확히 JSON 기대할 때 유용. trade-off: YAML 리더가 string 보고 구조 안 봐 — YAML schema validator 가 안에 못 들어감.

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

OpenAPI 생성기가 가끔 x-extension: "yaml-encoded" blob emit. 덜 흔함; 같은 trade-off — 외부 파서가 내부 구조 안 봄.

'string-encoded structure' 안티패턴: 도구가 중첩 구조 native 지원하면 그걸 선호. JSON blob 을 YAML string 으로 인코딩하는 건 schema validation, autocomplete, pretty-print 무력화 — 한 layer 수동 unwrap 안 하는 모든 도구에 데이터를 불투명하게 만들었음. 받는 쪽이 요구할 때만 사용.

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 하나 (chart, calculator, 라이브-config preview) 로 확장 상상. MDX 버전 정신적으로 스케치. 구조화 조각이 JSON/YAML import 원하고, prose 가 Markdown 유지 — 그게 polyglot 승리.

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

한 파일에 포맷이 공존할 때

Markdown front matter (재방문)

MDX — Markdown + JSX

YAML string 의 임베디드 JSON

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

Code

External links

Exercise

Progress

댓글 0