cross reference in markdown

[dakeshi]

Markdown에서 cross reference 문법에 대해 참고 글 남깁니다.

참고: https://dakeshi.gitbooks.io/markdown-test/content/

markdown 에서 inter document section 참조는 크게 두 가지 방법으로 가능합니다.

하나는 html 태그를 header에 포함시키는 방법이고 두번째는 html 태그 없이 이용하는 방법입니다.
어떤 방법을 이용하든 header에 reference id를 header 타이틀과 동일하게 부과하는 작업을 해줘야 다른 문서에서 섹션에 대한 참조가 가능합니다.

html을 이용하지 않는 방식의 경우 다시 두 가지로 나눌 수 있습니다.

먼저, 공식적인 markdown 문법을 사용하는 방법입니다. 아래처럼 title과 reference id 로 구성하며 reference id는 title 과 같아야 합니다.

[title](#referenceID)

title이 긴 경우 reference id 자리에는 dash (-) 만 허용되고 스페이스나 언더바(_)는 허용되지 않습니다.

[long title name reference](#long-title-name-reference-id)

Expressions/Passing arguments to ...parameters 챕터의 경우 cross reference를 위의 문법으로 표현할 수 없습니다. 왜냐하면 reference id 에서 ...가 무시되기 때문입니다. 즉, to-...-parameters 라고 표현하면 링크가 제대로 동작하지 않습니다.

이를 해결하는 방법은 gitbook 에서만 지원되는 문법을 사용하는 것입니다.

# title name {#new-reference-id}

이때, new reference id 는 titile name과 같지 않아도 됩니다.

---

현재 golang-spec 에서 사용하고 있는 reference 문법은 다음과 같습니다.

[long title name reference](#long-title-name-reference)
[합성 리터럴](/Expressions/composite_literals.html)

앞서 언급했듯이, Expressions/Passing arguments to ...parameters 챕터의 경우 cross reference를 아래의 문법으로 표현했습니다.

# title name {#new-reference-id}

현재 md 파일들에서 외부 파일 참조할 때 html 로 설정되어 있지만 md 기반으로 하는게 유지관리하는게 향후에는 도움이 될 것 같습니다.(md 파일을 source 파일로 사용한다는 가정하에.)