자주 묻는 질문: 테이블이 포맷팅되지 않는 문제 해결
학습 후 할 수 있는 것
이 수업에서는 플러그인 사용 중 발생하는 일반적인 문제를 빠르게 진단하고 해결하는 방법을 배웁니다:
- 테이블이 포맷팅되지 않는 원인 찾기
- "유효하지 않은 테이블 구조" 오류의 의미 이해
- 플러그인의 알려진 제한 사항 및 적용되지 않는 시나리오 이해
- 구성이 올바른지 빠르게 확인
문제 1: 테이블이 자동으로 포맷팅되지 않음
증상
AI가 테이블을 생성했지만 테이블 열 너비가 일관되지 않고 정렬되지 않음.
가능한 원인 및 해결 방법
원인 1: 플러그인이 구성되지 않음
확인 단계:
.opencode/opencode.jsonc파일 열기- 플러그인이
plugin배열에 있는지 확인:
{
"plugin": ["@franlol/opencode-md-table-formatter@0.0.3"]
}- 없으면 플러그인 구성 추가
- OpenCode 재시작하여 구성 적용
구성 형식
버전 번호와 패키지 이름이 올바른지 확인하세요. @franlol/opencode-md-table-formatter + @ + 버전 번호 형식을 사용하세요.
원인 2: OpenCode가 재시작되지 않음
해결 방법:
플러그인을 추가한 후에는 OpenCode를 완전히 재시작해야 합니다(페이지 새로고침이 아님). 그래야 플러그인이 로드됩니다.
원인 3: 테이블에 구분선이 없음
증상 예시:
| Name | Age |
| Alice | 25 |
| Bob | 30 |이러한 테이블은 포맷팅되지 않습니다.
해결 방법:
구분선 추가(두 번째 행, |---| 형식 사용):
| Name | Age |
|--- | ---|
| Alice | 25 |
| Bob | 30 |구분선 역할
구분선은 Markdown 테이블의 표준 구문으로, 헤더와 콘텐츠 행을 구분하고 정렬 방식을 지정하는 데 사용됩니다. 플러그인은 구분선을 감지해야만 테이블을 포맷팅합니다.
원인 4: OpenCode 버전이 너무 낮음
확인 단계:
- OpenCode 도움말 메뉴 열기
- 현재 버전 번호 확인
- 버전 >= 1.0.137인지 확인
해결 방법:
최신 버전의 OpenCode로 업그레이드하세요.
버전 요구사항
플러그인은 experimental.text.complete 훅을 사용하며, 이 API는 OpenCode 1.0.137+ 버전에서 사용할 수 있습니다.
문제 2: "invalid structure" 주석이 표시됨
증상
테이블 끝에 다음이 나타남:
<!-- table not formatted: invalid structure -->"유효하지 않은 테이블 구조"란 무엇인가
플러그인은 각 Markdown 테이블을 검증하며, 검증을 통과한 테이블만 포맷팅됩니다. 테이블 구조가 사양에 맞지 않으면 플러그인은 원본을 유지하고 이 주석을 추가합니다.
일반적인 원인
원인 1: 테이블 행 수가 부족함
오류 예시:
| Name |행이 1개뿐이며 형식이 불완전함.
올바른 예시:
| Name |
|---|최소 2행(구분선 포함)이 필요함.
원인 2: 열 수가 일관되지 않음
오류 예시:
| Name | Age |
|--- | ---|
| Alice |첫 번째 행은 2열, 두 번째 행은 1열로 열 수가 일관되지 않음.
올바른 예시:
| Name | Age |
|--- | ---|
| Alice | 25 |모든 행의 열 수가 같아야 함.
원인 3: 구분선이 없음
오류 예시:
| Name | Age |
| Alice | 25 |
| Bob | 30 ||---|---|와 같은 구분선이 없음.
올바른 예시:
| Name | Age |
|--- | ---|
| Alice | 25 |
| Bob | 30 |빠르게 진단하는 방법
다음 확인 목록을 사용하세요:
- [ ] 테이블에 최소 2행이 있음
- [ ] 모든 행의 열 수가 같음(각 행에 몇 개의
|가 있는지 세어보세요) - [ ] 구분선이 존재함(두 번째 행은 보통
|---|형식)
위의 모든 조건을 만족하지만 여전히 오류가 발생하는 경우 숨겨진 문자나 불필요한 공백으로 인해 열 수 계산 오류가 발생하지 않았는지 확인하세요.
문제 3: "table formatting failed" 주석이 표시됨
증상
텍스트 끝에 다음이 나타남:
<!-- table formatting failed: {오류 정보} -->원인
플러그인 내부에서 예상치 못한 예외가 발생함.
해결 방법
- 오류 정보 확인: 주석의
{오류 정보}부분에 구체적인 문제가 설명되어 있음 - 테이블 콘텐츠 확인: 극단적인 특수 상황(초과 긴 단일 행, 특수 문자 조합 등)이 있는지 확인
- 원본 유지: 실패하더라도 플러그인은 원본을 손상하지 않으므로 콘텐츠는 안전함
- 문제 보고: 문제가 반복적으로 발생하면 GitHub Issues에 문제 보고서 제출
오류 격리
플러그인은 try-catch로 포맷팅 로직을 감싸므로 오류가 발생해도 OpenCode 워크플로우가 중단되지 않습니다.
문제 4: 특정 테이블 유형이 지원되지 않음
지원되지 않는 테이블 유형
HTML 테이블
지원되지 않음:
<table>
<tr><th>Name</th></tr>
<tr><td>Alice</td></tr>
</table>지원됨: Markdown 파이프 테이블(Pipe Table)만
다중 행 셀
지원되지 않음:
| Name | Description |
|--- | ---|
| Alice | Line 1<br>Line 2 |지원되지 않는 이유
플러그인은 AI가 생성한 간단한 테이블용으로 설계되었으며, 다중 행 셀은 더 복잡한 레이아웃 로직이 필요합니다.
구분선 없는 테이블
지원되지 않음:
| Name | Age |
| Alice | 25 |
| Bob | 30 |구분선이 있어야 함(위의 "원인 3" 참조).
문제 5: 테이블 포맷팅 후에도 여전히 정렬되지 않음
가능한 원인
원인 1: 숨김 모드가 활성화되지 않음
플러그인은 OpenCode의 숨김 모드(Concealment Mode)에 최적화되어 있으며, 이 모드는 Markdown 기호(**, * 등)를 숨깁니다.
편집기에서 숨김 모드가 활성화되지 않은 경우 Markdown 기호가 실제 너비를 차지하므로 테이블이 "정렬되지 않은" 것처럼 보일 수 있습니다.
해결 방법:
OpenCode 숨김 모드가 활성화되어 있는지 확인(기본적으로 활성화됨).
원인 2: 셀 콘텐츠가 너무 김
특정 셀의 콘텐츠가 매우 긴 경우 테이블이 매우 넓게 늘어날 수 있습니다.
이것은 정상적인 동작이며 플러그인은 콘텐츠를 자르지 않습니다.
원인 3: 인라인 코드 내의 기호
인라인 코드(`**code**`) 내의 Markdown 기호는 리터럴 너비로 계산되며 스트리핑되지 않습니다.
예시:
| 符号 | 宽度 |
|--- | ---|
| 普通文本 | 4 |
| `**bold**` | 8 |이것은 올바른 동작이며 숨김 모드에서 코드 블록 내의 기호는 표시되기 때문입니다.
이 수업 요약
이 수업에서 다음을 배웠습니다:
- 테이블이 포맷팅되지 않는 문제 진단: 구성, 재시작, 버전 요구사항, 구분선 확인
- 유효하지 않은 테이블 오류 이해: 행 수, 열 수, 구분선 검증
- 알려진 제한 사항 식별: HTML 테이블, 다중 행 셀, 구분선 없는 테이블은 지원되지 않음
- 빠른 자체 확인: 확인 목록을 사용하여 테이블 구조 검증
여전히 해결되지 않았나요?
위의 모든 문제를 확인했지만 문제가 계속되는 경우:
- 전체 로그 확인: 플러그인은 기본적으로 조용히 실행되며 상세한 로그가 없음
- Issue 제출: GitHub Issues에 테이블 예시와 오류 정보 제공
- 고급 수업 참조: 테이블 사양 및 숨김 모드 원리를 읽어 더 많은 기술 세부사항 이해
다음 수업 미리보기
다음 수업에서는 **알려진 제한 사항: 플러그인의 경계는 어디까지인가**를 학습합니다.
다음을 배우게 됩니다:
- 플러그인의 설계 경계 및 제약 조건
- 향후 가능한 기능 향상
- 시나리오가 이 플러그인 사용에 적합한지 판단하는 방법
부록: 소스 코드 참조
클릭하여 소스 코드 위치 펼치기
업데이트 시간: 2026-01-26
| 기능 | 파일 경로 | 행 번호 |
|---|---|---|
| 테이블 검증 로직 | index.ts | 70-88 |
| 테이블 행 검출 | index.ts | 58-61 |
| 구분선 검출 | index.ts | 63-68 |
| 오류 처리 | index.ts | 15-20 |
| 유효하지 않은 테이블 주석 | index.ts | 44-47 |
핵심 비즈니스 규칙:
isValidTable(): 테이블이 최소 2행, 모든 행의 열 수가 일치, 구분선이 존재하는지 검증(70-88행)isSeparatorRow(): 정규식/^\s*:?-+:?\s*$/을 사용하여 구분선 검출(63-68행)- 열 최소 너비: 3 문자(115행)
오류 처리 메커니즘:
- try-catch로 주요 처리 함수 감싸기(15-20행)
- 포맷팅 실패: 원본 유지 +
<!-- table formatting failed: {message} -->주석 추가 - 검증 실패: 원본 유지 +
<!-- table not formatted: invalid structure -->주석 추가