01

상대 링크에는 출발점이 있습니다

상대 링크에는 출발점이 있습니다 핵심 안내 도식
핵심 읽기 · 상대 링크에는 출발점이 있습니다

README 안의 링크가 잘 열리다가 문서를 하위 폴더로 옮긴 뒤 깨졌다면, 대상 파일이 사라졌는지부터 단정하지 마세요. 링크가 현재 문서를 기준으로 경로를 읽는지 확인합니다. 같은 글자를 적었더라도 출발 폴더가 바뀌면 다른 위치를 가리킬 수 있습니다.

이 글은 GitHub 저장소 안에서 렌더링되는 Markdown 문서를 기준으로 합니다. 일반 웹사이트나 다른 편집기의 경로 처리까지 모두 같다고 가정하지 않습니다. 실제 자료를 이동하기 전에 복사한 작은 연습 폴더에서 문서와 이미지의 위치를 나란히 적어 보면 관계를 이해하기 쉽습니다.

02

세 파일로 작은 구조를 만듭니다

세 파일로 작은 구조를 만듭니다 핵심 안내 도식
핵심 읽기 · 세 파일로 작은 구조를 만듭니다

가상의 저장소 루트에 README.md, docs 폴더에 setup.md, assets 폴더에 map.png가 있다고 가정합니다. 루트 README에서 docs/setup.md는 같은 루트 아래의 docs 폴더로 들어가는 경로입니다. 그림을 가리키는 assets/map.png도 같은 방식으로 읽습니다.

가상 파일명은 예시를 위한 것이며 실제 프로젝트에서 자동 생성되는 파일이 아닙니다. 폴더 구조를 먼저 그리고 각 파일이 존재하는지 확인하세요. 링크 문구가 “설정 안내”처럼 자연스러워도 괄호 안 경로가 다른 곳을 가리킬 수 있습니다. 화면에 보이는 제목과 실제 대상 경로를 따로 읽는 것이 출발점입니다.

03

문서를 옮겼다면 출발 위치를 다시 잡습니다

문서를 옮겼다면 출발 위치를 다시 잡습니다 핵심 안내 도식
핵심 읽기 · 문서를 옮겼다면 출발 위치를 다시 잡습니다

README를 docs/README.md로 옮기고 링크에 docs/setup.md를 그대로 남기면 현재 docs 폴더 아래의 docs/setup.md를 찾게 됩니다. 대상 setup.md가 같은 폴더에 있다면 예시 링크는 setup.md가 됩니다. 문서 이동 전의 문자열을 그대로 복사하는 것이 항상 같은 대상을 보존하지는 않습니다.

그림 assets/map.png는 저장소 루트 아래에 있으므로 docs의 문서에서는 ../assets/map.png처럼 한 단계 위로 올라가는 경로로 설명할 수 있습니다. 이 예시는 GitHub Markdown의 상대 경로 규칙을 적용한 것입니다. 폴더 이름이나 파일 위치가 다른 프로젝트에 문자열만 붙여 넣지 마세요.

한눈에 비교하기
상황별 확인 항목 — 작은 화면에서는 표를 좌우로 밀어 볼 수 있습니다.
출발 문서가리킬 파일예시 상대 경로
README.mddocs/setup.mddocs/setup.md
docs/README.mddocs/setup.mdsetup.md
README.mdassets/map.pngassets/map.png
docs/README.mdassets/map.png../assets/map.png
04

문서 링크와 이미지 경로를 함께 점검합니다

문서 링크와 이미지 경로를 함께 점검합니다 핵심 안내 도식
핵심 읽기 · 문서 링크와 이미지 경로를 함께 점검합니다

문서의 이동은 본문 링크뿐 아니라 삽입한 이미지에도 영향을 줄 수 있습니다. 링크만 눌러 보고 끝내면 설명 그림이 사라진 상태를 놓칠 수 있으므로 렌더링된 문서에서 둘 다 확인합니다. 이미지가 보이지 않을 때는 경로와 실제 파일명, 확장자를 대조합니다.

GitHub 공식 문서는 현재 브랜치에 맞춰 상대 링크와 이미지 경로를 처리한다고 설명합니다. 따라서 한 브랜치에서 존재한 대상 파일이 다른 브랜치에도 있는지는 따로 확인해야 합니다. 상대 경로의 계산이 맞다는 것과 현재 브랜치에 파일이 있다는 것은 별개의 확인 항목입니다.

05

수정한 링크를 실제로 열어 봅니다

수정한 링크를 실제로 열어 봅니다 핵심 안내 도식
핵심 읽기 · 수정한 링크를 실제로 열어 봅니다

가상 연습에서는 docs/README.md의 설정 안내를 열어 docs/setup.md에 도착하는지 봅니다. 그림도 기대한 map.png인지 확인합니다. 오류 화면이 사라졌다고 무조건 성공으로 적지 말고 도착한 문서 제목과 경로까지 대조하세요. 다른 파일이 우연히 같은 위치에 있을 수 있기 때문입니다.

검사 결과는 “문서 경로 → 대상 경로 → 확인 결과”로 남깁니다. 파일 이동을 함께 검토하는 사람이 있으면 이전과 이후 위치를 나란히 보여 주세요. 작업은 예시 저장소의 파일로만 수행하고, 실제 프로젝트에 적용할 때는 변경 목록에 관계없는 파일 이동이 섞이지 않았는지도 확인합니다.

06

링크를 고정할 목적과 구분합니다

링크를 고정할 목적과 구분합니다 핵심 안내 도식
핵심 읽기 · 링크를 고정할 목적과 구분합니다

현재 브랜치의 문서끼리 이동하려는 목적과 특정 시점의 코드를 증거로 남기려는 목적은 다릅니다. 전자는 상대 링크가 편리할 수 있지만, 특정 변경 이전의 줄을 가리키려면 해당 버전의 고정 링크를 별도로 검토할 일입니다. 하나의 링크 방식이 모든 목적을 해결하지는 않습니다.

문서를 옮긴 뒤에는 그 문서를 가리키던 다른 문서의 링크도 확인하세요. 안에서 밖으로 나가는 링크만 고쳐도 외부의 진입 링크는 옛 위치에 남을 수 있습니다. 작은 폴더 구조와 실제 도착 확인을 함께 사용하면 링크 문자열을 추측해서 여러 번 바꾸는 일을 줄일 수 있습니다.

WORKBOOK

직접 적용해 보기: 문서 위치가 출발점

가상 README를 루트에서 docs 폴더로 옮긴 뒤 설정 안내와 그림이 열리지 않는 상황입니다.

  1. 01

    README와 대상 문서·그림의 실제 위치를 그립니다.

  2. 02

    새 출발 위치에서 setup.md와 ../assets/map.png를 계산합니다.

  3. 03

    렌더링된 문서에서 링크 도착 경로와 그림을 확인합니다.

남길 결과물

문서 이동 전후 경로와 실제 열림 결과를 적은 작은 검토표입니다.

여기서 자주 놓치는 점

문서를 옮긴 뒤 경로 문자열만 그대로 유지하면 같은 파일을 가리킨다고 생각하지 않습니다.

편집팀이 구성한 설명용 예시입니다. 실제 이용 후기나 측정 결과가 아닙니다.