내부 링크 검수 보고서
이 문서는 현재 작성된 T2Editor 문서 세트의 내부 링크 구조를 전수 점검한 결과를 기록합니다. 이번 검수의 목표는 다음 네 가지였습니다.
- 문서 front matter의
related_docs값이 실제 파일명과 맞는지 확인 - 본문 안에서 다른 문서를 언급할 때 깨진 상대경로가 없는지 확인
- 단순 파일명 텍스트로만 적혀 있어 클릭할 수 없던 참조를 실제 내부 링크로 보완
- 중복되거나 헷갈릴 수 있는 문서 간 참조가 최소한 상호 이동 가능하도록 정리
검수 결과 요약
- 총 검사 문서 수: 64개
- front matter
related_docs검사 결과: 깨진 참조 0건 - 본문 내
.md파일명 참조 검사 결과: 존재하지 않는 파일 참조 0건 - 클릭 불가능한 파일명 표기 보완: 4개 문서 수정
- 신규 보고서 문서 추가: 1개
실제 수정한 문서
아래 문서는 본문에 다른 문서 파일명이 일반 텍스트 또는 코드 표기 형태로만 적혀 있어, 클릭 가능한 상대경로 링크로 바꿨습니다.
- 08-developer-architecture-entry.md
- 09-developer-architecture-entry.md
- 72-version-issues-guide.md
- 99-audit-and-remediation-report.md
검수 기준
1. front matter 기준
각 문서의 상단 메타데이터 중 related_docs 항목을 확인했습니다. 검사 기준은 다음과 같습니다.
- 같은 폴더에 실제 존재하는
.md파일명인지 - 확장자가 빠진 경우
.md를 붙이면 실제 파일이 존재하는지 - 파일명이 중간에 변경된 흔적이 없는지
현재 세트에서는 related_docs 기준으로 깨진 참조는 발견되지 않았습니다.
2. 본문 기준
본문 안에서 다음과 같은 형식의 문서 참조를 검사했습니다.
00-overview-macro-guide.mdcore-editor-lib-php.mdplugin-ai.mddirectory-plugin-guide.md
이 가운데 존재하지 않는 파일명은 발견되지 않았습니다. 다만 일부 문서는 파일명을 코드 표기만 하고 링크로 연결하지 않아 탐색성이 떨어졌습니다. 이번에 그 부분을 상대경로 링크로 보완했습니다.
아쉬운 점과 후속 보완 제안
현재 내부 링크는 깨지지 않지만, 아래 부분은 앞으로 더 보완할 수 있습니다.
중복 성격 문서
두 문서가 모두 개발자 진입 성격을 띠고 있어 제목만 보면 혼동할 수 있습니다. 다음 개정 때는 하나는 “빠른 진입”, 다른 하나는 “심층 구조 진입”처럼 역할을 더 명확하게 나누는 편이 좋습니다.
front matter와 본문의 동기화
related_docs는 잘 연결되어 있으나, 본문의 “관련 문서” 섹션이 있는 문서와 없는 문서의 편차가 있습니다. 다음 정리 단계에서는 모든 문서에 공통 형식으로 아래 섹션을 넣는 것이 좋습니다.
- 관련 문서
- 먼저 읽을 문서
- 이어서 읽을 문서
- 관련 코어 문서
- 관련 플러그인 문서
내부 링크 표준화
앞으로는 다른 문서를 언급할 때 아래 형식 중 하나로 통일하는 것이 좋습니다.
- 일반 링크: 문서 제목 + 실제 파일명 링크 형식
- 파일명 링크: `
파일명.md` 또는 실제 파일 링크 형식
이 원칙을 지키면 검색 허브와 별개로 폴더 브라우징만 하더라도 문서 간 이동이 훨씬 쉬워집니다.
권장 후속 작업
related_docs를 이용해 자동 “관련 문서” 블록을 렌더링하는 허브 기능 추가- 08/09 개발자 진입 문서의 역할 분리
- 모든 문서 하단에 표준 내부 링크 블록 삽입
- 플러그인 문서 ↔ 코어 문서 사이의 상호 링크 확대
- 디렉터리 문서 ↔ 파일 문서 사이의 탐색 링크 강화
참고
이 보고서는 현재 문서 세트를 기준으로 작성되었으며, 이후 파일명 변경이나 문서 추가가 발생하면 다시 점검해야 합니다.