FormatArc의 한국어 CSV to Markdown 화면에서 변환된 마크다운 표FormatArc의 한국어 CSV to Markdown 화면에서 변환된 마크다운 표
저자: FormatArc게시일: 2026-08-22갱신일: 2026-11-07

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

객체 배열(Array of Objects) 형태의 JSON 데이터를 마크다운 표(Markdown Table)로 만들고 싶을 때 가장 안정적인 방법은, 먼저 CSV 형식으로 변환한 뒤 CSV to Markdown 도구에 전달하는 것입니다. JSON을 마크다운 표로 직접 변환한다면, 도구가 중첩된 값과 누락된 키를 어떻게 처리하는지 먼저 확인하세요. 중간에 CSV 단계를 거치면 열(Column)과 행(Row)의 대응 관계를 눈으로 확인할 수 있어, 어긋난 열이나 빠진 값을 고친 뒤 마크다운 표로 넘길 수 있습니다.

이 글에서는 JSON의 구조를 확인하는 방법부터 CSV 변환, 마크다운 표 생성, 그리고 API 응답 데이터 및 중첩된 JSON 처리 방법까지 차례대로 설명합니다. 이 글에서 소개하는 FormatArc의 브라우저 도구는 붙여넣은 데이터를 브라우저 안에서 처리하며 외부 서버로 전송하지 않습니다.

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

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

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

위의 세 과정은 JSON to Markdown 변환기로 한 번에 처리할 수 있습니다. 같은 CSV 경유 규칙을 쓰기 때문에 중첩 객체는 address.city 같은 점 표기법 열이 되고, 배열은 JSON 형식 문자열로 바꿔 한 셀에 담고, 키가 없는 행은 그 키에 해당하는 셀을 빈칸으로 둡니다. 마지막으로 GFM 호환 표를 만들고 셀 안의 |는 이스케이프합니다. 만들어진 표는 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 구조에 따라 추가 처리가 필요할 수 있습니다.

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

앞서 살펴본 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에 붙여넣고 실행합니다.

FormatArc의 한국어 CSV to Markdown 화면에서 변환된 마크다운 표FormatArc의 한국어 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" } }
]

중첩된 구조를 행과 열로 나타내려면 계층을 평탄화해야 합니다. 계층을 문자열로 보여 주기만 하면 된다면, 중첩된 부분을 셀 하나에 넣는 방법도 있습니다.

평탄화(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에서는 이 정렬이 그대로 표시되지만, 마크다운을 표시하는 프로그램에 따라 적용되지 않을 수 있습니다. 열 정렬과 이스케이프를 포함한 표 작성 문법의 자세한 내용은 마크다운 표 만들기를 참조하세요.

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

요소마다 키가 다른 경우

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

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

true, false 및 숫자 값은 CSV로 변환하면 일반 텍스트로 기록되고, 마크다운 표에서도 같은 표기로 출력됩니다. 키가 없는 행과 null 값은 모두 빈 셀이 됩니다.

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

데이터 값 안에 줄바꿈이나 파이프 기호(|)가 포함되어 있으면 열 구분자와 충돌해 표 레이아웃이 깨집니다. 셀 안의 줄바꿈과 파이프 문자 처리 방식은 앞의 「중첩된 값을 문자열로 셀 안에 넣기」에서 설명한 것과 같습니다.

자주 묻는 질문

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

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

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

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

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

중첩을 지원하는 도구라면 그대로 입력할 수 있습니다. 직접 변환한다면 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가 출력한 CSV를 FormatArc CLI에 넘깁니다.

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

이 명령은 첫 번째 객체의 키를 헤더 행으로 삼고, 배열의 각 객체 값을 데이터 행으로 CSV에 출력합니다. formatarc csv-to-markdown은 표준 입력(stdin)에서 CSV를 읽어 마크다운 표를 표준 출력(stdout)으로 내보냅니다. CI 환경이나 자동화 스크립트에서 유용합니다.

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

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

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

요구사항마크다운 표HTML <table>권장 선택
셀 병합(colspan / rowspan)지원 불가지원HTML
셀 내 줄바꿈인라인 <br> 사용<br> 기본 지원HTML 또는 인라인 <br>
행이 많은 대용량 데이터렌더러에 따라 느림가벼움HTML 또는 페이지네이션
LLM 프롬프트 컨텍스트최적 (토큰 효율 높음)태그가 장황함마크다운
GitHub README 표시최적렌더러에 따라 상이마크다운
좌/우/가운데 외의 정렬지원 불가인라인 스타일로 가능HTML
헤더 없는 표비표준 (구분 행 필요)지원HTML

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

정리

JSON을 마크다운 표로 변환하는 방법은 일괄 변환 도구를 쓰는 것과, CSV로 열과 행의 대응을 확인하면서 변환하는 것 두 가지입니다. JSON 포맷터로 구조를 확인하고, 배열을 CSV 형식으로 정리한 뒤, CSV to Markdown에 붙여넣으면 즉시 복사해 쓸 수 있는 GFM 호환 표가 생성됩니다. 중첩된 객체는 평탄화하고, data 같은 안에 배열이 있는 API 응답은 필요한 배열만 꺼내면 같은 흐름으로 변환할 수 있습니다.

변환한 표를 LLM에 입력할 때 어떤 형식을 고를지는 LLM 입력엔 Markdown vs HTML?에서 비교하고 있습니다. 마크다운 표를 다시 HTML 코드로 변환하고 싶다면 Markdown to HTML 변환기를 함께 사용해 보세요.