Astro 7-ன் Rust அடிப்படையிலான Sätteri markdown engine-க்கு மாறியதால், display-math தொகுதிகள் சாதாரண code-ஆக மாறுகின்றன, heading anchors நீக்கப்படுகின்றன மற்றும் custom markdown விருப்பங்கள் கைவிடப்படுகின்றன – இது upgrade செய்த பிறகு தங்கள் தளத்தில் சமன்பாடுகள் (equations) உடைந்து போனதைக் காணும் எவருக்கும் ஒரு பெரிய சிக்கலாகும்.

நீங்கள் LaTeX-style math, automatic heading links அல்லது தனிப்பயனாக்கப்பட்ட (bespoke) markdown plugins ஆகியவற்றைச் சார்ந்து இருந்தால், இந்த upgrade உங்கள் உள்ளடக்கத்தைப் படிக்க முடியாததாகவும், உங்கள் navigation-ஐப் பயன்படுத்த முடியாததாகவும் மாற்றக்கூடும், எனவே இதை விரைவாகச் சரிசெய்வது அவசியமாகும்.

ஏன் இந்த upgrade அனைத்தையும் பாதித்தது

Astro இப்போது Sätteri-யை அதன் முக்கிய Markdown processor-ஆக இயக்குகிறது. Sätteri plugins பயன்படுத்தப்படும் வரிசையை மாற்றுகிறது: நீங்கள் கட்டமைத்துள்ள HTML-AST (HAST) plugins-க்கு முன்பே இது syntax highlighting-ஐ இயக்குகிறது. இந்த மாற்றம் மூன்று பொதுவான முறைகள் வேலை செய்வதை நிறுத்துகிறது:

  • Display math – $$ … $$ மூலம் பிரிக்கப்பட்ட தொகுதிகள் சாதாரண code-ஆகக் கருதப்படுகின்றன, ஏனெனில் highlighter முதலில் இயங்குகிறது.
  • Heading anchors – slugs (URL-friendly IDs) உருவாக்கி, பின்னர் அந்த headings-களை autolink செய்யும் plugins-களால் இனி IDs-களைக் காண முடியாது, எனவே links உருவாக்கப்படுவதில்லை.
  • Custom options – நீங்கள் Sätteri processor-க்குள் நேரடியாக அனுப்பிய கூடுதல் அமைப்புகள் புறக்கணிக்கப்படுகின்றன; Astro மூன்று முன் வரையறுக்கப்பட்ட (predefined) புலங்களை மட்டுமே முன்னோக்கி அனுப்புகிறது.

உறுதியான தீர்வுகள்

1. HTML-AST-க்கு பதிலாக markdown-AST (MDAST)-இல் math-ஐ render செய்யவும்

Astro-வின் markdown pipeline இரண்டு plugin slots-களைக் கொண்டுள்ளது:

  • mdastPlugins – markdown parse செய்யப்பட்ட பிறகு, அது HTML-ஆக மாறுவதற்கு முன்பு இயங்குகிறது.
  • hastPlugins – HTML-ஆக மாற்றப்பட்ட பிறகு 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
  }
}

Standard setups-களில் ஒரு slug generator-ஐத் தொடர்ந்து autolink plugin நிறுவப்படும். Astro-வில், உள்ளமைக்கப்பட்ட (built-in) heading-ID plugin உங்கள் பட்டியலுக்கு பிறகு இயங்குகிறது, இதனால் autolink plugin-ஆல் இணைக்க எதுவும் மிஞ்சவில்லை. பட்டியலில் slug plugin-ஐ முதலில் வைத்து, பின்னர் autolink plugin-ஐ வைக்கவும்.

export default {
  markdown: {
    mdastPlugins: [
      satteriSlug(),            // must be first
      satteriAutolinkHeadings() // runs after slug, sees IDs
    ]
  }
}

இப்போது ஒவ்வொரு heading-க்கும் ஒரு ID கிடைக்கும் மற்றும் autolink plugin அதைத் தகுந்த anchor-உடன் இணைக்க முடியும்.

3. கூடுதல் configuration-ஐ Astro markdown object-இன் top level-இல் வைக்கவும்

Astro, Sätteri processor-க்கு மூன்று குறிப்பிட்ட புலங்களை மட்டுமே அனுப்புகிறது. நீங்கள் processor-க்குள் (உதாரணமாக ஒரு shikiConfig object) வைக்கும் எதையும் அது நீக்கிவிடும். அந்த கூடுதல் அமைப்புகளை markdown configuration-இன் top level-க்கு மாற்றவும்.

export default {
  markdown: {
    shikiConfig: { theme: 'nord' }, // top-level, will be respected
    // other Astro-accepted fields …
    mdastPlugins: [/* … */],
    hastPlugins: [/* … */]
  }
}

பொதுவான remark plugins-க்கான விரைவான மாற்று வழிகாட்டி

பழைய 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-இல் plugin பெயருக்குப் பதிலாக அதற்கு இணையான features.* flag-ஐ மாற்றவும்.

Sätteri-க்கு plugins-களை மாற்றும்போது பின்பற்ற வேண்டிய சிறந்த நடைமுறைகள்

  • Factory pattern – பக்கங்களுக்கு இடையே state கசிவதைத் தவிர்க்க, ஒவ்வொரு ஆவணத்திற்கும் ஒரு புதிய plugin instance-ஐ உருவாக்கவும்.
  • Immutable nodes – ஒரு node-ஐ அப்படியே மாற்ற வேண்டாம்; processor மாற்றங்களைக் சரியாகக் கண்காணிக்க புதிய node object-ஐத் திருப்பிக் கொடுக்கவும்.
  • Insert helpers – மரத்தை (tree) கைமுறையாகச் சரிசெய்வதற்குப் பதிலாக, sibling nodes-களைச் சேர்க்க வேண்டியிருக்கும் போது ctx.insertBefore அல்லது ctx.insertAfter-ஐப் பயன்படுத்தவும்.

இந்த விதிகளைப் பின்பற்றுவது processor-ஐ நிலையானதாக வைத்திருக்கும் மற்றும் கண்டறிவதற்கு கடினமான பிழைகளைத் தடுக்கும்.

அடுத்து கவனிக்க வேண்டியவை

Astro-வின் ஆவணங்கள் இன்னும் பழைய plugin வரிசையையே இயல்பானதாகக் குறிப்பிடுகின்றன, எனவே புதிய திட்டங்கள் (projects) தற்செயலாக இந்தச் சிக்கலான நடத்தையைப் பெறக்கூடும். உள்ளமைக்கப்பட்ட heading-ID plugin-ன் வரிசையை மாற்றும் சாத்தியமான built-in fix-க்காக வரவிருக்கும் Astro releases-களைக் கவனித்துக் கொண்டே இருங்கள். இதற்கிடையில், Astro 7-க்கு மாறிய பிறகு math rendering, heading anchors மற்றும் custom markdown விருப்பங்களை மீட்டெடுக்க மேலே உள்ள படிகளே நம்பகமான வழிகளாகும்.

சுருக்கம்: Astro 7-ன் Sätteri engine-க்கு மாறுவதற்கு, math handling-ஐ mdastPlugins-க்கு மாற்றவும், autolinks-க்கு முன்னதாக slug plugin-ஐ வைக்கவும், மற்றும் கூடுதல் markdown அமைப்புகளை processor object-லிருந்து வெளியே எடுக்கவும் வேண்டும்; இந்த மூன்று மாற்றங்களையும் செய்தவுடன், உங்கள் தளத்தின் சமன்பாடுகள், navigation links மற்றும் custom markdown அம்சங்கள் முன்பைப் போலவே செயல்படும்.