ref shortcode

ref는 특정 페이지를 가리키는 permalink를 만들어 주는 shortcode입니다.
문서 내부 링크를 직접 하드코딩하지 않고, 페이지 참조를 기준으로 링크를 만들고 싶을 때 유용합니다.

공식 문서는 Markdown에서 이 shortcode가 이제는 obsolete라고 설명하면서도, 기존 shortcode 문법 자체와 경고 처리, 경로 해석 방식은 여전히 문서화합니다. 또한 path, lang, outputFormat을 사용할 수 있고, 경로는 현재 페이지 기준 또는 사이트 기준으로 해석됩니다. citeturn660511view0

렌더링 결과

내부 문서로 가는 링크

원형

[내부 문서로 가는 링크]({{% ref "/blog/lab/91-hugo-shortcode/ref-target" %}})

해석 포인트

  • ref는 링크 텍스트를 감싸는 Markdown과 함께 사용하는 것이 기본입니다.
  • 경로는 절대 경로처럼 쓰는 편이 읽기 쉽습니다.
  • 참조 대상이 없으면 빌드 에러가 날 수 있으므로, 문서 구조를 바꾸기 전에 대상 경로를 함께 확인해야 합니다.
  • 다양한 언어와 출력 형식을 다루는 사이트에서는 lang와 outputFormat이 중요해집니다.

실무 팁

  • 오래된 문서나 다국어 사이트에서 특히 유용합니다.
  • 새 Markdown 링크를 설계할 때는 render hook 전략과 함께 검토하는 것이 좋습니다.