티스토리 블로그 본문에 앵커(Anchor) 링크 추가하기

앵커 링크(Anchor Link)는 페이지 안에서 특정 위치로 바로 이동할 수 있게 해주는 기능이다. MDN, GitHub, 기술 블로그 등 문서 중심의 웹사이트는 제목 태그(heading)에 앵커 링크를 적용하여 사용자가 원하는 섹션을 빠르게 탐색할 수 있도록 지원한다.

 

앵커 링크를 클릭해서 특정 섹션으로 이동할 때마다 주소창 URL도 https://...#섹션으로 변경된다. #섹션은 해시(hash)라고 부르는데, 해시가 포함된 주소로 접속하면 브라우저가 해당 위치까지 자동으로 스크롤해 주는 편리한 기능이다.

 

아쉽게도 티스토리는 자체적인 앵커 링크를 제공하지 않기 때문에 자바스크립트로 직접 구현해야 한다. 아래에서 소개할 앵커 링크 추가 스크립트는 개인적으로 사용하려고 만들었지만, jsDelivr 같은 CDN으로 배포하면 다른 스킨 사용자도 쉽게 활용할 수 있지 않을까 싶어서 플러그인 형태로 정리해 봤다.

 

 

적용 방법

---

티스토리 스킨 편집 > HTML 편집 화면에서 CSS, JS 코드를 붙여넣는다. CSS 파일은 스타일을 담당하므로 </head> 태그 바로 위에 삽입하는 것을 권장한다.

<!-- Heading-anchor CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/romantech/tistory-plugins@latest/dist/heading-anchor/index.min.css">

 

JS(자바스크립트) 파일은 페이지 로딩을 방해하지 않도록 </body> 태그 바로 위에 삽입한다.

<!-- Heading-anchor JS -->
<script defer src="https://cdn.jsdelivr.net/gh/romantech/tistory-plugins@latest/dist/heading-anchor/index.min.js"></script>

 

이 스크립트는 기본적으로 H2~H4 제목 태그를 대상으로 앵커 링크를 생성한다. H1 태그는 포스팅 상단 제목에 사용하므로 제외했다. 본문 제목에 마우스 커서를 올리면 우측에 # 기호가 나타나고, 제목 혹은 # 기호를 클릭하면 해당 위치로 부드럽게 스크롤된다. 전반적인 구조와 동작 방식은 MDN 앵커 링크와 유사하다.

 

 

작동 방식

---

작동 방식은 크게 보면 그리 복잡하지 않다. 먼저 본문에 포함된 모든 제목을 찾은 뒤 고유한 해시를 생성한다. 생성된 앵커 링크(제목)를 클릭하거나 해시가 포함된 주소로 접속했을 땐 해당 위치로 자연스럽게 이동하도록 처리한다(scroll-behavior: smooth 적용).

1. 본문 영역에서 H2~H4 제목 태그를 탐색한다.
2. 제목 텍스트를 기준으로 id를 생성하고, 중복 제목은 번호를 붙여 해시가 겹치지 않도록 한다.
3. 제목 전체를 앵커 링크로 감싸고, 마우스를 올렸을 때 표시할 # 마커를 추가한다.
4. 제목을 클릭하면 URL에 #섹션 해시를 반영하고, 해당 위치로 부드럽게 스크롤한다.
5. 해시가 포함된 주소로 처음 접속했을 때도 같은 방식으로 동작한다.

 

🔍 제목 텍스트 전체 영역에 링크를 적용했다면 앵커 링크가 생성되지 않는다.

 

 

설정 옵션

---

스킨마다 헤더 높이와 본문 구조가 조금씩 다를 수 있으므로, 아래 옵션을 통해 동작 범위를 조정할 수 있다.

 

headingAnchor.levels

• 설명: 앵커 링크를 적용할 제목 태그 범위.
• 기본값: [2, 3, 4] (H2~H4)

 

headingAnchor.headerOffset

• 설명: 스크롤 위치 보정값.
• 상단 고정 헤더가 본문 제목을 가리지 않도록 여백을 추가할 수 있다.
• 기본값: 84 (화면 상단부터 제목까지의 여백)

 

articleSelectors

• 설명: 본문 영역 셀렉터 지정. 
• 플러그인이 본문 영역을 찾지 못할 경우 직접 지정할 수 있다.
• 기본값: ["#article", ".article-view", ".post-content", ...]

 

headerOffset은 실제 헤더 높이와 똑같이 맞추기보다, 상단 여백을 고려해 더 크게 설정하는 게 좋다. 예를 들어 헤더 높이가 64px이라면 16px 정도 여유를 더해 80 정도로 설정한 뒤, 스킨에 맞게 조금씩 조정하는 방식을 추천한다. 

<script>
window.RPPlugins = {
  articleSelectors: [".my-custom-article"], // 본문 영역 셀렉터 직접 지정
  headingAnchor: {
    levels: [2, 3, 4, 5], // H2~H5 제목에 적용
    headerOffset: 80 // 헤더 높이 64px + 여유값 16px
  }
};
</script>
<script defer src="https://cdn.jsdelivr.net/gh/romantech/tistory-plugins@latest/dist/heading-anchor/index.min.js"></script>

 

⚠️ 설정 옵션 코드는 플러그인 스크립트보다 상단에 위치해야 정상적으로 적용된다.

 

 

기타 플러그인

---

앵커 링크 외에도 인라인 코드, LaTeX(KaTeX) 렌더링 등 스크립트 한 줄만 추가하면 바로 적용할 수 있는 다른 플러그인도 함께 만들었다. 전체 코드와 더 자세한 설명은 GitHub 저장소를 참고하자.

 

플러그인	설명
inline-code	벡틱(`)으로 감싼 인라인 텍스트를 <code>로 변환
katex	텍스트 내 수학 수식을 KaTeX로 렌더링
copy-code	코드 블록 우측 상단에 복사 버튼 추가
focus-guard	사이드바 토글 과정에서 발생하는 aria-hidden 포커스 경고 완화