문서 작업 가이드
데이터를 손상시키지 않고 CSV·JSON 레코드를 Markdown 표로 변환하기
안전한 레코드 표본을 정하고, 따옴표 CSV 또는 엄격한 JSON을 파싱하고, 정규화 경고와 표 미리보기를 확인한 뒤 실제 목적지에서 GFM을 검증하는 실전 절차입니다.
작성 및 검수 SimpleWebUtils게시일: 검토일:
이 작업 흐름을 검증한 방법
“뒤에서 추가된 키, 0, 중첩 담당자를 포함한 API fixture 문서화” 문서 입력을 데이터 테이블 워크벤치에 그대로 넣었습니다. 수행 순서는 “원본 계약이 CSV인지 JSON인지 확인합니다”, “파서, 구조, 정밀도 진단을 모두 해결합니다”였고 브라우저 결과를 예시 출력과 대조했습니다. 실패 경계는 “실제 운영 데이터를 편리한 표본으로 사용하기”, “내보내기 설정 확인 없이 구분자 감지를 믿기” 두 항목으로 나눠 검토했습니다.
GFM 표는 처음 등장한 열 순서를 유지하고 중첩 owner를 축약 JSON으로 표시했으며, false와 0을 보존하고 없는 score 셀만 비워 두었습니다.
문제 상황
스프레드시트 내보내기와 API 예제는 따옴표 쉼표, 포함 줄바꿈, 불균일 행, 뒤에서 추가된 JSON 키, 중첩 객체, null, 큰 식별자, 파이프 문자, HTML 형태 문자열을 만나면 단순하지 않습니다. 변환기는 값을 잘못된 열로 옮기거나 숫자를 반올림하고도 그럴듯한 Markdown을 만들 수 있습니다. 따라서 목표는 파이프 문법 생성이 아니라 의도한 레코드를 보존하고, 불가피한 정규화를 공개하고, 민감 필드를 제거하며, 목적지에서 독자가 보게 될 표와 동일함을 증명하는 것입니다.
이럴 때 사용하세요
- 검토한 스프레드시트 내보내기를 호환성 매트릭스, 릴리스 표, 재고 일부, README 참고 표로 바꿀 때
- 작은 API 응답 fixture를 false, 0, null, 뒤 객체에서 새로 등장한 키까지 보존해 행으로 문서화할 때
- 운영 레코드에서 민감 정보를 제거한 뒤 변환 서비스에 업로드하지 않고 지원 런북이나 사고 부록 표를 만들 때
- 데이터 계약 변경의 전후 Markdown fixture를 행·열 수, 이스케이프, 모바일 렌더링까지 pull request에서 검토할 때
단계
- 1단계
독자와 목적을 정하고 안전한 대표 fixture를 분리합니다
표가 답해야 할 질문을 정하고 그 답에 필요한 행과 열만 남깁니다. 액세스 토큰, 이메일, 고객 식별자, 내부 호스트, 미공개 가격, 관련 없는 메타데이터를 제거하세요. 따옴표 구분자, 여러 줄 메모, false, 0, null, 뒤에서 추가된 키, 긴 값, 리터럴 파이프처럼 민감하지 않은 어려운 사례는 유지해 지나치게 깨끗한 표본이 아니라 실제 계약을 검사하게 합니다.
- 2단계
원본 계약이 CSV인지 JSON인지 확인합니다
CSV라면 내보내기 구분자, 따옴표 문자, 헤더 정책, 줄바꿈, 인코딩을 확인합니다. 따옴표 필드에 쉼표와 줄바꿈이 들어갈 수 있으므로 눈으로 쉼표를 나눠 구조를 추측하지 마세요. JSON이라면 엄격한 최상위 객체 배열을 요구하고, 중첩 배열이나 객체를 축약 셀 텍스트로 허용할지 결정합니다. 정확한 큰 식별자는 JavaScript 숫자 파싱에 맡기지 말고 원본에서 문자열로 바꾸세요.
- 3단계
구분자, 헤더, 정렬을 명시해 변환합니다
Data Table Workbench에서 CSV 또는 JSON을 선택합니다. CSV 계약을 모를 때만 자동 구분자 감지를 사용하고 감지된 문자를 확인하세요. 계약을 안다면 쉼표, 탭, 세미콜론, 파이프, 한 글자 사용자 구분자를 직접 선택합니다. 첫 행 헤더 옵션을 정확히 설정하고, 정렬은 표현용으로만 선택하며 숫자 유형 검증을 대신하게 하지 말고 수동으로 변환을 실행합니다.
- 4단계
파서, 구조, 정밀도 진단을 모두 해결합니다
잘못된 따옴표, 유효하지 않은 JSON, 원시값 JSON 행, 중복 키, 안전 범위 밖 정수, 손실 소수, 자원 한도 오류가 있으면 중단합니다. 빈 행, 불균일 CSV, 생성·중복 헤더, 중첩 값, null 셀, 여러 줄 내용, 가장자리 공백, HTML 형태 텍스트 경고를 검토하세요. 보고된 행·열 수를 원본 fixture와 비교하고 모든 차이를 설명한 뒤 결과를 받아들입니다.
- 5단계
표 미리보기와 생성 Markdown을 함께 비교합니다
마지막 레코드와 일부 객체에만 있던 필드를 포함해 행과 열을 따라 미리보기를 확인합니다. 그다음 Markdown 원문에서 이스케이프된 파이프와 백슬래시, 생성된 <br> 표시, non-breaking 공백 엔터티, 인코딩된 HTML 문자, 정렬 표식, 축약 중첩 JSON을 검사하세요. false와 0이 보이는지, null·누락·빈 문자열이 업무상 같은 상태가 아닌데 설명 없이 모두 빈 셀로 취급되지는 않는지 확인합니다.
- 6단계
실제 목적지에서 렌더링하고 검토한 결과만 게시합니다
.md 파일을 복사하거나 다운로드해 실제 GitHub, 위키, 정적 사이트, 문서 빌드에서 렌더링합니다. 표 의미, 긴 셀, 코드 형태 값, 링크, raw HTML 정책, 390px 모바일 넘침, 다크 모드, 키보드 읽기 순서, 최종 diff를 확인하세요. 해당 저장소의 포맷터, 린터, 링크 검사, 접근성 검사, 프로덕션 빌드를 실행하고 검토된 산출물에서만 게시합니다.
예시
뒤에서 추가된 키, 0, 중첩 담당자를 포함한 API fixture 문서화
입력
[{"name":"Ada","active":true,"owner":{"team":"Docs"}},{"name":"Grace","active":false,"score":0,"owner":null}]출력
name, active, owner, score 열이 처음 등장한 순서로 있는 GFM 표입니다. 중첩 owner는 축약 JSON이고 false와 0은 유지되며 null owner는 경고와 함께 빈 셀이 됩니다. 게시 전에 목적지 렌더러에서 확인합니다.흔한 실수
실제 운영 데이터를 편리한 표본으로 사용하기
로컬 변환은 전송 경로 하나를 줄일 뿐 비밀값을 문서, 스크린샷, 클립보드 기록, 브라우저 확장, 소스 관리에 적합하게 만들지 않습니다. 검증에 필요한 구조적 예외만 남긴 정제 fixture를 만드세요.
내보내기 설정 확인 없이 구분자 감지를 믿기
짧거나 단일 열인 표본은 자동 감지 근거가 부족할 수 있습니다. 특히 지역별 세미콜론 내보내기와 탭 보고서는 감지 구분자와 생성 열 수를 원본 애플리케이션 설정과 비교하세요.
표가 정렬돼 보인다는 이유로 경고 무시하기
불균일 행을 채우면 미리보기는 직사각형으로 보이지만 원본에서 값이 이미 이동하거나 빠졌을 수 있습니다. 각 경고를 정확한 원본 레코드까지 추적하고 열 의미가 모호하면 내보내기를 수정하세요.
중첩 JSON이 자동 평탄화됐다고 가정하기
셀 안의 축약 JSON은 정보를 보존하지만 정규화된 스키마가 아닙니다. 중첩 배열이나 객체가 독립 열이 되었다고 설명하지 말고, 원자 열이 필요하면 별도 평탄화 규칙을 정해 문서화하세요.
내장 미리보기만 검토하기
최종 렌더러가 <br> 표시, 엔터티, raw HTML, 긴 단어, 표 넘침을 결정합니다. 독자가 사용하는 빌드, 테마, 모바일 너비에서 생성 파일을 검사하세요.
자주 묻는 질문
9007199254740993 같은 식별자를 JSON 숫자로 사용해도 되나요?
브라우저 작업에서 정확한 숫자가 중요하다면 안 됩니다. 안전한 정수 범위 밖 식별자는 JSON 문자열로 인코딩하고 유형을 명시하세요. 워크벤치는 반올림된 결과를 만드는 대신 거부합니다.
CSV 행마다 열 수가 다르면 어떻게 해야 하나요?
정확한 레코드를 찾고 구분자와 따옴표 규칙을 확인한 뒤 내보내기 스키마와 비교하세요. 끝 셀 누락이 의도적일 수 있지만 열 이동이나 잘못된 따옴표는 게시 전에 원본에서 수정해야 합니다.
중첩 JSON 값을 왜 축약 텍스트로 표시하나요?
하나의 Markdown 셀은 추가 평탄화 정책 없이 중첩 표 계약을 표현할 수 없습니다. 축약 JSON은 값을 정직하게 보존합니다. 원자 열이 필요하면 별도 평탄화 규칙을 선택하고 문서화하세요.
HTML 형태 텍스트 인코딩이 최종 페이지 전체를 정화하나요?
이번 생성 표에서 원본 문자열이 활성 HTML이 되는 것을 막습니다. 전체 문서에 대해서는 목적지가 자체 Markdown, raw HTML, 링크, 콘텐츠 보안 정책을 계속 적용해야 합니다.
게시된 표에는 어떤 검증 증거를 남겨야 하나요?
정제한 원본 fixture, 선택 옵션, 예상 행·열 수, 해결한 경고 기록, 생성 Markdown diff, 목적지 렌더링 확인, 관련 빌드·접근성 결과를 보관하세요.