Astro 7의 Rust 기반 Sätteri 마크다운 엔진 전환은 수학 공식, 헤딩 앵커, 커스텀 설정에 의존하는 사이트들에게 매끄러운 업그레이드가 아닌 세 배의 악몽이 되었습니다. 인라인 수식은 여전히 작동하지만, 디스플레이 수식(display-math) 블록은 일반 텍스트 코드 스니펫으로 나타나고, 헤딩 ID는 사라지며, Astro 설정에 추가한 모든 추가 옵션은 조용히 무시됩니다. 이전 Astro 버전에서 마이그레이션하는 개발자들은 이제 플러그인을 다시 작성하거나 페이지가 깨지는 위험을 감수해야 합니다.

왜 이 변화가 중요한가

새로운 엔진은 사용자 제공 플러그인보다 먼저 내장된 구문 강조기(syntax highlighter)를 실행하며, 오직 세 가지 최상위 설정 필드만 허용합니다. 이러한 선택은 대부분의 Astro 프로젝트가 기능을 추가하는 방식과 충돌합니다. 즉, 강조 처리 이후에 실행되기를 기대하는 remark (MDAST) 및 rehype (HAST) 플러그인을 사용하거나, 하위 마크다운 파서로 전달되는 허용적인 설정 객체를 사용하는 방식과 충돌하는 것입니다.

그 여파는 LaTeX 스타일의 수학 공식과 일반 콘텐츠가 섞여 있는 모든 페이지에서 나타납니다. 인라인 수학 공식($a+b$)은 잘 렌더링되지만, 디스플레이 블록($$a+b$$)은 <pre> 태그로 감싸져 포맷팅된 수식 대신 가공되지 않은 마크업을 보여줍니다. 목차 링크나 딥링크를 지원하는 헤딩 앵커는 사라지는데, 이는 ID 생성 플러그인이 내장 ID 핸들러보다 먼저 실행되어 autolink 플러그인이 달라붙을 대상이 남지 않기 때문입니다. shikiConfig 객체로 Shiki 구문 강조기를 미세 조정하려 했던 개발자들은 해당 설정이 흔적도 없이 사라진 것을 발견하게 됩니다.

기술적 해결 방법

1. 강조 처리 전 수학 공식 렌더링

근본 원인은 작업 순서에 있습니다. Sätteri의 강조기가 텍스트를 먼저 점유하여 수학 블록을 일반 코드로 분류해 버립니다. 수학 공식을 되찾으려면 처리를 MDAST 레이어(HTML이 되기 전 마크다운을 나타내는 추상 구문 트리)로 옮겨야 합니다. 모든 HAST 레벨 수학 플러그인을 MDAST 대응 버전으로 교체하고 강조기 단계 이전에 실행하십시오. 실제로 remark-math 플러그인을 마크다운 파싱 단계에 연결되는 버전으로 교체한 다음, 이미 변환된 수학 노드에 대해 강조기가 작동하도록 하십시오.

2. 헤딩-ID 플러그인 순서 재조정

헤딩 ID는 이제 사용자 플러그인 이후에 실행되는 내장 플러그인에 의해 생성됩니다. 커스텀 ID 또는 slug 생성기를 플러그인 목록의 맨 위로 이동하여 가장 먼저 실행되도록 하십시오. 앵커 링크를 복구하는 전형적인 순서는 다음과 같습니다:

  1. slug/ID 플러그인
  2. autolink 플러그인
  3. 기타 remark 플러그인

ID가 초기에 배치되면 autolink 플러그인이 예상되는 <a> 요소를 부착할 수 있고, 목차는 올바른 섹션을 가리키게 됩니다.

3. Sätteri의 엄격한 설정 스키마 준수

Sätteri는 Astro 마크다운 설정에서 오직 세 가지 필드만 인식합니다. shikiConfig와 같은 다른 모든 것은 조용히 누락됩니다. 커스텀 테마나 강조기 수정을 유지하려면 해당 설정을 Astro 설정 계층 구조의 적절한 레벨로 이동시키십시오.

빠른 교체 가이드

기존 Astro 마크다운 스택을 포팅하는 경우, 오래된 remark 플러그인을 Sätteri가 이해하는 새로운 기능 플래그(feature flags)로 교체하십시오:

  • remark-gfm → features.gfm
  • remark-frontmatter → features.frontmatter
  • remark-math → features.math
  • remark-directive → features.directive
  • remark-smartypants → features.smartPunctuation
  • remark-wiki-link → features.wikilinks

이 플래그들은 별도의 플러그인 로드 없이도 동일한 기능을 활성화합니다.

Sätteri에서 플러그인을 안정적으로 유지하기 위한 규칙

  • 단 한 번의 패스만 허용 – 플러그인은 트리를 한 번만 확인합니다. 파이프라인의 나중에 생성된 노드를 다시 방문할 수 없습니다.
  • 상태 생성을 위한 팩토리 – 페이지 간 데이터 누출을 방지하기 위해 각 페이지에 대해 새로운 상태 객체를 생성하십시오.
  • 불변 노드 – 변경이 필요한 경우 새 노드를 반환하십시오. 기존 노드를 직접 수정(mutating)하면 후속 처리 단계가 깨질 수 있습니다.
  • 루트 프래그먼트 금지 – 최상위 프래그먼트 노드를 생성하는 대신 제공된 삽입 헬퍼(insertion helpers)를 통해 형제 노드를 삽입하십시오.

기존 플러그인을 조정할 때는 README의 예시 출력에 의존하지 마십시오. 원래 플러그인의 HTML을 렌더링하고, 해당 마크업을 캡처하여 Sätteri 호환 버전을 위한 참조점으로 사용하십시오.

시사점

Astro 7의 Sätteri 엔진은 속도를 향상시키지만, 마크다운 처리 체인의 순서를 재조정해야 합니다. MDAST 레벨에서 수식을 렌더링하고, heading-ID 플러그인을 맨 앞에 배치하며, 설정을 허용된 세 가지 필드로 제한하십시오. feature-flag 매핑을 따르고 single-pass 및 immutable-node 규칙을 준수하면, 사이트에서 의존하고 있는 수식, 앵커, 커스텀 테마를 복구할 수 있습니다. 초기에는 노력이 필요하지만, 그 대가로 더욱 예측 가능하고 빠른 마크다운 파이프라인을 얻게 될 것입니다.