Astro Markdown 코드블록에 파일명과 복사 버튼을 붙이면 글이 읽기 쉬워진다

기술 블로그에서 코드블록은 본문만큼 중요하다.

하지만 그냥 코드만 던져두면 독자는 금방 헷갈린다.

이 코드는 어느 파일에 넣는 거지?
전체 교체인가, 일부 수정인가?
복사해서 바로 써도 되나?

그래서 Astro 블로그에서는 코드블록에 파일명과 복사 버튼을 붙이는 것만으로도 읽기 경험이 꽤 좋아진다.

Astro Markdown 코드블록 복사 버튼 삽화

파일명이 있으면 맥락이 보인다

예를 들어 같은 CSS 코드라도 위치가 중요하다.

@utility app-layout {
  @apply mx-auto w-full max-w-6xl px-4 sm:px-6;
}

이 코드만 보면 어디에 넣어야 하는지 알기 어렵다.

하지만 파일명이 붙으면 훨씬 분명해진다.

@utility app-layout {
  @apply mx-auto w-full max-w-6xl px-4 sm:px-6;
}

기술 글은 코드 자체보다 코드의 위치가 더 중요할 때가 많다.

독자는 코드블록을 직접 드래그해서 복사할 수도 있다.

하지만 코드가 길거나 모바일에서 읽을 때는 불편하다.

복사 버튼이 있으면 이런 작은 마찰이 줄어든다.

읽기
→ 복사
→ 붙여넣기
→ 실행

튜토리얼형 글에서는 이 흐름이 중요하다.

Markdown이 HTML로 렌더링된 뒤,
pre 요소를 찾아 복사 버튼을 붙이는 방식이 가장 단순하다.

흐름은 이렇다.

page load
→ pre 요소 찾기
→ wrapper 생성
→ copy button 추가
→ clipboard API 연결

Astro의 페이지 전환을 쓰고 있다면 astro:page-load 이벤트도 같이 고려해야 한다.

document.addEventListener("astro:page-load", attachCopyButtons);

페이지 전환 후에도 새 글의 코드블록에 버튼이 붙어야 하기 때문이다.

페이지 전환이나 재실행이 들어가면 같은 코드블록에 버튼이 여러 개 붙을 수 있다.

그래서 wrapper가 이미 있는지 확인하는 게 좋다.

if (codeBlock.closest(".code-wrapper")) return;

이 한 줄이 없으면 버튼이 중복으로 생기고,
레이아웃도 어색해진다.

코드블록 파일명은 markdown fence의 meta 정보를 활용할 수 있다.

예를 들어:

```ts filename="src/content.config.ts"
export const collections = { blog };
```

이 정보를 rehype나 shiki transformer에서 읽어
렌더링 결과에 표시하면 된다.

장점은 본문 작성자가 자연스럽게 파일명을 남길 수 있다는 점이다.

복사 버튼은 작아 보여도 레이아웃에 영향을 준다.

특히 파일명 영역과 복사 버튼이 겹치면 지저분하다.

체크할 것:

버튼이 코드 내용을 가리면 기능은 있어도 사용성은 나빠진다.

대부분의 브라우저에서는 navigator.clipboard.writeText()가 잘 동작한다.

하지만 보안 컨텍스트나 권한에 따라 실패할 수 있다.

블로그에서는 실패를 크게 터뜨리기보다,
버튼 상태만 유지하는 정도로도 충분하다.

try {
  await navigator.clipboard.writeText(text);
  button.innerText = "Copied";
} catch {
  button.innerText = "Copy";
}

Astro Markdown 코드블록 개선은 화려한 기능이 아니다.

하지만 기술 블로그에서는 효과가 크다.

작은 편의 기능이지만 글의 완성도를 꽤 올려준다.

Astro 기술 블로그의 코드블록에는 파일명과 복사 버튼을 붙여야 독자가 코드 위치와 사용 흐름을 더 빨리 이해한다.