JSON to Markdown Table 변환 방법 - 배열·API 응답을 마크다운 표로 만들기

객체 배열(Array of Objects) 형태의 JSON 데이터를 마크다운 표(Markdown Table)로 만들고 싶을 때 가장 안정적인 방법은, 먼저 CSV 형식으로 변환한 뒤 CSV to Markdown 도구에 전달하는 것입니다. JSON을 마크다운 표로 직접 변환해 주는 도구도 있지만, 중첩된 데이터나 누락된 키가 섞여 있으면 결과가 쉽게 깨지고 원인을 추적하기 어렵습니다. 중간에 CSV 단계를 거치면 열(Column)과 행(Row)의 대응 관계를 직접 눈으로 확인할 수 있어 결과가 안정적입니다.

이 글에서는 JSON의 구조를 확인하는 방법부터 CSV 변환, 마크다운 표 생성, 그리고 API 응답 데이터 및 중첩된 JSON 처리 방법까지 차례대로 설명합니다. 모든 처리는 브라우저 내에서 로컬로 완결되므로 API 응답이나 사내 데이터를 붙여넣어도 외부 서버로 전송되지 않습니다.

결론: JSON은 CSV를 거쳐 마크다운 표로 변환한다

먼저 전체 작업 흐름을 정리합니다.

1. JSON 포맷터로 JSON을 정렬하고 객체 배열 형태인지 확인합니다.
2. 배열을 CSV로 변환합니다(각 객체의 키가 열 헤더가 되고, 각 요소가 1개의 데이터 행이 됩니다).
3. 변환된 CSV를 CSV to Markdown에 붙여넣어 마크다운 표를 생성합니다.

FormatArc에는 JSON을 한 번에 마크다운 표로 변환하는 단일 버튼은 없습니다. 대신 포맷터와 CSV 변환 도구를 조합하면 GitHub, GitLab, velog, Tistory 등 어떤 환경에서도 깨지지 않는 GFM(GitHub Flavored Markdown) 호환 표를 만들 수 있습니다. CSV를 중간 단계로 활용하면 열의 어긋남이나 값의 누락을 그 자리에서 즉시 점검할 수 있다는 것이 큰 장점입니다.

마크다운 표로 변환하기 적합한 JSON 형태

마크다운 표는 "열 헤더 + 데이터 행"으로 이루어진 2차원 그리드입니다. 따라서 표로 만들기 가장 적합한 JSON은 동일한 구조를 가진 객체들이 나열된 배열입니다.

[
  { "name": "Mika", "role": "admin", "active": true },
  { "name": "Noah", "role": "viewer", "active": false }
]

이때 각 객체의 키(name, role, active)가 열 헤더가 되고, 배열의 각 요소가 데이터 행 1줄이 됩니다. 위의 JSON은 다음 마크다운 표에 대응합니다.

| name | role | active |
| --- | --- | --- |
| Mika | admin | true |
| Noah | viewer | false |

반대로 배열로 감싸지지 않은 단일 객체({ ... })는 그 자체로 여러 행이 되지 않습니다. 키와 값으로 이루어진 2열 표로 만들거나, [ { ... } ]처럼 배열로 감싼 뒤 변환해야 합니다.

단계별 절차: JSON을 마크다운 표로 변환하기

1단계: JSON을 정렬하고 구조 확인하기

API 응답이나 로그 파일에서 추출한 JSON은 줄바꿈이 없는 1줄 문자열인 경우가 많습니다. 먼저 JSON 포맷터에 붙여넣어 보기 좋게 정렬한 뒤, 실제로 객체 배열인지, 모든 요소가 동일한 키를 가지고 있는지 눈으로 확인합니다.

구문 오류(SyntaxError)가 있으면 이후 변환이 실패하므로, 닫는 괄호 누락이나 후행 쉼표(trailing comma)가 있다면 먼저 수정합니다. 구문 오류가 발생했을 때의 자세한 해결 방법은 JSON 파싱 오류 해결을 참조하세요. // 같은 주석이 포함되어 있다면 표준 JSON 규격에 맞게 주석을 제거해야 합니다. 주석 처리 방법과 대안에 대해서는 JSON 주석처리 방법을 참조하세요.

2단계: 배열을 CSV 형태로 변환하기

구조를 확인했다면 배열을 CSV 형태로 바꿉니다. 작업은 두 가지뿐입니다.

• 첫 번째 줄에 객체의 키를 쉼표로 구분해 헤더로 작성합니다.
• 각 객체의 값을 동일한 순서로 쉼표로 구분해 한 줄씩 작성합니다.

앞서 살펴본 JSON이라면 다음과 같이 변환됩니다.

name,role,active
Mika,admin,true
Noah,viewer,false

값 안에 쉼표(,)나 줄바꿈이 들어 있다면 해당 값을 큰따옴표("...")로 감쌉니다. CSV의 기본 구조와 작성 규칙은 CSV 파일이란?을 참조하세요. 반대로 CSV 데이터를 JSON으로 되돌리고 싶다면 CSV JSON 변환기를 사용할 수 있으며, 다양한 환경에서의 변환 방법은 CSV JSON 변환 가이드에서 다루고 있습니다.

3단계: CSV to Markdown으로 테이블 생성하기

CSV가 준비되면 CSV to Markdown에 붙여넣고 실행합니다.

오른쪽에 GFM 호환 마크다운 표가 즉시 출력됩니다. 헤더 구분선과 열 너비가 자동으로 맞춰지므로, 그대로 복사해 GitHub README, 이슈(Issue), PR 설명, 기술 문서에 바로 붙여넣을 수 있습니다. 변환 원리와 자세한 사용법은 CSV를 마크다운 표로 변환하는 방법을 참조하세요.

API 응답 JSON을 표로 만들기

curl 명령어로 호출한 API 응답 데이터를 표 형태로 정리해 공유해야 하는 경우가 자주 있습니다. 흐름은 위와 동일하게 응답을 정렬한 뒤 CSV를 거쳐 표로 변환합니다.

curl -s https://api.example.com/users | jq .

API 응답이 객체 배열이라면 JSON 포맷터에 붙여넣고 2단계로 진행하면 됩니다. 만약 응답 전체가 { "data": [ ... ] }처럼 배열을 감싸고 있는 형태라면, 표로 만들고자 하는 배열 부분(data 내부)만 추출합니다. jq를 사용한다면 jq '.data' 명령어로 배열만 손쉽게 분리할 수 있습니다.

curl 응답 정렬에 대한 자세한 방법은 curl JSON pretty print 방법을 참조하세요.

인증 헤더나 페이지네이션을 포함한 API 응답 표 변환 워크플로는 API 응답 JSON을 마크다운 표로 변환하기에 정리되어 있습니다.

중첩된 JSON(Nested JSON)은 어떻게 다룰까

실제 API 응답 데이터는 값 안에 또 다른 객체나 배열이 들어 있는 경우가 흔합니다.

[
  { "name": "Mika", "address": { "city": "Tokyo", "zip": "100-0001" } }
]

마크다운 표는 2차원 표이므로, 계층적으로 중첩된 구조를 셀 안에 그대로 넣을 수는 없습니다. 해결 방법은 크게 두 가지입니다.

평탄화(Flatten)한 뒤 표로 만들기

중첩된 키를 address.city와 같은 점 표기법(Dot notation)으로 펼쳐서 1차원 구조로 평탄화한 뒤 CSV로 만듭니다.

name,address.city,address.zip
Mika,Tokyo,100-0001

데이터가 적다면 직접 편집해도 되지만, 데이터 양이 많다면 jq의 to_entries 함수나 Python의 pandas.json_normalize() 같은 도구를 사용해 자동으로 평탄화하는 것이 안전합니다. 평탄화한 후에는 동일하게 CSV를 거쳐 CSV to Markdown으로 표를 생성합니다.

중첩된 값을 문자열로 셀 안에 넣기

구조를 평탄화하지 않고, 중첩된 객체 자체를 하나의 JSON 문자열로 변환해 셀 안에 넣는 방법도 있습니다. address 열의 값으로 {"city":"Tokyo","zip":"100-0001"} 같은 문자열을 그대로 넣습니다.

이 경우 문자열 안에 파이프 기호(|)나 줄바꿈이 포함되면 표 구조가 깨질 수 있으므로, CSV 단계에서 해당 값을 큰따옴표로 감싸 두어야 합니다. CSV to Markdown은 셀 안의 파이프 기호를 자동으로 이스케이프(\|)하고 줄바꿈을 공백으로 변환하므로 안전하게 처리됩니다.

열 정렬(Alignment) 지정하기

GFM 마크다운 표는 구분 행에 콜론(:)을 추가해 열별 정렬 방식을 지정할 수 있습니다.

| name | count |
| :--- | ---: |
| Mika | 12 |
| Noah | 340 |

• :--- — 왼쪽 정렬(기본값)
• :---: — 가운데 정렬
• ---: — 오른쪽 정렬

숫자 데이터가 있는 열을 오른쪽 정렬하면 자릿수가 깔끔하게 맞아 가독성이 높아집니다. 정렬 표시는 GitHub, velog 등 GFM 렌더러에서는 정상 작동하지만, 플랫폼에 따라 다르게 렌더링될 수 있습니다. 열 정렬과 이스케이프를 포함한 표 작성 문법의 자세한 내용은 마크다운 표 만들기를 참조하세요.

자주 발생하는 문제와 주의점

요소마다 키가 다른 경우

배열 내 객체마다 포함된 키가 다른 경우, 어떤 열을 표에 포함할지 결정해야 합니다. 모든 객체에 등장하는 키의 합집합을 열로 지정하면 값이 없는 셀은 빈칸이 됩니다. 반면 첫 번째 객체의 키만을 기준으로 삼으면 뒤쪽 객체에만 있는 키는 누락됩니다. CSV를 구성할 때 필요한 열을 미리 정리해 두어야 일관된 표를 얻을 수 있습니다.

불리언(boolean)·null·숫자 처리

true, false, null 및 숫자 값은 CSV로 변환하면 일반 텍스트로 기록됩니다. 마크다운 표에서도 문자열 형태로 그대로 출력되므로 원래의 의미가 유지됩니다. 빈 값은 빈 셀로 렌더링됩니다.

셀 안의 줄바꿈과 파이프 문자

데이터 값 안에 줄바꿈이나 파이프 기호(|)가 포함되어 있으면 열 구분자와 충돌해 표 레이아웃이 깨집니다. CSV 작성 단계에서 해당 값을 큰따옴표로 감싸면 CSV to Markdown이 파이프 문자를 백슬래시 이스케이프(\|) 처리하고 안전하게 변환합니다.

자주 묻는 질문

JSON 데이터를 서버에 업로드해야 하나요?

전혀 그렇지 않습니다. FormatArc의 모든 변환 처리는 사용자의 웹 브라우저 로컬 환경에서 실행됩니다. API 응답이나 기밀 데이터, 개인정보가 포함된 JSON을 붙여넣어도 외부 서버로 전송되지 않습니다.

왜 직접 변환하지 않고 CSV를 거치나요?

CSV를 중간 매개체로 사용하면 열 헤더와 데이터 행의 대응 관계를 시각적으로 명확하게 확인할 수 있기 때문입니다. JSON을 직접 표로 변환하는 경우 중첩 데이터나 누락된 키로 인해 레이아웃이 깨졌을 때 원인을 파악하기 어렵지만, CSV 단계를 거치면 어긋난 부분을 즉시 발견하고 수정할 수 있습니다.

중첩된 JSON을 그대로 표로 만들 수 있나요?

마크다운 표는 2차원 평면 구조이므로 깊게 중첩된 계층 구조를 그대로 셀에 담을 수는 없습니다. address.city처럼 점 표기법으로 평탄화하거나, 중첩 객체를 JSON 문자열로 직렬화하여 하나의 셀에 넣는 방식을 사용해야 합니다.

코드로 JSON을 마크다운 표로 변환하기

브라우저 도구 외에 스크립트, CI 파이프라인, 문서 자동 생성 과정에서 프로그래밍 방식으로 JSON을 마크다운 표로 변환하고 싶다면 다음 라이브러리와 도구를 활용할 수 있습니다.

Python (tabulate)

from tabulate import tabulate

data = [
    {"id": 1, "name": "Mika",  "role": "admin"},
    {"id": 2, "name": "Noah",  "role": "viewer"},
    {"id": 3, "name": "Sofia", "role": "editor"},
]
print(tabulate(data, headers="keys", tablefmt="pipe"))

tablefmt="pipe" 옵션을 사용하면 GFM 호환 파이프 표가 출력됩니다. tablefmt="github"를 지정하면 정렬 행도 명시적으로 작성됩니다. pip install tabulate로 설치합니다.

JavaScript / Node.js (tablemark)

import tablemark from "tablemark";

const data = [
  { id: 1, name: "Mika",  role: "admin" },
  { id: 2, name: "Noah",  role: "viewer" },
  { id: 3, name: "Sofia", role: "editor" },
];
console.log(tablemark(data));

tablemark 라이브러리는 객체 배열을 직접 받아 GFM 파이프 표를 생성합니다. npm install tablemark로 설치합니다.

쉘 (jq + FormatArc CLI)

런타임 의존성 없이 쉘 환경에서 한 줄로 변환하고 싶다면 jq와 formatarc npm CLI 도구를 파이프라인으로 연결할 수 있습니다.

curl -s https://api.example.com/users \
  | jq -r '(.[0] | keys_unsorted) as $k | $k, (.[] | [.[$k[]]]) | @csv' \
  | npx formatarc csv-to-markdown

jq는 첫 번째 객체의 키를 헤더로 추출하고 나머지 데이터를 CSV 형태로 출력합니다. formatarc csv-to-markdown은 표준 입력(stdin)에서 CSV를 읽어 마크다운 표를 표준 출력(stdout)으로 내보냅니다. CI 환경이나 자동화 스크립트에서 유용합니다.

README에 표를 작성할 때의 주의점과 팁은 GitHub README 표 만들기를 참조하세요.

마크다운 표의 한계와 HTML 전환 기준

마크다운 표는 간결한 표기를 목적으로 설계되었기 때문에 복잡한 서식을 표현하는 데는 한계가 있습니다. 표현하려는 데이터가 마크다운 표의 사양을 벗어난다면 마크다운 내에서 HTML <table> 태그로 전환하는 것이 적절합니다.

GitHub, velog, Notion 등 대부분의 마크다운 렌더러는 마크다운 문서 내의 원시 HTML 태그를 정상적으로 렌더링합니다. 셀 병합이나 세밀한 스타일링이 필요한 경우 <table> 태그를 직접 작성하거나 JSON에서 템플릿으로 생성해 임베드할 수 있습니다. 반대로 복잡한 HTML 표를 마크다운 표로 변환하고 싶다면 HTML to Markdown 변환기를 활용할 수 있습니다. HTML 테이블을 마크다운 표로 되돌리는 방법은 HTML 테이블을 마크다운 표로 변환을 참조하세요.

정리

JSON 데이터를 깔끔하고 안정적인 마크다운 표로 만드는 가장 빠른 방법은 CSV를 중간 매개체로 활용하는 것입니다. JSON 포맷터로 구조를 확인하고, 배열을 CSV 형식으로 정리한 뒤, CSV to Markdown에 붙여넣으면 즉시 복사해 쓸 수 있는 GFM 호환 표가 생성됩니다. 중첩된 JSON이나 복잡한 API 응답 데이터도 평탄화 작업을 거치면 동일한 방식으로 손쉽게 처리할 수 있습니다.

완성된 마크다운 표는 LLM의 프롬프트 컨텍스트로 전달할 때도 불필요한 태그가 많은 HTML에 비해 토큰 효율과 데이터 추출 정확도 면에서 유리합니다. 토큰 절약과 실측 비교에 대한 자세한 내용은 LLM 입력엔 Markdown vs HTML?을 참조하세요. 마크다운 표를 다시 HTML 코드로 변환하고 싶다면 Markdown to HTML 변환기를 함께 사용해 보세요.