Astro 7, Rust-ఆధారిత Sätteri markdown engineకి మారడం వల్ల, math, heading anchors మరియు custom configuration పై ఆధారపడే సైట్లకు ఒక సులభమైన అప్గ్రేడ్ మూడుంతల సమస్యగా మారింది. Inline equations ఇంకా పనిచేస్తున్నాయి, కానీ display-math blocks కేవలం plain-text code snippets లాగా కనిపిస్తున్నాయి, heading IDs మాయమవుతున్నాయి, మరియు మీరు Astro configలో ఇచ్చే అదనపు ఆప్షన్లు ఏవీ పట్టించుకోకుండానే వదిలివేయబడతాయి. పాత Astro releases నుండి మైగ్రేట్ అయ్యే డెవలపర్లు ఇప్పుడు ప్లగిన్లను తిరిగి రాయాల్సి ఉంటుంది, లేకపోతే పేజీలు పాడైపోయే ప్రమాదం ఉంది.
ఈ మార్పు ఎందుకు ముఖ్యం
కొత్త engine, వినియోగదారులు అందించే ప్లగిన్ల కంటే ముందే ఒక built-in syntax highlighterని రన్ చేస్తుంది మరియు కేవలం మూడు top-level configuration fieldsలను మాత్రమే అంగీకరిస్తుంది. ఈ ఎంపికలు చాలా Astro ప్రాజెక్ట్లు ఫీచర్లను జోడించే విధానంతో విభేదిస్తున్నాయి: అంటే, highlighting తర్వాత రన్ అవ్వాలని ఆశించే remark (MDAST) మరియు rehype (HAST) ప్లగిన్ల ద్వారా మరియు underlying markdown parserకి పాస్ అయ్యే ఒక permissive config object ద్వారా ఫీచర్లు జోడించడం.
LaTeX-style math మరియు సాధారణ కంటెంట్ను కలిపి ఉండే ఏ పేజీలోనైనా దీని ప్రభావం కనిపిస్తుంది. Inline math ($a+b$) సరిగ్గా కనిపిస్తుంది, కానీ ఒక display block ($$a+b$$) <pre> ట్యాగ్లో చుట్టబడి, ఫార్మాట్ చేసిన ఈక్వేషన్ బదులుగా raw markupను చూపిస్తుంది. Table-of-contents లింక్లు లేదా deep-linking కోసం ఉపయోగించే heading anchors మాయమవుతున్నాయి, ఎందుకంటే ID-generation plugin, built-in ID handler కంటే ముందే రన్ అవుతుంది, దీనివల్ల autolink plugin దేనినైనా అనుసంధానించడానికి ఏమీ మిగలదు. shikiConfig ఆబ్జెక్ట్తో Shiki syntax highlighterని fine-tune చేయడానికి ప్రయత్నించిన డెవలపర్లు, ఆ సెట్టింగ్ ఎక్కడికి వెళ్లిపోయిందో తెలియకుండానే మాయమవ్వడాన్ని గమనించారు.
సాంకేతిక పరిష్కారాలు
1. highlighting కంటే ముందే mathను render చేయండి
దీనికి ప్రధాన కారణం ఆపరేషన్ల క్రమం (order of operations): Sätteri యొక్క highlighter మొదట టెక్స్ట్ను తీసుకుంటుంది, తద్వారా math blockను plain codeగా వర్గీకరిస్తుంది. Mathను తిరిగి పొందడానికి, ప్రాసెసింగ్ను MDAST లేయర్కు (markdown HTMLగా మారకముందు దానిని సూచించే abstract syntax tree) మార్చండి. HAST-level math ప్లగిన్ల స్థానంలో వాటి MDAST సమానమైన వాటిని ఉపయోగించి, highlighter స్టెప్ ముందు వాటిని రన్ చేయండి. ఆచరణలో, remark-math ప్లగిన్లను markdown parsing స్టేజ్లో హుక్ అయ్యే వెర్షన్తో మార్చండి, ఆపై ఇప్పటికే కన్వర్ట్ అయిన math nodes పై highlighter పనిచేయనివ్వండి.
2. heading-ID ప్లగిన్ల క్రమాన్ని మార్చండి
Heading IDs ఒక built-in ప్లగిన్ ద్వారా జనరేట్ చేయబడతాయి, ఇది ఇప్పుడు యూజర్ ప్లగిన్ల తర్వాత రన్ అవుతుంది. కస్టమ్ ID లేదా slug జనరేటర్లను ప్లగిన్ లిస్ట్ పైన ఉంచండి, తద్వారా అవి మొదట రన్ అవుతాయి. Anchor లింక్లను పునరుద్ధరించే సాధారణ క్రమం ఇలా ఉంటుంది:
- slug/ID plugin
- autolink plugin
- ఇతర remark ప్లగిన్లు
IDs ముందుగానే అందుబాటులో ఉండటం వల్ల, autolink plugin ఆశించిన <a> ఎలిమెంట్లను జోడించగలదు మరియు table-of-contents సరైన సెక్షన్లను సూచిస్తుంది.
3. Sätteri యొక్క కఠినమైన config schemaను పాటించండి
Astro markdown configurationలో Sätteri కేవలం మూడు ఫీల్డ్లను మాత్రమే గుర్తిస్తుంది. shikiConfig వంటి ఇతర ఏవైనా సెట్టింగ్లు నిశ్శబ్దంగా వదిలివేయబడతాయి. కస్టమ్ థీమ్లు లేదా highlighter మార్పులను కొనసాగించడానికి, ఆ సెట్టింగ్లను Astro config hierarchyలో సరైన స్థాయికి మార్చండి.
త్వరిత మార్పిడి గైడ్
మీరు పాత Astro markdown స్టాక్ను పోర్ట్ చేస్తున్నట్లయితే, పాత remark ప్లగిన్లను Sätteri అర్థం చేసుకునే కొత్త feature flagsతో మార్చండి:
remark-gfm→features.gfmremark-frontmatter→features.frontmatterremark-math→features.mathremark-directive→features.directiveremark-smartypants→features.smartPunctuationremark-wiki-link→features.wikilinks
ఈ ఫ్లాగ్లు ప్రత్యేక ప్లగిన్ లోడ్ అవసరం లేకుండానే అదే సామర్థ్యాలను అందిస్తాయి.
Sätteriతో ప్లగిన్లు సజావుగా పనిచేయడానికి నియమాలు
- Single pass only – ప్లగిన్లు ట్రీని ఒకేసారి చూస్తాయి; పైప్లైన్లో తర్వాత సృష్టించబడిన నోడ్లను అవి మళ్ళీ చూడలేవు.
- Factory for state – పేజీల మధ్య డేటా లీకేజీని నివారించడానికి ప్రతి పేజీ కోసం ఒక కొత్త state ఆబ్జెక్ట్ను నిర్మించండి.
- Immutable nodes – మార్పు కావాలనుకున్నప్పుడు కొత్త నోడ్ను రిటర్న్ చేయండి; ఇప్పటికే ఉన్న నోడ్ను మ్యుటేట్ (mutate) చేయడం వల్ల తదుపరి ప్రాసెసింగ్ దశలు దెబ్బతినవచ్చు.
- No root fragments – టాప్-లెవల్ ఫ్రాగ్మెంట్ నోడ్ను సృష్టించడానికి బదులుగా, అందించబడిన insertion helpers ద్వారా sibling నోడ్లను ఇన్సర్ట్ చేయండి.
మీరు ఇప్పటికే ఉన్న ప్లగిన్ను అడాప్ట్ చేస్తున్నప్పుడు, READMEలోని ఉదాహరణ అవుట్పుట్పై ఆధారపడకండి. అసలు ప్లగిన్ యొక్క HTMLని render చేసి, ఆ markupను క్యాప్చర్ చేయండి, మరియు దానిని మీ Sätteri-compatible వెర్షన్కు రిఫరెన్స్ పాయింట్గా ఉపయోగించండి.
ముగింపు
Astro 7 యొక్క Sätteri engine వేగాన్ని తీసుకువస్తుంది, కానీ markdown ప్రాసెసింగ్ చైన్ను తిరిగి క్రమబద్ధీకరించవలసి ఉంటుంది: MDAST స్థాయిలో mathను రెండర్ చేయండి, heading-ID ప్లగిన్లను ముందు వరుసలో ఉంచండి, మరియు కాన్ఫిగరేషన్ను మూడు ఆమోదించబడిన ఫీల్డ్లకు మాత్రమే పరిమితం చేయండి. feature-flag మ్యాపింగ్ను అనుసరించండి, single-pass మరియు immutable-node నియమాలను పాటించండి, అప్పుడు మీ సైట్కు అవసరమైన math, anchors మరియు custom themingలను మీరు పునరుద్ధరించగలరు. ఈ శ్రమ ముందుగానే చేయాల్సి ఉంటుంది; కానీ దీని వల్ల ఫలితంగా మరింత ఊహించదగిన మరియు వేగవంతమైన markdown pipeline లభిస్తుంది.