Astro 7 Upgrade Breaks Math, Heading Links and Custom Options – How to Fix It

Astro 7-ന്റെ Rust അടിസ്ഥാനമാക്കിയുള്ള Sätteri markdown എഞ്ചിനിലേക്കുള്ള മാറ്റം, display-math ബ്ലോക്കുകളെ സാധാരണ കോഡായി മാറ്റുകയും, heading anchors ഇല്ലാതാക്കുകയും, custom markdown ഓപ്ഷനുകൾ ഒഴിവാക്കുകയും ചെയ്യുന്നു - ഇത് അപ്‌ഗ്രേഡ് ചെയ്തവർക്ക് അവരുടെ സൈറ്റിൽ സമവാക്യങ്ങൾ (equations) തകരാറിലാകുന്ന വലിയൊരു ബുദ്ധിമുട്ടാണ്.

നിങ്ങൾ LaTeX-style math, automatic heading links അല്ലെങ്കിൽ പ്രത്യേക markdown പ്ലഗിനുകളെ ആശ്രയിക്കുന്നുണ്ടെങ്കിൽ, ഈ അപ്‌ഗ്രേഡ് നിങ്ങളുടെ ഉള്ളടക്കം വായിക്കാൻ കഴിയാത്തതാക്കുകയും നാവിഗേഷൻ ഉപയോഗശൂന്യമാക്കുകയും ചെയ്തേക്കാം, അതിനാൽ ഇത് വേഗത്തിൽ പരിഹരിക്കേണ്ടത് അത്യാവശ്യമാണ്.

എന്തുകൊണ്ടാണ് അപ്‌ഗ്രേഡ് പ്രശ്നങ്ങൾ ഉണ്ടാക്കിയത്

Astro ഇപ്പോൾ അതിന്റെ കോർ Markdown പ്രോസസ്സറായി Sätteri ആണ് ഉപയോഗിക്കുന്നത്. Sätteri പ്ലഗിനുകൾ പ്രയോഗിക്കുന്ന ക്രമത്തിൽ മാറ്റം വരുത്തുന്നു: നിങ്ങൾ കോൺഫിഗർ ചെയ്തിട്ടുള്ള HTML-AST (HAST) പ്ലഗിനുകൾക്ക് മുമ്പ് തന്നെ ഇത് സിന്റാക്സ് ഹൈലൈറ്റിംഗ് (syntax highlighting) പ്രവർത്തിപ്പിക്കുന്നു. ഈ മാറ്റം മൂന്ന് സാധാരണ രീതികളെ പ്രവർത്തനരഹിതമാക്കുന്നു:

• Display math – $$ … $$ ഉപയോഗിച്ച് അടയാളപ്പെടുത്തിയ ബ്ലോക്കുകൾ സാധാരണ കോഡായി കണക്കാക്കപ്പെടുന്നു, കാരണം ഹൈലൈറ്റർ ആദ്യം പ്രവർത്തിക്കുന്നു.
• Heading anchors – സ്ലഗ്ഗുകൾ (URL-friendly IDs) നിർമ്മിക്കുകയും അവ ഹെഡിംഗുകളുമായി ഓട്ടോമാറ്റിക്കായി ലിങ്ക് ചെയ്യുകയും ചെയ്യുന്ന പ്ലഗിനുകൾക്ക് ഇനി മുതൽ ഐഡികൾ കാണാൻ കഴിയില്ല, അതിനാൽ ലിങ്കുകൾ ഒരിക്കലും നിർമ്മിക്കപ്പെടില്ല.
• Custom options – നിങ്ങൾ Sätteri പ്രോസസ്സറിലേക്ക് നേരിട്ട് നൽകിയ അധിക സെറ്റിംഗുകൾ അവഗണിക്കപ്പെടുന്നു; Astro മൂന്ന് മുൻകൂട്ടി നിശ്ചയിച്ച ഫീൽഡുകൾ മാത്രമേ ഫോർവേഡ് ചെയ്യുന്നുള്ളൂ.

കൃത്യമായ പരിഹാരങ്ങൾ

1. HTML-AST-ന് പകരം markdown-AST (MDAST)-ൽ math റെൻഡർ ചെയ്യുക

Astro-യുടെ markdown പൈപ്പ്‌ലൈനിൽ രണ്ട് പ്ലഗിൻ സ്ലോട്ടുകൾ ഉണ്ട്:

• 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. ഹെഡിംഗുകൾക്കായുള്ള slug, autolink പ്ലഗിനുകൾ പുനക്രമീകരിക്കുക

സാധാരണ സെറ്റപ്പുകളിൽ ഒരു സ്ലഗ് ജനറേറ്ററും അതിനുശേഷം ഒരു ഓട്ടോലിങ്ക് പ്ലഗിനും ഇൻസ്റ്റാൾ ചെയ്യുന്നു. Astro-യിൽ, ഇൻബിൽറ്റ് ഹെഡിംഗ്-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 – ട്രീ മാനുവലായി സ്പ്ലൈസ് ചെയ്യുന്നതിന് പകരം, സഹോദര നോഡുകൾ (sibling nodes) ചേർക്കേണ്ടി വരുമ്പോൾ ctx.insertBefore അല്ലെങ്കിൽ ctx.insertAfter ഉപയോഗിക്കുക.

ഈ നിയമങ്ങൾ പാലിക്കുന്നത് പ്രോസസ്സർ സ്ഥിരതയുള്ളതാക്കാനും കണ്ടെത്താൻ പ്രയാസമുള്ള ബഗുകൾ ഒഴിവാക്കാനും സഹായിക്കുന്നു.

ഇനി ശ്രദ്ധിക്കേണ്ട കാര്യങ്ങൾ

Astro-യുടെ ഡോക്യുമെന്റേഷൻ ഇപ്പോഴും പഴയ പ്ലഗിൻ ക്രമം തന്നെയാണ് ഡിഫോൾട്ട് ആയി കാണിക്കുന്നത്, അതിനാൽ പുതിയ പ്രോജക്റ്റുകളിൽ അറിയാതെ തന്നെ ഈ പ്രശ്നം ഉണ്ടായേക്കാം. ഇൻ്റേണൽ ഹെഡിംഗ്-ID പ്ലഗിൻ പുനക്രമീകരിക്കുന്നതിനുള്ള ഒരു ഇൻബിൽറ്റ് പരിഹാരത്തിനായി വരാനിരിക്കുന്ന Astro റിലീസുകൾ ശ്രദ്ധിക്കുക. അതുവരെ, Astro 7-ലേക്ക് മാറിയ ശേഷം മാത്ത് റെൻഡറിംഗ്, ഹെഡിംഗ് ആങ്കറുകൾ, കസ്റ്റം മാർക്ക്ഡൗൺ ഓപ്ഷനുകൾ എന്നിവ വീണ്ടെടുക്കാനുള്ള ഏക വിശ്വസനീയമായ മാർഗ്ഗം മുകളിൽ പറഞ്ഞ ഘട്ടങ്ങളാണ്.

ചുരുക്കത്തിൽ: Astro 7-ന്റെ Sätteri എഞ്ചിനിലേക്ക് മാറുന്നതിന് മാത്ത് ഹാൻഡ്‌ലിംഗ് mdastPlugins-ലേക്ക് മാറ്റുകയും, ഓട്ടോലിങ്കുകൾക്ക് മുമ്പ് സ്ലഗ് പ്ലഗിൻ നൽകുകയും, അധിക മാർക്ക്ഡൗൺ സെറ്റിംഗുകൾ പ്രോസസ്സർ ഒബ്‌ജക്റ്റിൽ നിന്ന് മാറ്റി ടോപ്പ് ലെവലിലേക്ക് കൊണ്ടുവരികയും വേണം; ഈ മൂന്ന് ക്രമീകരണങ്ങൾ ചെയ്താൽ നിങ്ങളുടെ സൈറ്റിലെ സമവാക്യങ്ങളും നാവിഗേഷൻ ലിങ്കുകളും കസ്റ്റം മാർക്ക്ഡൗൺ ഫീച്ചറുകളും പഴയതുപോലെ പ്രവർത്തിക്കും.