Astro 7 એ Rust-આધારિત Sätteri markdown engine પર સ્વિચ કરવાથી, જે એક સરળ અપગ્રેડ હોવું જોઈતું હતું, તેને ગણિત (math), હેડિંગ એન્કર્સ (heading anchors) અને કસ્ટમ કોન્ફિગરેશન પર આધારિત સાઇટ્સ માટે ત્રણગણી મુશ્કેલીમાં ફેરવી દીધું છે. ઇનલાઇન ઇક્વેશન હજુ પણ કામ કરે છે, પરંતુ ડિસ્પ્લે-મેથ (display-math) બ્લોક્સ સાદા ટેક્સ્ટ કોડ સ્નિપેટ્સ તરીકે દેખાય છે, હેડિંગ ID ગાયબ થઈ જાય છે, અને તમે Astro કોન્ફિગમાં ઉમેરતા કોઈપણ વધારાના વિકલ્પોને શાંતિથી અવગણવામાં આવે છે. જે ડેવલપર્સ અગાઉના Astro રિલીઝમાંથી માઇગ્રેટ કરે છે, તેમણે હવે પ્લગિન્સ ફરીથી લખવા પડશે અથવા બ્રોકન પેજનું જોખમ લેવું પડશે.

આ ફેરફાર શા માટે મહત્વપૂર્ણ છે

નવું એન્જિન કોઈપણ યુઝર-સપ્લાય કરેલા પ્લગિન્સ પહેલા ઇન-બિલ્ટ સિન્ટેક્સ હાઇલાઇટર ચલાવે છે અને માત્ર ત્રણ ટોપ-લેવલ કોન્ફિગરેશન ફીલ્ડ્સ જ સ્વીકારે છે. આ પસંદગીઓ મોટાભાગના Astro પ્રોજેક્ટ્સમાં ફીચર્સ ઉમેરવાની રીત સાથે ટકરાય છે: remark (MDAST) અને rehype (HAST) પ્લગિન્સ દ્વારા જે હાઇલાઇટિંગ પછી ચાલવાની અપેક્ષા રાખે છે, અને એક પરમિસિવ કોન્ફિગ ઓબ્જેક્ટ દ્વારા જે અન્ડરલાઇંગ માર્કડાઉન પાર્સર સુધી પહોંચે છે.

આ અસરો એવા કોઈપણ પેજ પર જોવા મળે છે જે LaTeX-સ્ટાઇલ મેથને રેગ્યુલર કન્ટેન્ટ સાથે મિક્સ કરે છે. ઇનલાઇન મેથ ($a+b$) બરાબર રેન્ડર થાય છે, પરંતુ ડિસ્પ્લે બ્લોક ($$a+b$$) ને <pre> ટેગમાં લપેટવામાં આવે છે, જે ફોર્મેટ કરેલા ઇક્વેશનને બદલે રો (raw) માર્કઅપ બતાવે છે. ટેબલ-ઓફ-કન્ટેન્ટ લિંક્સ અથવા ડીપ-લિંકિંગ માટે ઉપયોગી હેડિંગ એન્કર્સ ગાયબ થઈ જાય છે કારણ કે 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 સમજે છે:

  • 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 સાથે પ્લગિન્સને સુમેળમાં રાખવા માટેના નિયમો

  • માત્ર સિંગલ પાસ (Single pass only) – પ્લગિન્સ ટ્રીને એક જ વાર જુએ છે; તેઓ પાઇપલાઇનમાં પછીથી બનાવેલા નોડ્સ પર ફરીથી જઈ શકતા નથી.
  • સ્ટેટ માટે ફેક્ટરી (Factory for state) – ક્રોસ-પેજ ડેટા લીકેજ ટાળવા માટે દરેક પેજ માટે એક નવો સ્ટેટ ઓબ્જેક્ટ બનાવો.
  • ઇમ્યુટેબલ નોડ્સ (Immutable nodes) – જ્યારે તમારે ફેરફારની જરૂર હોય ત્યારે નવો નોડ રિટર્ન કરો; હાલના નોડમાં ફેરફાર (mutating) કરવાથી પછીના પ્રોસેસિંગ સ્ટેપ્સ બગડી શકે છે.
  • કોઈ રૂટ ફ્રેગમેન્ટ્સ નહીં (No root fragments) – ટોપ-લેવલ ફ્રેગમેન્ટ નોડ બનાવવાને બદલે આપેલા ઇન્સર્શન હેલ્પર્સ દ્વારા સિંબલિંગ્સ (siblings) ઇન્સર્ટ કરો.

જ્યારે તમે અસ્તિત્વમાં રહેલા પ્લગિનને એડેપ્ટ કરો, ત્યારે README ના ઉદાહરણ આઉટપુટ પર આધાર રાખશો નહીં. મૂળ પ્લગિનના HTML ને રેન્ડર કરો, તે માર્કઅપને કેપ્ચર કરો, અને તેને તમારા Sätteri-સુસંગત વર્ઝન માટે સંદર્ભ બિંદુ તરીકે ઉપયોગ કરો.

મુખ્ય વાત (Takeaway)

Astro 7 નું Sätteri engine ઝડપ લાવે છે પરંતુ તે markdown પ્રોસેસિંગ ચેઇનમાં પુનઃક્રમન કરવા માટે મજબૂર કરે છે: MDAST લેવલ પર math રેન્ડર કરો, heading-ID પ્લગિન્સને આગળ રાખો, અને કોન્ફિગરેશનને ત્રણ સ્વીકૃત ફીલ્ડ્સ સુધી મર્યાદિત કરો. feature-flag મેપિંગનું અનુસરણ કરો, single-pass અને immutable-node નિયમોનું પાલન કરો, અને તમે math, anchors, અને custom theming ને પુનઃસ્થાપિત કરી શકશો જેના પર તમારી સાઇટ નિર્ભર છે. મહેનત શરૂઆતમાં જ કરવી પડશે; બદલામાં તમને વધુ અનુમાનિત અને ઝડપી markdown પાઇપલાઇન મળશે.