Mac의 Obsidian에서 편집하고 GitHub에서 읽는 Markdown 노트에는 표준 Markdown 링크와 고유한 소문자 제목을 사용하세요. setup 같은 단일 단어는 두 렌더러에서 같은 대상으로 연결되지만, 공백이 있는 제목은 더 세심한 주의가 필요합니다.

이 가이드는 노트 내부와 두 Markdown 파일 사이의 탐색에 중점을 둡니다. 실용적인 목표는 모든 Markdown 렌더러가 제목 대상을 똑같이 해석한다고 가정하지 않으면서 읽기 쉬운 문서 하나를 유지하는 것입니다.

유효한 Markdown 링크가 제목으로 이동하지 않는 이유는 무엇인가요?

제목 링크에는 두 가지 별도 요구 사항이 있습니다. Markdown 파서가 링크를 인식해야 하고, 렌더러가 링크 대상을 찾아야 합니다. 링크를 클릭할 수 있으면 첫 번째 요구 사항이 충족된 것입니다. 의도한 섹션에 도달해야 두 번째 요구 사항이 충족된 것입니다.

CommonMark는 제목 구문과 [link](#fragment)을 포함한 조각 식별자가 있는 링크를 정의합니다. 제목 예시는 보편적인 제목 ID 생성 알고리즘을 규정하지 않습니다. 이 차이 때문에 유효한 Markdown 구문만으로는 여러 애플리케이션에서 섹션 탐색이 일치한다고 보장할 수 없습니다. CommonMark 제목 명세와 링크 명세를 참조하세요.

GitHub는 제목 앵커를 만들 때 문자를 소문자로 바꾸고, 공백을 하이픈으로 바꾸며, 그 밖의 문장 부호와 서식을 제거합니다. 같은 앵커가 반복되면 숫자 접미사로 구분합니다. Obsidian은 # 뒤에 오는 제목 텍스트를 사용해 제목 링크를 작성합니다. 두 앱의 대상 규칙은 서로 다릅니다. GitHub의 섹션 링크 규칙과 Obsidian의 내부 링크 문서를 참조하세요.

Obsidian은 CommonMark와 GitHub Flavored Markdown을 자체 확장 기능과 함께 지원합니다. 하지만 그렇다고 해서 애플리케이션별 링크를 모두 서로 바꿔 쓸 수 있는 것은 아닙니다. Obsidian은 일부 확장 기능이 다른 앱에서는 일반 텍스트로 표시될 수 있다고 명시적으로 경고합니다. Markdown 호환성 문서에서 이 한계를 설명합니다.

두 렌더러에서 같은 대상으로 연결되는 제목 규칙은 무엇인가요?

여러 앱에서 공유할 새 노트에는 고유한 제목을 사용하세요. 제목은 소문자 ASCII 문자로 구성하고, 가능하면 한 단어로 작성합니다. 긴 제목에는 desk-layout 같은 형식이 유용합니다. 표시되는 제목 텍스트가 이미 GitHub 스타일의 조각 식별자와 일치하기 때문입니다.

이는 별도의 호환성 기능이 아니라 문서화된 규칙에서 도출한 관례입니다. setup에는 공백이나 대문자, 서식이 없어 두 렌더러가 다르게 해석할 요소가 없습니다. 표시되는 제목과 대상도 쉽게 비교할 수 있습니다.

파일에 적힌 제목 Obsidian 제목 텍스트 대상(URL 인코딩됨) GitHub에서 생성하는 대상
## setup #setup #setup
## desk-layout #desk-layout #desk-layout
## Desk Layout #Desk%20Layout #desk-layout

이 표에는 Obsidian의 제목 텍스트 및 URL 인코딩 지침과 GitHub 앵커 규칙이 적용됩니다. Obsidian이 GitHub 방식으로 정규화된 조각 식별자를 모두 지원한다고 가정하지 않습니다.

눈에 보이는 절충점이 있습니다. desk-layout은 일반적인 섹션 제목이라기보다 식별자처럼 읽힙니다. 자연스러운 제목이 더 중요하다면 제목을 그대로 두고 두 앱에서 링크가 올바르게 연결되는지 확인하세요. 독자에게 어느 쪽이 적합한지 결정하기 전에 문서 전체의 제목을 바꾸지는 마세요.

직접 확인해 볼 전체 노트

desk-notes.md라는 노트를 만들고 아래 Markdown을 붙여 넣으세요. 이것은 가상의 콘텐츠를 사용한 완전한 예시 문서입니다. 코드 펜스는 원본을 보여 주기 위한 것입니다.

Desk notes

Jump to [setup](#setup), [materials](#materials), or
[desk layout](#desk-layout).

## setup

Place the notebook beside the keyboard.

## materials

Use a notebook, a pencil, and a desk tray.

## desk-layout

Keep the tray beside the notebook.

Return to [setup](#setup).

링크 레이블에는 일반적인 띄어쓰기를 사용할 수 있습니다. [desk layout](#desk-layout)는 읽기 쉬운 텍스트로 표시되면서 대상은 그대로 유지합니다. 모든 탐색 레이블을 제목 식별자와 같은 형태로 만들 필요는 없습니다.

실제 노트에서는 탐색이 눈에 띄도록 섹션에 충분한 내용을 넣으세요. 문서가 아주 짧으면 노트 전체가 이미 창 안에 들어와 링크를 눌러도 거의 이동하지 않을 수 있습니다.

Mac에서 Obsidian을 어떻게 설정하고 테스트하나요?

먼저 노트 자체를 살펴본 뒤 Obsidian이 앞으로 링크를 생성하는 방식을 조정하세요. 둘은 별도로 확인해야 합니다. 링크 생성 기본 설정을 바꾸는 것만으로 기존 Markdown을 확인할 수는 없습니다.

  1. 사이드바에서 Settings를 엽니다.
  2. Files and links에서 Use Wikilinks를 꺼서 생성되는 링크에 Markdown 구문을 사용하도록 합니다.
  3. 공유 파일 사이의 링크에는 New link format을 Relative path to file로 설정합니다.
  4. 새 설정에 의존하기 전에 기존 링크 대상을 확인합니다.

Obsidian은 데스크톱 설정 화면에 들어가는 방법과 두 가지 링크 생성 기본 설정을 Settings에서 설명합니다. 공유 폴더 구조가 명확해지므로 여기에는 상대 경로를 사용하는 것이 좋습니다.

샘플 노트를 Command+E로 Reading view로 전환한 다음 각 탐색 링크를 클릭하세요. Obsidian은 macOS에서 이 단축키를 사용할 수 있다고 설명하며, 읽기 보기에서는 Markdown 구문이 숨겨진다고 안내합니다. 편집 동작과 탐색 테스트를 섞지 말고 반복 가능한 확인을 위해 같은 보기를 사용하세요. 보기 및 편집 모드를 참조하세요.

그다음 GitHub에서 렌더링된 파일을 확인합니다. 제목 위에 마우스를 올리고 링크 아이콘을 클릭해 실제 조각 식별자를 확인하세요. 그 식별자를 원본 링크에서 # 뒤에 오는 텍스트와 비교합니다. GitHub는 섹션 링크에서 이 확인 방법을 설명합니다.

간단한 승인 체크리스트를 사용하세요. 링크가 링크로 표시되고, 의도한 파일을 선택하며, 의도한 제목으로 이동해야 합니다. 여러 제목을 한꺼번에 바꾸는 대신 대상별로 실패를 기록하세요. 그러면 수정이 파일 이름, 경로, 조각 식별자 중 무엇을 해결했는지 파악하기 쉽습니다.

다른 파일의 제목으로 연결하려면 어떻게 하나요?

먼저 간단한 예시부터 시작하세요. 파일 두 개를 나란히 둡니다. desk-notes.md과 같은 폴더에 index.md를 만들고 다음 내용을 모두 입력합니다.

Desk index

Read the [setup notes](desk-notes.md#setup).

Review the [desk layout](desk-notes.md#desk-layout).

대상은 두 부분으로 이루어집니다. desk-notes.md은 파일을 선택하고 #setup은 섹션을 선택합니다. GitHub는 현재 파일을 기준으로 상대 파일 링크를 해석하며, Obsidian에는 상대 경로를 생성하는 설정이 있습니다. 문서에 설명된 이 동작을 활용하면 같은 폴더에 파일을 두고 사용할 수 있습니다. GitHub 상대 링크와 Obsidian 링크 설정을 참조하세요.

이 문서를 읽을 때도 같은 상대적 배치를 유지하세요. index.md만 하위 폴더로 옮기면 기존의 형제 파일 대상은 더 이상 처음의 파일 배치를 가리키지 않습니다. 제목을 살펴보기 전에 경로를 다시 계산하세요.

공유 파일 링크에는 .md 확장자를 명시하세요. 파일 이름에 공백이 있으면 Obsidian의 URL 인코딩 지침에 따라 Markdown 대상에 %20을 사용하세요. 공백을 인코딩해도 공백은 그대로 남습니다. 제목이 GitHub의 하이픈으로 구분된 앵커로 바뀌는 것은 아닙니다.

기존 제목과 끊어진 링크는 어떻게 처리해야 하나요?

플러그인이나 추가 앵커 방식을 도입하기 전에 다음 진단 순서를 따르세요. 문서에서 문제가 발생한 가장 작은 부분을 분리할 수 있습니다.

  1. 제목 원본을 확인합니다. 대상이 ## setup처럼 실제 Markdown 제목인지 확인합니다. 여는 해시 뒤에 공백도 있어야 합니다. CommonMark에서는 텍스트가 있는 제목에 이 공백이 필요합니다. ATX 제목을 참조하세요.
  2. 링크 구문을 확인합니다. [setup](#setup)을 사용하세요. 닫는 대괄호와 여는 괄호 사이를 붙여 씁니다. [setup] (#setup)은 CommonMark 링크 규칙에 따른 인라인 링크가 아닙니다.
  3. 파일 경로 확인과 섹션 이동 확인을 분리합니다. 다른 파일로 이동하는 링크가 실패하면 조각 식별자를 잠시 빼고 파일 링크를 테스트합니다. 이마저 실패하면 먼저 경로를 수정하세요.
  4. 제목 텍스트와 조각 식별자를 비교합니다. Desk Layout 같은 자연스러운 제목이라면 위의 렌더러 비교를 다시 확인하세요. %20를 -로 바꾸면 대상 규칙이 달라집니다.
  5. 대상이 반복되는지 확인합니다. notebook-setup과 tray-setup처럼 서로 다른 이름을 우선 사용하세요. GitHub의 숫자 접미사는 중복 앵커의 순서에 따라 달라지므로 순서를 바꾸면 대상도 바뀔 수 있습니다. GitHub 섹션 링크를 참조하세요.

문서에 자연스러운 섹션 제목이 이미 있다면 가장 유용한 탐색 링크부터 수정하세요. 조각 식별자를 일치시키면 제목이 어색해지는 경우에는, 확인되지 않은 표기를 이식 가능하다고 설명하지 말고 필요한 곳에 렌더러별 대상을 유지하세요. 실제로 유지할 원본을 테스트하세요.

제목을 바꾸면 해당 제목으로 들어오는 섹션 링크를 다시 확인하세요. Obsidian의 Automatically update internal links 설정은 파일 이름 변경 시 링크를 업데이트한다고 설명합니다. 이 설명만으로는 제목을 수정할 때마다 그 제목으로 들어오는 링크가 모두 수정된다는 근거가 되지 않습니다. Obsidian 설정 설명을 참조하세요.

여러 앱에서 공유하는 간단한 노트라면 명시적인 Markdown 파일 링크와 고유한 제목 대상, 구조를 바꾼 뒤 각 렌더러에서 간단히 확인하는 방법이 대체로 가장 관리하기 쉽습니다. 예시 규칙으로 시작하고 파일 배치를 유지한 다음, 구체적인 탐색 요구가 있을 때만 복잡한 방식을 더하세요.

출처