Astro 7이 Rust 기반의 Sätteri 마크다운 엔진으로 전환하면서 display-math 블록이 일반 코드로 변하고, 헤딩 앵커(heading anchors)가 사라지며, 커스텀 마크다운 옵션이 무시되는 문제가 발생하고 있습니다. 이는 업그레이드 후 사이트에서 수식이 깨져 보이는 사용자들에게 큰 불편을 주고 있습니다.
LaTeX 스타일의 수식, 자동 헤딩 링크 또는 맞춤형 마크다운 플러그인을 사용 중이라면, 이번 업그레이드로 인해 콘텐츠를 읽을 수 없게 되거나 내비게이션을 사용할 수 없게 될 수 있으므로 신속한 해결이 필수적입니다.
업그레이드 후 문제가 발생한 이유
Astro는 이제 Sätteri를 핵심 마크다운 프로세서로 실행합니다. Sätteri는 플러그인이 적용되는 순서를 변경합니다. 즉, 사용자가 설정한 HTML-AST(HAST) 플러그인보다 구문 강조(syntax highlighting)를 먼저 실행합니다. 이러한 변화로 인해 다음과 같은 세 가지 일반적인 패턴이 작동하지 않게 됩니다.
- Display math –
$$ … $$로 구분된 블록은 하이라이터가 먼저 실행되기 때문에 일반 코드로 취급됩니다. - Heading anchors – 슬러그(URL 친화적 ID)를 생성한 다음 해당 헤딩에 자동 링크를 거는 플러그인들이 더 이상 ID를 인식하지 못해 링크가 생성되지 않습니다.
- Custom options – Sätteri 프로세서에 직접 전달한 추가 설정은 무시됩니다. Astro는 미리 정의된 세 가지 필드만 전달하기 때문입니다.
구체적인 해결 방법
1. HTML-AST 대신 markdown-AST(MDAST)에서 수식을 렌더링하세요
Astro의 마크다운 파이프라인에는 두 가지 플러그인 슬롯이 있습니다.
mdastPlugins– HTML로 변환되기 전, 파싱된 마크다운 트리에 실행됩니다.hastPlugins– 변환 후 HTML 트리에 실행됩니다.
하이라이터가 hastPlugins보다 먼저 실행되기 때문에 수식이 코드 블록으로 변해버립니다. 수식 플러그인을 mdastPlugins로 옮기세요.
export default {
markdown: {
mdastPlugins: [
// put remark-math (or your custom math handler) here
],
// leave hastPlugins for things that truly need HTML nodes
}
}
2. 헤딩을 위한 슬러그 및 자동 링크 플러그인 순서 재조정
일반적인 설정에서는 슬러그 생성기를 먼저 설치하고 그 다음에 자동 링크 플러그인을 설치합니다. 하지만 Astro에서는 내장된 heading-ID 플러그인이 사용자의 리스트 이후에 실행되므로, 자동 링크 플러그인이 연결할 대상이 남지 않게 됩니다. 리스트의 맨 앞에 슬러그 플러그인을 배치하고, 그 다음에 자동 링크 플러그인을 배치하세요.
export default {
markdown: {
mdastPlugins: [
satteriSlug(), // must be first
satteriAutolinkHeadings() // runs after slug, sees IDs
]
}
}
이제 각 헤딩이 ID를 부여받으며, 자동 링크 플러그인이 적절한 앵커로 이를 감쌀 수 있게 됩니다.
3. 추가 설정을 Astro markdown 객체의 최상위 레벨에 배치하세요
Astro는 Sätteri 프로세서로 세 가지 특정 필드만 전달합니다. 프로세서 내부에 중첩된 설정(예: shikiConfig 객체)은 누락됩니다. 이러한 추가 설정을 markdown 설정의 최상위 레벨로 옮기세요.
export default {
markdown: {
shikiConfig: { theme: 'nord' }, // top-level, will be respected
// other Astro-accepted fields …
mdastPlugins: [/* … */],
hastPlugins: [/* … */]
}
}
일반적인 remark 플러그인을 위한 빠른 교체 가이드
| 기존 remark 플러그인 | 새로운 Astro 기능 플래그 |
|---|---|
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 |
Astro 설정에서 플러그인 이름을 해당하는 features.* 플래그로 교체하세요.
Sätteri로 플러그인을 이식할 때의 권장 사항
- Factory pattern – 페이지 간의 상태 유출을 방지하기 위해 문서마다 새로운 플러그인 인스턴스를 생성하세요.
- Immutable nodes – 노드를 직접 수정하지 마세요. 프로세서가 변경 사항을 올바르게 추적할 수 있도록 새로운 노드 객체를 반환해야 합니다.
- Insert helpers – 트리를 수동으로 스플라이스(splice)하는 대신, 형제 노드를 추가해야 할 때는
ctx.insertBefore또는ctx.insertAfter를 사용하세요.
이 규칙들을 따르면 프로세서의 안정성을 유지하고 추적하기 어려운 버그를 방지할 수 있습니다.
향후 주의 깊게 살펴볼 점
Astro의 문서는 여전히 이전 플러그인 순서를 기본값으로 나열하고 있어, 새로운 프로젝트에서 의도치 않게 문제가 발생할 수 있습니다. 내부 heading-ID 플러그인의 순서를 재조정하는 내장 수정 사항이 포함될 수 있으므로 향후 Astro 릴리스를 계속 주시하세요. 그전까지는 위 단계들이 Astro 7로 이동한 후 수식 렌더링, 헤딩 앵커 및 커스텀 마크다운 옵션을 복구할 수 있는 유일하고 신뢰할 수 있는 방법입니다.
핵심 요약: Astro 7의 Sätteri 엔진으로 전환하려면 수식 처리를 mdastPlugins로 옮기고, 슬러그 플러그인을 자동 링크보다 앞에 배치하며, 프로세서 객체 외부로 추가 마크다운 설정을 꺼내야 합니다. 이 세 가지 조정을 마치면 사이트의 수식, 내비게이션 링크 및 커스텀 마크다운 기능이 이전처럼 정상적으로 작동합니다.