Astro 7 యొక్క Rust-ఆధారిత Sätteri markdown engine కి మారడం వల్ల display-math బ్లాక్లు సాధారణ కోడ్గా మారుతున్నాయి, heading anchors తొలగించబడుతున్నాయి మరియు custom markdown options వదిలివేయబడుతున్నాయి – ఇది అప్గ్రేడ్ చేసిన వారికి మరియు వారి సైట్లో విచ్ఛిన్నమైన సమీకరణాలను (equations) చూస్తున్న వారికి ఒక పెద్ద సమస్య.
మీరు LaTeX-style math, automatic heading links లేదా bespoke markdown plugins పై ఆధారపడి ఉంటే, ఈ అప్గ్రేడ్ మీ కంటెంట్ను చదవలేనంతగా మరియు మీ నావిగేషన్ను ఉపయోగించలేనంతగా మార్చేస్తుంది, కాబట్టి దీనిని త్వరగా పరిష్కరించడం చాలా ముఖ్యం.
అప్గ్రేడ్ వల్ల ఎందుకు సమస్యలు వచ్చాయి
Astro ఇప్పుడు Sätteriని దాని కోర్ Markdown processor గా ఉపయోగిస్తోంది. Sätteri ప్లగిన్లు అప్లై అయ్యే క్రమాన్ని మారుస్తుంది: మీరు కాన్ఫిగర్ చేసిన HTML-AST (HAST) ప్లగిన్ల కంటే ముందే ఇది syntax highlighting ని రన్ చేస్తుంది. ఆ మార్పు వల్ల మూడు సాధారణ పద్ధతులు పనిచేయవు:
- Display math –
$$ … $$తో delimited చేయబడిన బ్లాక్లు సాధారణ కోడ్గా పరిగణించబడతాయి ఎందుకంటే highlighter మొదట రన్ అవుతుంది. - Heading anchors – slugs (URL-friendly IDs) ని సృష్టించి, ఆ తర్వాత ఆ హెడ్డింగ్లకు ఆటోలింక్ చేసే ప్లగిన్లు ఇకపై IDలను చూడలేవు, కాబట్టి లింక్లు అసలు సృష్టించబడవు.
- Custom options – మీరు నేరుగా Sätteri processor లోకి పంపిన ఏవైనా అదనపు సెట్టింగ్లు విస్మరించబడతాయి; Astro కేవలం మూడు ముందుగా నిర్వచించిన (predefined) ఫీల్డ్లను మాత్రమే ఫార్వార్డ్ చేస్తుంది.
ఖచ్చితమైన పరిష్కారాలు
1. HTML-AST కి బదులుగా markdown-AST (MDAST) పై math ని render చేయండి
Astro యొక్క markdown pipeline లో రెండు plugin slots ఉన్నాయి:
mdastPlugins– ఇది HTML గా మారకముందు parsed markdown tree పై రన్ అవుతుంది.hastPlugins– ఇది కన్వర్షన్ తర్వాత HTML tree పై రన్ అవుతుంది.
Highlighter hastPlugins కంటే ముందే రన్ అవుతుంది కాబట్టి, math ఒక code block గా మారిపోతుంది. మీ math plugin ని mdastPlugins కి మార్చండి.
export default {
markdown: {
mdastPlugins: [
// put remark-math (or your custom math handler) here
],
// leave hastPlugins for things that truly need HTML nodes
}
}
2. హెడ్డింగ్ల కోసం slug మరియు autolink ప్లగిన్ల క్రమాన్ని మార్చండి
Standard setups లో ఒక slug generator తర్వాత autolink plugin ఇన్స్టాల్ చేయబడుతుంది. Astro లో, ఇన్బిల్ట్ heading-ID plugin మీ లిస్ట్ తర్వాత రన్ అవుతుంది, దీనివల్ల autolink plugin కి అటాచ్ చేయడానికి ఏమీ ఉండదు. లిస్ట్లో slug plugin ని మొదట ఉంచండి, ఆ తర్వాత autolink plugin ని ఉంచండి.
export default {
markdown: {
mdastPlugins: [
satteriSlug(), // must be first
satteriAutolinkHeadings() // runs after slug, sees IDs
]
}
}
ఇప్పుడు ప్రతి హెడ్డింగ్కు ఒక ID లభిస్తుంది మరియు autolink plugin దానిని తగిన anchor తో చుట్టగలదు (wrap చేయగలదు).
3. అదనపు కాన్ఫిగరేషన్ను Astro markdown object యొక్క top level లో ఉంచండి
Astro కేవలం మూడు నిర్దిష్ట ఫీల్డ్లను మాత్రమే Sätteri processor కి ఫార్వార్డ్ చేస్తుంది. మీరు processor లోపల (ఉదాహరణకు ఒక shikiConfig object) ఏది ఉంచినా అది తొలగించబడుతుంది. ఆ అదనపు సెట్టింగ్లను markdown కాన్ఫిగరేషన్ యొక్క top level కి మార్చండి.
export default {
markdown: {
shikiConfig: { theme: 'nord' }, // top-level, will be respected
// other Astro-accepted fields …
mdastPlugins: [/* … */],
hastPlugins: [/* … */]
}
}
సాధారణ remark ప్లగిన్ల కోసం త్వరిత మార్పిడి గైడ్
| పాత remark plugin | కొత్త Astro feature flag |
|---|---|
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 config లో ప్లగిన్ పేరును దానికి సంబంధించిన features.* ఫ్లాగ్తో మార్చండి.
Sätteri కి ప్లగిన్లను పోర్ట్ చేసేటప్పుడు పాటించాల్సిన ఉత్తమ పద్ధతులు
- Factory pattern – పేజీల మధ్య స్టేట్ లీక్ అవ్వకుండా ఉండటానికి ప్రతి డాక్యుమెంట్ కోసం కొత్త ప్లగిన్ ఇన్స్టెన్స్ను సృష్టించండి.
- Immutable nodes – ఒక నోడ్ను నేరుగా మార్చకండి (mutate); ఒక కొత్త నోడ్ ఆబ్జెక్ట్ను రిటర్న్ చేయండి, తద్వారా processor మార్పులను సరిగ్గా ట్రాక్ చేయగలదు.
- Insert helpers – మీరు sibling nodesలను జోడించాలనుకున్నప్పుడు, ట్రీని మాన్యువల్గా splice చేసే బదులు
ctx.insertBeforeలేదాctx.insertAfterఉపయోగించండి.
ఈ నియమాలను పాటించడం వల్ల processor స్థిరంగా ఉంటుంది మరియు కనుగొనడం కష్టమైన బగ్లను నివారిస్తుంది.
తదుపరి ఏం గమనించాలి
Astro డాక్యుమెంటేషన్ ఇంకా పాత ప్లగిన్ ఆర్డర్నే డిఫాల్ట్గా చూపుతోంది, కాబట్టి కొత్త ప్రాజెక్ట్లు తెలియకుండానే ఈ సమస్యను ఎదుర్కోవచ్చు. ఇంటర్నల్ heading-ID ప్లగిన్ క్రమాన్ని మార్చే సాధ్యమయ్యే ఇన్బిల్ట్ ఫిక్స్ కోసం రాబోయే Astro రిలీజ్లను గమనిస్తూ ఉండండి. ప్రస్తుతానికి, Astro 7 కి మారిన తర్వాత math rendering, heading anchors మరియు custom markdown optionsలను పునరుద్ధరించడానికి పైన పేర్కొన్న దశలే ఏకైక నమ్మదగిన మార్గాలు.
ముఖ్య అంశం: Astro 7 యొక్క Sätteri engine కి మారేటప్పుడు math handling ని mdastPlugins కి మార్చడం, autolinks కంటే ముందు slug plugin ని ఉంచడం, మరియు అదనపు markdown సెట్టింగ్లను processor object నుండి బయటకు తీసి top level లో ఉంచడం అవసరం; ఈ మూడు సర్దుబాట్లు చేసిన తర్వాత, మీ సైట్ యొక్క సమీకరణాలు, నావిగేషన్ లింక్లు మరియు కస్టమ్ markdown ఫీచర్లు మునుపటిలాగే పనిచేస్తాయి.