내부 링크 검수 보고서

이 감사의 기준 시점과 방법

이 문서는 현재 작성된 T2Editor 문서 세트의 내부 링크 구조를 전수 점검한 결과를 기록합니다. 이번 검수의 목표는 다음 네 가지였습니다.

1. 문서 front matter의 related_docs 값이 실제 파일명과 맞는지 확인
2. 본문 안에서 다른 문서를 언급할 때 깨진 상대경로가 없는지 확인
3. 단순 파일명 텍스트로만 적혀 있어 클릭할 수 없던 참조를 실제 내부 링크로 보완
4. 중복되거나 헷갈릴 수 있는 문서 간 참조가 최소한 상호 이동 가능하도록 정리

검수 결과 요약

검수 결과 요약

재실측 근거: 84건 전문 파싱 스크립트 w2-linkgraph.mjs 실행 결과(audit/W2-linkgraph.json). [[...]] 3계열을 분리해 세었습니다 — 문서 1건 · 태그/분류 페이지 22회(별도 계층) · 끊어진 링크 91회.

파일명 표기 보완: 4개 문서를 상대경로로 변경했으나

이 수정은 탐색성을 개선하지 못했고 "점검 완료" 신호만 만들었습니다. 위키 엔진은 이 문법을 링크로 인식하지 않습니다. 올바른 내부 링크는 [[슬러그]] 문법이며 뷰 URL은 slug에 확장자가 붙은 값을 요구합니다.

이번 감사에서 수정한 4개 문서(재실측 기준)

• 08-developer-architecture-entry
• 09-developer-architecture-entry
• 72-version-issues-guide
• 99-audit-and-remediation-report

→ 2026-09-28 개정에서 위 4건에 본문 [[...]] 링크가 추가되었습니다. 링크 표준화는 아래 "내부 링크 표준화 (수정)"를 따릅니다.

검수 기준

1. front matter 기준

각 문서의 상단 메타데이터 중 related_docs 항목을 확인했습니다. 검사 기준은 다음과 같습니다.

• 같은 폴더에 실제 존재하는 .md 파일명인지
• 확장자가 빠진 경우 .md를 붙이면 실제 파일이 존재하는지
• 파일명이 중간에 변경된 흔적이 없는지

당시(9.0.0 기준)에는 깨진 참조를 발견하지 못했습니다. 2026-09-28 재실측에서는 related_docs 값 69개 중 25개(36.2%)가 가리키는 문서가 없습니다. 전부 버전 접미를 떼어쓴 슬러그입니다(예: guide-nsfwjs-overview → 실제 guide-nsfwjs-overview.v9.1.0.md). 또한 일부 문서에는 하이픈이 U+2011(NON-BREAKING HYPHEN)로 들어가 있어 문자열 비교로 어떤 문서와도 일치하지 않습니다.

2. 본문 기준

본문 안에서 다음과 같은 형식의 문서 참조를 검사했습니다.

• 00-overview-macro-guide.md
• core-editor-lib-php.md
• plugin-ai.md
• directory-plugin-guide.md

이 가운데 존재하지 않는 파일명은 발견되지 않았습니다. 다만 일부 문서는 파일명을 코드 표기만 하고 링크로 연결하지 않아 탐색성이 떨어졌습니다. 이번에 그 부분을 상대경로 링크로 보완했습니다.

아쉬운 점과 후속 보완 제안

당시 기준으로는 깨진 링크를 발견하지 못했으나, 2026-09-28 재실측에서 [[...]] 끊어진 링크 91건이 확인되었습니다. 위키 엔진이 파싱하는 [[...]]는 84건 중 대부분이 서버 키와 달라 문서 간 연결은 사실상 0입니다. 아래 보완 항목에 이를 포함합니다.

중복 성격 문서

• 08-developer-architecture-entry.md
• 09-developer-architecture-entry.md

두 문서가 모두 개발자 진입 성격을 띠고 있어 제목만 보면 혼동할 수 있습니다. 다음 개정 때는 하나는 “빠른 진입”, 다른 하나는 “심층 구조 진입”처럼 역할을 더 명확하게 나누는 편이 좋습니다.

front matter와 본문의 동기화

related_docs는 잘 연결되어 있으나, 본문의 “관련 문서” 섹션이 있는 문서와 없는 문서의 편차가 있습니다. 다음 정리 단계에서는 모든 문서에 공통 형식으로 아래 섹션을 넣는 것이 좋습니다.

• 관련 문서
• 먼저 읽을 문서
• 이어서 읽을 문서
• 관련 코어 문서
• 관련 플러그인 문서

내부 링크 표준화 (수정)

앞으로는 다른 문서를 언급할 때 본문에서는 [[슬러그]]만 씁니다.

1. 본문 링크는 [[슬러그]] 문법을 사용합니다. 위키의 백링크·링크맵이 이 문법만 파싱합니다.
2. [[...]] 안에는 서버 문서 키를 그대로 씁니다 — 확장자 .md를 반드시 포함하십시오. 실측: slug=01-installation-guide.md 는 200, slug=01-installation-guide 는 빈 페이지입니다. 서버 문서 키는 index.json 기준 {번호}-{슬러그}.md 형식이므로, 링크를 만들 때 실제 서버 키와 대조하십시오.
3. 태그는 문서 링크가 아닙니다. 태그 페이지는 view&slug= 로 열리지 않습니다. 태그를 언급할 때는 백틱 표기 ` 분류:태그명 ` 또는 일반 텍스트로 쓰십시오.
4. related_docs 배열은 본문 링크와 별개입니다. 배열 값은 서버 문서 키와 일치하는지 별도로 확인해야 합니다.
5. [x.md](x.md) 마크다운 상대경로는 사용하지 않습니다. 엔진이 링크로 인식하지 않아 탐색성이 오르지 않습니다.
6. 문서 슬러그는 slug와 document_id가 일치해야 합니다. 현재 70·71·72는 frontmatter slug이 서버 키와 달라 서로 다른 문서를 가리킬 수 있습니다.

권장 후속 작업

• related_docs를 이용해 자동 “관련 문서” 블록을 렌더링하는 허브 기능 추가
• 08/09 개발자 진입 문서의 역할 분리
• 모든 문서 하단에 표준 내부 링크 블록 삽입
• 플러그인 문서 ↔ 코어 문서 사이의 상호 링크 확대
• 디렉터리 문서 ↔ 파일 문서 사이의 탐색 링크 강화

참고

• 00-overview-macro-guide.md — 거시적 안내서
• 73-external-reference-index.md — 외부 자료 참고 인용 정리
• 99-audit-and-remediation-report.md — 문서 감사 및 보완 보고서
• 01-installation-guide.md · 06-version-compatibility-guide.md — 기준이 된 사용자 문서 2건

이 보고서는 9.0.0 기준 문서 세트(64건)를 대상으로 작성되었고, 2026-09-28에 84건 전체로 재실측해 결과를 정정했습니다. 재현 명령은 node scripts/w2-linkgraph.mjs이며 출력은 audit/W2-linkgraph.json입니다. 파일명·문서 추가가 발생하면 같은 스크립트로 다시 측정하십시오. 2026-09-28 통합관의 링크 정합 검사 스크립트는 node scripts/m1-linkcheck.mjs 입니다.