Astro 7 ਦਾ Rust-ਅਧਾਰਿਤ Sätteri markdown engine ਵਿੱਚ ਬਦਲਾਅ ਉਹਨਾਂ ਸਾਈਟਾਂ ਲਈ ਇੱਕ ਤਿੰਨ-ਗੁਣਾ ਮੁਸ਼ਕਲ (nightmare) ਬਣ ਗਿਆ ਹੈ ਜੋ math, heading anchors, ਅਤੇ custom configuration 'ਤੇ ਨਿਰਭਰ ਕਰਦੀਆਂ ਹਨ। Inline equations ਅਜੇ ਵੀ ਕੰਮ ਕਰਦੀਆਂ ਹਨ, ਪਰ display-math blocks ਸਾਧਾਰਨ-ਟੈਕਸਟ code snippets ਵਾਂਗ ਦਿਖਾਈ ਦਿੰਦੇ ਹਨ, heading IDs ਗਾਇਬ ਹੋ ਜਾਂਦੀਆਂ ਹਨ, ਅਤੇ Astro config ਵਿੱਚ ਤੁਹਾਡੇ ਦੁਆਰਾ ਜੋੜੇ ਗਏ ਕੋਈ ਵੀ ਵਾਧੂ ਵਿਕਲਪ ਚੁੱਪਚਾਪ ਨਜ਼ਰਅੰਦਾਜ਼ ਕਰ ਦਿੱਤੇ ਜਾਂਦੇ ਹਨ। ਜੋ ਡਿਵੈਲਪਰ ਪਹਿਲਾਂ ਵਾਲੇ Astro releases ਤੋਂ ਮਾਈਗ੍ਰੇਟ ਕਰ ਰਹੇ ਹਨ, ਉਹਨਾਂ ਨੂੰ ਹੁਣ plugins ਨੂੰ ਦੁਬਾਰਾ ਲਿਖਣਾ ਪਵੇਗਾ ਜਾਂ ਟੁੱਟੇ ਹੋਏ ਪੇਜਾਂ ਦਾ ਖ਼ਤਰਾ ਹੋ ਸਕਦਾ ਹੈ।

ਇਹ ਬਦਲਾਅ ਕਿਉਂ ਮਹੱਤਵਪੂਰਨ ਹੈ

ਨਵਾਂ engine ਕਿਸੇ ਵੀ user-supplied plugins ਤੋਂ ਪਹਿਲਾਂ ਇੱਕ built-in syntax highlighter ਚਲਾਉਂਦਾ ਹੈ ਅਤੇ ਸਿਰਫ਼ ਤਿੰਨ top-level configuration fields ਨੂੰ ਹੀ ਸਵੀਕਾਰ ਕਰਦਾ ਹੈ। ਇਹ ਚੋਣਾਂ ਉਸ ਤਰੀਕੇ ਨਾਲ ਟਕਰਾਉਂਦੀਆਂ ਹਨ ਜਿਸ ਰਾਹੀਂ ਜ਼ਿਆਦਾਤਰ Astro projects ਵਿੱਚ features ਜੋੜੇ ਜਾਂਦੇ ਹਨ: remark (MDAST) ਅਤੇ rehype (HAST) plugins ਰਾਹੀਂ ਜੋ highlighting ਤੋਂ ਬਾਅਦ ਚੱਲਣ ਦੀ ਉਮੀਦ ਕਰਦੇ ਹਨ, ਅਤੇ ਇੱਕ permissive config object ਰਾਹੀਂ ਜੋ underlying markdown parser ਤੱਕ ਪਹੁੰਚਦਾ ਹੈ।

ਇਸਦਾ ਪ੍ਰਭਾਵ ਕਿਸੇ ਵੀ ਅਜਿਹੇ ਪੇਜ 'ਤੇ ਦਿਖਾਈ ਦਿੰਦਾ ਹੈ ਜੋ LaTeX-style math ਨੂੰ ਆਮ ਸਮੱਗਰੀ (content) ਨਾਲ ਮਿਲਾਉਂਦਾ ਹੈ। Inline math ($a+b$) ਸਹੀ ਤਰ੍ਹਾਂ ਰੈਂਡਰ ਹੁੰਦੀ ਹੈ, ਪਰ ਇੱਕ display block ($$a+b$$) ਨੂੰ <pre> tag ਵਿੱਚ ਲਪੇਟਿਆ ਜਾਂਦਾ ਹੈ, ਜੋ ਇੱਕ ਫਾਰਮੈਟ ਕੀਤੇ equation ਦੀ ਬਜਾਏ raw markup ਦਿਖਾਉਂਦਾ ਹੈ। Heading anchors ਜੋ table-of-contents links ਜਾਂ deep-linking ਨੂੰ ਚਲਾਉਂਦੇ ਹਨ, ਉਹ ਗਾਇਬ ਹੋ ਜਾਂਦੇ ਹਨ ਕਿਉਂਕਿ ID-generation plugin built-in ID handler ਤੋਂ ਪਹਿਲਾਂ ਚੱਲਦਾ ਹੈ, ਜਿਸ ਨਾਲ autolink plugin ਲਈ ਕੁਝ ਵੀ ਨਹੀਂ ਬਚਦਾ। ਉਹ ਡਿਵੈਲਪਰ ਜਿਨ੍ਹਾਂ ਨੇ shikiConfig object ਨਾਲ Shiki syntax highlighter ਨੂੰ fine-tune ਕਰਨ ਦੀ ਕੋਸ਼ਿਸ਼ ਕੀਤੀ ਸੀ, ਉਹਨਾਂ ਨੂੰ ਪਤਾ ਲੱਗਦਾ ਹੈ ਕਿ ਉਹ ਸੈਟਿੰਗ ਬਿਨਾਂ ਕਿਸੇ ਨਿਸ਼ਾਨ ਦੇ ਗਾਇਬ ਹੋ ਗਈ ਹੈ।

ਤਕਨੀਕੀ ਹੱਲ (The technical fixes)

1. Highlighting ਤੋਂ ਪਹਿਲਾਂ math ਨੂੰ ਰੈਂਡਰ ਕਰੋ

ਇਸਦਾ ਮੁੱਖ ਕਾਰਨ ਕੰਮ ਕਰਨ ਦਾ ਕ੍ਰਮ (order of operations) ਹੈ: Sätteri ਦਾ highlighter ਪਹਿਲਾਂ ਟੈਕਸਟ ਨੂੰ ਕਬਜ਼ੇ ਵਿੱਚ ਲੈ ਲੈਂਦਾ ਹੈ, ਅਤੇ math block ਨੂੰ plain code ਵਜੋਂ ਸ਼੍ਰੇਣੀਬੱਧ ਕਰ ਦਿੰਦਾ ਹੈ। Math ਨੂੰ ਵਾਪਸ ਪ੍ਰਾਪਤ ਕਰਨ ਲਈ, processing ਨੂੰ MDAST layer (abstract syntax tree ਜੋ HTML ਬਣਨ ਤੋਂ ਪਹਿਲਾਂ markdown ਨੂੰ ਦਰਸਾਉਂਦਾ ਹੈ) 'ਤੇ ਤਬਦੀਲ ਕਰੋ। ਕਿਸੇ ਵੀ HAST-level math plugins ਨੂੰ ਉਹਨਾਂ ਦੇ MDAST equivalents ਨਾਲ ਬਦਲੋ ਅਤੇ ਉਹਨਾਂ ਨੂੰ highlighter step ਤੋਂ ਪਹਿਲਾਂ ਚਲਾਓ। ਅਸਲ ਵਿੱਚ, remark-math plugins ਨੂੰ ਅਜਿਹੇ version ਨਾਲ ਬਦਲੋ ਜੋ markdown parsing stage ਨਾਲ ਜੁੜਿਆ ਹੋਵੇ, ਫਿਰ highlighter ਨੂੰ ਪਹਿਲਾਂ ਤੋਂ ਹੀ-ਕਨਵਰਟ ਕੀਤੇ math nodes 'ਤੇ ਕੰਮ ਕਰਨ ਦਿਓ।

2. Heading-ID plugins ਦਾ ਕ੍ਰਮ ਬਦਲੋ

Heading IDs ਇੱਕ built-in plugin ਦੁਆਰਾ ਬਣਾਏ ਜਾਂਦੇ ਹਨ ਜੋ ਹੁਣ user plugins ਤੋਂ ਬਾਅਦ ਚੱਲਦਾ ਹੈ। Custom ID ਜਾਂ slug generators ਨੂੰ plugin list ਦੇ ਸਭ ਤੋਂ ਉੱਪਰ ਲਿਜਾਓ ਤਾਂ ਜੋ ਉਹ ਪਹਿਲਾਂ ਚੱਲਣ। Anchor links ਨੂੰ ਬਹਾਲ ਕਰਨ ਵਾਲਾ ਇੱਕ ਆਮ ਕ੍ਰਮ ਇਸ ਤਰ੍ਹਾਂ ਦਿਖਾਈ ਦਿੰਦਾ ਹੈ:

  1. slug/ID plugin
  2. autolink plugin
  3. ਕੋਈ ਵੀ ਹੋਰ remark plugins

IDs ਦੇ ਸ਼ੁਰੂ ਵਿੱਚ ਹੀ ਮੌਜੂਦ ਹੋਣ ਨਾਲ, autolink plugin ਉਮੀਦ ਕੀਤੇ <a> elements ਲਗਾ ਸਕਦਾ ਹੈ, ਅਤੇ table-of-contents ਸਹੀ ਸੈਕਸ਼ਨਾਂ ਵੱਲ ਇਸ਼ਾਰਾ ਕਰੇਗਾ।

3. Sätteri ਦੇ ਸਖ਼ਤ config schema ਦਾ ਸਤਿਕਾਰ ਕਰੋ

Sätteri Astro markdown configuration ਵਿੱਚ ਸਿਰਫ਼ ਤਿੰਨ fields ਨੂੰ ਹੀ ਸਵੀਕਾਰ ਕਰਦਾ ਹੈ। ਕੋਈ ਵੀ ਹੋਰ ਚੀਜ਼, ਜਿਵੇਂ ਕਿ shikiConfig, ਚੁੱਪਚਾਪ ਡ੍ਰੌਪ (drop) ਕਰ ਦਿੱਤੀ ਜਾਂਦੀ ਹੈ। Custom themes ਜਾਂ highlighter tweaks ਨੂੰ ਬਰਕਰਾਰ ਰੱਖਣ ਲਈ, ਉਹਨਾਂ ਸੈਟਿੰਗਾਂ ਨੂੰ Astro config hierarchy ਵਿੱਚ ਸਹੀ ਪੱਧਰ 'ਤੇ ਰੀਲੋਕੇਟ (relocate) ਕਰੋ।

ਤੇਜ਼ੀ ਨਾਲ ਬਦਲਣ ਲਈ ਗਾਈਡ (Quick replacement guide)

ਜੇਕਰ ਤੁਸੀਂ ਇੱਕ ਕਲਾਸਿਕ Astro markdown stack ਨੂੰ ਪੋਰਟ ਕਰ ਰਹੇ ਹੋ, ਤਾਂ ਪੁਰਾਣੇ remark plugins ਨੂੰ ਨਵੇਂ feature flags ਨਾਲ ਬਦਲੋ ਜੋ 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

ਇਹ flags ਵੱਖਰੇ plugin load ਦੀ ਲੋੜ ਤੋਂ ਬਿਨਾਂ ਉਹੀ ਸਮਰੱਥਾਵਾਂ (capabilities) ਪ੍ਰਦਾਨ ਕਰਦੇ ਹਨ।

Sätteri ਦੇ ਨਾਲ plugins ਨੂੰ ਸਹੀ ਰੱਖਣ ਲਈ ਨਿਯਮ

  • Single pass only – Plugins tree ਨੂੰ ਸਿਰਫ਼ ਇੱਕ ਵਾਰ ਦੇਖਦੇ ਹਨ; ਉਹ pipeline ਵਿੱਚ ਬਾਅਦ ਵਿੱਚ ਬਣਾਏ ਗਏ nodes 'ਤੇ ਦੁਬਾਰਾ ਨਹੀਂ ਜਾ ਸਕਦੇ।
  • Factory for state – cross-page data leakage ਤੋਂ ਬਚਣ ਲਈ ਹਰੇਕ ਪੇਜ ਲਈ ਇੱਕ ਨਵਾਂ state object ਬਣਾਓ।
  • Immutable nodes – ਜਦੋਂ ਤੁਹਾਨੂੰ ਬਦਲਾਅ ਦੀ ਲੋੜ ਹੋਵੇ ਤਾਂ ਇੱਕ ਨਵਾਂ node ਵਾਪਸ ਕਰੋ; ਮੌਜੂਦਾ node ਨੂੰ ਬਦਲਣ (mutating) ਨਾਲ ਅਗਲੇ ਪ੍ਰੋਸੈਸਿੰਗ ਸਟੈਪ ਟੁੱਟ ਸਕਦੇ ਹਨ।
  • No root fragments – top-level fragment node ਬਣਾਉਣ ਦੀ ਬਜਾਏ ਦਿੱਤੇ ਗਏ insertion helpers ਰਾਹੀਂ siblings ਨੂੰ ਇਨਸਰਟ ਕਰੋ।

ਜਦੋਂ ਤੁਸੀਂ ਕਿਸੇ ਮੌਜੂਦਾ plugin ਨੂੰ ਅਨੁਕੂਲ (adapt) ਕਰਦੇ ਹੋ, ਤਾਂ README ਦੇ ਉਦਾਹਰਣ ਆਉਟਪੁੱਟ 'ਤੇ ਭਰੋਸਾ ਨਾ ਕਰੋ। ਅਸਲ plugin ਦੇ HTML ਨੂੰ ਰੈਂਡਰ ਕਰੋ, ਉਸ markup ਨੂੰ ਕੈਪਚਰ ਕਰੋ, ਅਤੇ ਇਸਨੂੰ ਆਪਣੇ Sätteri-compatible version ਲਈ ਰੈਫਰੈਂਸ ਪੁਆਇੰਟ ਵਜੋਂ ਵਰਤੋ।

ਸਿੱਟਾ (Takeaway)

Astro 7 ਦਾ Sätteri engine ਰਫਤਾਰ ਤਾਂ ਲਿਆਉਂਦਾ ਹੈ ਪਰ ਇਹ markdown processing chain ਦੇ ਕ੍ਰਮ ਨੂੰ ਮੁੜ ਵਿਵਸਥਿਤ ਕਰਨ ਲਈ ਮਜਬੂਰ ਕਰਦਾ ਹੈ: MDAST ਲੈਵਲ 'ਤੇ math ਨੂੰ ਰੈਂਡਰ ਕਰੋ, heading-ID plugins ਨੂੰ ਸਭ ਤੋਂ ਅੱਗੇ ਰੱਖੋ, ਅਤੇ configuration ਨੂੰ ਤਿੰਨ ਮਨਜ਼ੂਰਸ਼ੁਦਾ ਫੀਲਡਾਂ ਤੱਕ ਹੀ ਸੀਮਤ ਰੱਖੋ। feature-flag mapping ਦੀ ਪਾਲਣਾ ਕਰੋ, single-pass ਅਤੇ immutable-node ਨਿਯਮਾਂ ਦੀ ਪਾਲਣਾ ਕਰੋ, ਅਤੇ ਤੁਸੀਂ ਉਸ math, anchors, ਅਤੇ custom theming ਨੂੰ ਬਹਾਲ ਕਰ ਲਵੋਗੇ ਜਿਸ 'ਤੇ ਤੁਹਾਡੀ ਸਾਈਟ ਨਿਰਭਰ ਕਰਦੀ ਹੈ। ਮਿਹਨਤ ਸ਼ੁਰੂਆਤੀ ਪੜਾਅ 'ਤੇ ਹੀ ਕਰਨੀ ਪਵੇਗੀ; ਪਰ ਇਸਦਾ ਫਲ ਇੱਕ ਵਧੇਰੇ ਭਰੋਸੇਯੋਗ ਅਤੇ ਤੇਜ਼ markdown pipeline ਦੇ ਰੂਪ ਵਿੱਚ ਮਿਲੇਗਾ।