DeQrypter로 렌더링된 Heading의 anchor가 먹통되는 문제

[Queue-ri]

Tasks

• anchor 먹통 및 TOC와의 동기화 깨짐 문제 fix (Priority: 📈High)
  • Upgrade to Docusaurus 3 #147 이후 발생
  • 2버전 베타에선 문제 없었으므로 그 사이 내부 anchor 처리 로직에 변경사항이 생긴듯
• value는 같지만 독립된 각 Heading에 대한 id 처리 (Priority: 📉Low)
  • 거의 볼 일 없는 버그지만 docusaurus는 핸들링하므로 fix 해주는 것이 좋음
  • Ex. 2개의 ### 풀이 키워드 Headings

Comment

• Docusaurus에서 h1은 그냥 다 TOC에 안넣음 (최초 h1만 생성 안하는 것 x)
• 참고: https://github.com/facebook/docusaurus/blob/a4c33bfea56b231b302adbf819a45c2de217a01d/packages/docusaurus-theme-classic/src/theme/Heading/index.tsx#L18-L28

[Queue-ri]

Task 1: anchor 먹통 및 TOC와의 동기화 깨짐 문제 fix note

fix 이전 상황

function createHeading(level) {
  return ({ node, ...props }) => {
    if (level === 1 && firstH1Ref.current) { // 첫번째 h1: id 없이 렌더링
      firstH1Ref.current = false;
      return <Heading as="h1" {...props} />;
    }
    else { // h2~h6 or 첫번째가 아닌 h1: id 설정
      firstH1Ref.current = false;
      const index = headingIndexRef.current;
      const headingId = toc[index]?.id || '';
      headingIndexRef.current += 1;
      return <Heading as={`h${level}`} id={headingId} {...props} />;
    }
  };
}

function extractHeadingsFromMarkdown(mdText) {
  const lines = mdText.split('\n');
  const headings = [];
  let isFirstLevel1 = true;

  for (const line of lines) {
    const headingMatch = line.match(/^(#{1,6})\s+(.*)$/);
    if (headingMatch) {
      const level = headingMatch[1].length;
      const text = headingMatch[2].trim();

      if (level === 1 && isFirstLevel1) {
        isFirstLevel1 = false;
        continue; // 첫번째 h1 무시
      }
      isFirstLevel1 = false;

      // id 생성: 영소문자, 공백 -> 하이픈 변환, 한/영/숫자/하이픈 허용
      const id = text
        .toLowerCase()
        .replace(/\s+/g, '-')
        .replace(/[^가-힣a-z0-9\-]/g, '');

      headings.push({ value: text, id, level });
    }
  }

fix 이전 작동 상태

• DeQrypter로 복호화 후 Heading 우측의 hashtag 누르면 먹통
• TOC에서 항목 누르면 스크롤 안됨

🐞 버그 원인

1. createHeading에서 id를 넘겨주긴 했지만 MDX AST의 node.properties.id 발 근본 넘치는 값이 아니라 extractHeadingsFromMarkdown발 무근본 값임
2. Docusaurus의 Heading 컴포넌트는 내부적으로 AST node 객체를 참조해서 anchor link 생성
3. 어 id 없네? -> 퍼벙펑 💥

⭐️ DOM id와 AST node의 id가 일치해야 Docusaurus 로직이 정상 작동함

AST node -> rehype -> props.id -> Heading -> <Link> 생성

정리하자면, 이전의 createHeading은 위 단계에서 props.id 부터 id를 설정해주는 방식이었음.

f12로 보면 heading 태그에 id 있었는데?

AST 속성에 id 없어도 리액트 컴포넌트에 값 찔러넣어서 DOM id로 렌더링 할 수 있음
왜 내부 참조 id는 AST꺼로 쓰면서 DOM id는 props로 받는지 몰?루

🛠️ fix한 방식

1. rehypeExtractHeadings 라는 rehype 플러그인 작성
2. extractHeadingsFromMarkdown의 id 생성 로직 일부를 플러그인으로 옮김
3. 플러그인에서 AST 속성에 생성한 id 넣어줌