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

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

ਜੇਕਰ ਤੁਸੀਂ LaTeX-ਸਟਾਈਲ ਮੈਥ, ਆਟੋਮੈਟਿਕ ਹੈਡਿੰਗ ਲਿੰਕਸ ਜਾਂ ਬੇਸਪੋਕ (bespoke) markdown ਪਲਗਇਨਾਂ 'ਤੇ ਨਿਰਭਰ ਕਰਦੇ ਹੋ, ਤਾਂ ਇਹ ਅੱਪਗ੍ਰੇਡ ਤੁਹਾਡੇ ਕੰਟੈਂਟ ਨੂੰ ਅਣਪੜ੍ਹਯੋਗ ਅਤੇ ਤੁਹਾਡੀ ਨੈਵੀਗੇਸ਼ਨ ਨੂੰ ਬੇਕਾਰ ਬਣਾ ਸਕਦਾ ਹੈ, ਇਸ ਲਈ ਇਸਨੂੰ ਜਲਦੀ ਠੀਕ ਕਰਨਾ ਜ਼ਰੂਰੀ ਹੈ।

ਅੱਪਗ੍ਰੇਡ ਨੇ ਚੀਜ਼ਾਂ ਕਿਉਂ ਖਰਾਬ ਕਰ ਦਿੱਤੀਆਂ

Astro ਹੁਣ Sätteri ਨੂੰ ਆਪਣੇ ਕੋਰ Markdown ਪ੍ਰੋਸੈਸਰ ਵਜੋਂ ਚਲਾਉਂਦਾ ਹੈ। Sätteri ਉਹਨਾਂ ਪਲਗਇਨਾਂ ਦੇ ਕ੍ਰਮ ਨੂੰ ਬਦਲ ਦਿੰਦਾ ਹੈ ਜਿਸ ਤਰ੍ਹਾਂ ਉਹ ਲਾਗੂ ਕੀਤੇ ਜਾਂਦੇ ਹਨ: ਇਹ ਤੁਹਾਡੇ ਦੁਆਰਾ ਕੌਂਫਿਗ ਕੀਤੇ ਹੋਏ HTML-AST (HAST) ਪਲਗਇਨਾਂ ਤੋਂ ਪਹਿਲਾਂ ਸਿੰਟੈਕਸ ਹਾਈਲਾਈਟਿੰਗ (syntax highlighting) ਚਲਾਉਂਦਾ ਹੈ। ਇਸ ਤਬਦੀਲੀ ਦਾ ਮਤਲਬ ਹੈ ਕਿ ਤਿੰਨ ਆਮ ਪੈਟਰਨ ਕੰਮ ਕਰਨਾ ਬੰਦ ਕਰ ਦਿੰਦੇ ਹਨ:

• Display math – $$ … $$ ਦੁਆਰਾ ਸੀਮਤ ਬਲਾਕਾਂ ਨੂੰ ਆਮ ਕੋਡ ਵਜੋਂ ਮੰਨਿਆ ਜਾਂਦਾ ਹੈ ਕਿਉਂਕਿ ਹਾਈਲਾਈਟਰ ਪਹਿਲਾਂ ਚੱਲਦਾ ਹੈ।
• Heading anchors – ਉਹ ਪਲਗਇਨ ਜੋ ਸਲੱਗ (URL-friendly IDs) ਬਣਾਉਂਦੇ ਹਨ ਅਤੇ ਫਿਰ ਉਹਨਾਂ ਹੈਡਿੰਗਾਂ ਨੂੰ ਆਟੋਲਿੰਕ ਕਰਦੇ ਹਨ, ਉਹ ਹੁਣ IDs ਨੂੰ ਨਹੀਂ ਦੇਖ ਪਾਉਂਦੇ, ਇਸ ਲਈ ਲਿੰਕ ਕਦੇ ਬਣਦੇ ਹੀ ਨਹੀਂ।
• Custom options – ਕੋਈ ਵੀ ਵਾਧੂ ਸੈਟਿੰਗਾਂ ਜੋ ਤੁਸੀਂ ਸਿੱਧੇ Sätteri ਪ੍ਰੋਸੈਸਰ ਵਿੱਚ ਦਿੱਤੀਆਂ ਸਨ, ਉਹਨਾਂ ਨੂੰ ਨਜ਼ਰਅੰਦਾਜ਼ ਕਰ ਦਿੱਤਾ ਜਾਂਦਾ ਹੈ; Astro ਸਿਰਫ਼ ਤਿੰਨ ਪਹਿਲਾਂ ਤੋਂ ਨਿਰਧਾਰਤ ਫੀਲਡਾਂ ਨੂੰ ਹੀ ਅੱਗੇ ਭੇਜਦਾ ਹੈ।

ਠੋਸ ਹੱਲ

1. HTML-AST ਦੀ ਬਜਾਏ markdown-AST (MDAST) 'ਤੇ ਮੈਥ ਰੈਂਡਰ ਕਰੋ

Astro ਦੇ markdown ਪਾਈਪਲਾਈਨ ਵਿੱਚ ਦੋ ਪਲਗਇਨ ਸਲਾਟ ਹਨ:

• mdastPlugins – HTML ਬਣਨ ਤੋਂ ਪਹਿਲਾਂ ਪਾਰਸ ਕੀਤੇ ਗਏ markdown ਟ੍ਰੀ 'ਤੇ ਚੱਲਦੇ ਹਨ।
• 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 ਪਲਗਇਨਾਂ ਦਾ ਕ੍ਰਮ ਬਦਲੋ

ਸਟੈਂਡਰਡ ਸੈੱਟਅੱਪ ਵਿੱਚ ਇੱਕ slug ਜਨਰੇਟਰ ਅਤੇ ਉਸ ਤੋਂ ਬਾਅਦ ਇੱਕ autolink ਪਲਗਇਨ ਇੰਸਟਾਲ ਕੀਤਾ ਜਾਂਦਾ ਹੈ। Astro ਵਿੱਚ, ਬਿਲਟ-ਇਨ ਹੈਡਿੰਗ-ID ਪਲਗਇਨ ਤੁਹਾਡੀ ਸੂਚੀ ਦੇ ਬਾਅਦ ਚੱਲਦਾ ਹੈ, ਜਿਸ ਨਾਲ autolink ਪਲਗਇਨ ਲਈ ਕੁਝ ਵੀ ਨਹੀਂ ਬਚਦਾ। ਸੂਚੀ ਵਿੱਚ ਪਹਿਲਾਂ slug ਪਲਗਇਨ ਰੱਖੋ, ਫਿਰ autolink ਪਲਗਇਨ।

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

ਹੁਣ ਹਰੇਕ ਹੈਡਿੰਗ ਨੂੰ ਇੱਕ ID ਮਿਲਦੀ ਹੈ ਅਤੇ autolink ਪਲਗਇਨ ਇਸਨੂੰ ਉਚਿਤ ਐਂਕਰ (anchor) ਨਾਲ ਲਪੇਟ ਸਕਦਾ ਹੈ।

3. ਵਾਧੂ ਕੌਂਫਿਗਰੇਸ਼ਨ ਨੂੰ Astro markdown ਆਬਜੈਕਟ ਦੇ ਟੌਪ ਲੈਵਲ 'ਤੇ ਰੱਖੋ

Astro ਸਿਰਫ਼ ਤਿੰਨ ਖਾਸ ਫੀਲਡਾਂ ਨੂੰ Sätteri ਪ੍ਰੋਸੈਸਰ ਨੂੰ ਭੇਜਦਾ ਹੈ। ਤੁਸੀਂ ਪ੍ਰੋਸੈਸਰ ਦੇ ਅੰਦਰ ਜੋ ਵੀ ਨੈਸਟ (nest) ਕਰਦੇ ਹੋ (ਉਦਾਹਰਨ ਲਈ ਇੱਕ shikiConfig ਆਬਜੈਕਟ), ਉਹ ਡ੍ਰੌਪ ਹੋ ਜਾਂਦਾ ਹੈ। ਉਹਨਾਂ ਵਾਧੂ ਸੈਟਿੰਗਾਂ ਨੂੰ markdown ਕੌਂਫਿਗਰੇਸ਼ਨ ਦੇ ਟੌਪ ਲੈਵਲ 'ਤੇ ਲੈ ਜਾਓ।

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

ਆਮ remark ਪਲਗਇਨਾਂ ਲਈ ਤੇਜ਼ੀ ਨਾਲ ਬਦਲਣ ਲਈ ਗਾਈਡ

Old remark plugin	New 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 ਕੌਂਫਿਗ ਵਿੱਚ ਪਲਗਇਨ ਦੇ ਨਾਮ ਨੂੰ ਸੰਬੰਧਿਤ features.* ਫਲੈਗ ਨਾਲ ਬਦਲ ਦਿਓ।

ਪਲਗਇਨਾਂ ਨੂੰ Sätteri ਵਿੱਚ ਪੋਰਟ ਕਰਦੇ ਸਮੇਂ ਵਧੀਆ ਅਭਿਆਸ (Best practices)

• Factory pattern – ਪੇਜਾਂ ਵਿਚਕਾਰ ਸਟੇਟ (state) ਲੀਕ ਹੋਣ ਤੋਂ ਬਚਣ ਲਈ ਹਰੇਕ ਦਸਤਾਵੇਜ਼ ਲਈ ਇੱਕ ਨਵਾਂ ਪਲਗਇਨ ਇੰਸਟੈਂਸ ਬਣਾਓ।
• Immutable nodes – ਕਿਸੇ ਨੋਡ ਨੂੰ ਕਦੇ ਵੀ ਸਥਾਨ 'ਤੇ (in place) ਮਿਊਟੇਟ ਨਾ ਕਰੋ; ਇੱਕ ਨਵਾਂ ਨੋਡ ਆਬਜੈਕਟ ਵਾਪਸ ਕਰੋ ਤਾਂ ਜੋ ਪ੍ਰੋਸੈਸਰ ਸਹੀ ਢੰਗ ਨਾਲ ਤਬਦੀਲੀਆਂ ਨੂੰ ਟ੍ਰੈਕ ਕਰ ਸਕੇ।
• Insert helpers – ਜਦੋਂ ਤੁਹਾਨੂੰ ਸਿਬਲਿੰਗ (sibling) ਨੋਡਸ ਜੋੜਨ ਦੀ ਲੋੜ ਹੁੰਦੀ ਹੈ, ਤਾਂ ਟ੍ਰੀ ਨੂੰ ਮੈਨੂਅਲੀ ਸਪਲਾਈਸ ਕਰਨ ਦੀ ਬਜਾਏ ctx.insertBefore ਜਾਂ ctx.insertAfter ਦੀ ਵਰਤੋਂ ਕਰੋ।

ਇਹਨਾਂ ਨਿਯਮਾਂ ਦੀ ਪਾਲਣਾ ਕਰਨ ਨਾਲ ਪ੍ਰੋਸੈਸਰ ਸਥਿਰ ਰਹਿੰਦਾ ਹੈ ਅਤੇ ਮੁਸ਼ਕਲ ਬੱਗਾਂ (bugs) ਤੋਂ ਬਚਾਅ ਹੁੰਦਾ ਹੈ।

ਅੱਗੇ ਕੀ ਦੇਖਣਾ ਹੈ

Astro ਦਾ ਦਸਤਾਵੇਜ਼ ਅਜੇ ਵੀ ਪੁਰਾਣੇ ਪਲਗਇਨ ਕ੍ਰਮ ਨੂੰ ਡਿਫੌਲਟ ਵਜੋਂ ਸੂਚੀਬੱਧ ਕਰਦਾ ਹੈ, ਇਸ ਲਈ ਨਵੇਂ ਪ੍ਰੋਜੈਕਟਾਂ ਵਿੱਚ ਅਣਜਾਣੇ ਵਿੱਚ ਇਹ ਖਰਾਬ ਵਿਵਹਾਰ ਆ ਸਕਦਾ ਹੈ। ਆਉਣ ਵਾਲੇ Astro ਰਿਲੀਜ਼ਾਂ 'ਤੇ ਨਜ਼ਰ ਰੱਖੋ ਕਿਉਂਕਿ ਸ਼ਾਇਦ ਕੋਈ ਬਿਲਟ-ਇਨ ਫਿਕਸ ਆਵੇ ਜੋ ਅੰਦਰੂਨੀ ਹੈਡਿੰਗ-ID ਪਲਗਇਨ ਦੇ ਕ੍ਰਮ ਨੂੰ ਦੁਬਾਰਾ ਸੈੱਟ ਕਰ ਦੇਵੇ। ਇਸ ਦੌਰਾਨ, Astro 7 ਵਿੱਚ ਜਾਣ ਤੋਂ ਬਾਅਦ ਮੈਥ ਰੈਂਡਰਿੰਗ, ਹੈਡਿੰਗ ਐਂਕਰ ਅਤੇ ਕਸਟਮ markdown ਵਿਕਲਪਾਂ ਨੂੰ ਬਹਾਲ ਕਰਨ ਲਈ ਉੱਪਰ ਦਿੱਤੇ ਕਦਮ ਹੀ ਇਕਲੌਤੇ ਭਰੋਸੇਯੋਗ ਤਰੀਕੇ ਹਨ।

ਮੁੱਖ ਨੁਕਤਾ: Astro 7 ਦੇ Sätteri ਇੰਜਣ ਵਿੱਚ ਬਦਲਣ ਲਈ ਮੈਥ ਹੈਂਡਲਿੰਗ ਨੂੰ mdastPlugins ਵਿੱਚ ਲੈ ਕੇ ਜਾਣਾ, autolinks ਤੋਂ ਪਹਿਲਾਂ slug ਪਲਗਇਨ ਨੂੰ ਅੱਗੇ ਰੱਖਣਾ, ਅਤੇ ਕਿਸੇ ਵੀ ਵਾਧੂ markdown ਸੈਟਿੰਗ ਨੂੰ ਪ੍ਰੋਸੈਸਰ ਆਬਜੈਕਟ ਤੋਂ ਬਾਹਰ ਕੱਢਣਾ ਜ਼ਰੂਰੀ ਹੈ; ਇੱਕ ਵਾਰ ਜਦੋਂ ਇਹ ਤਿੰਨ ਐਡਜਸਟਮੈਂਟ ਕਰ ਦਿੱਤੇ ਜਾਂਦੇ ਹਨ, ਤਾਂ ਤੁਹਾਡੀ ਸਾਈਟ ਦੇ ਇਕੁਏਸ਼ਨਾਂ, ਨੈਵੀਗੇਸ਼ਨ ਲਿੰਕਸ ਅਤੇ ਕਸਟਮ markdown ਫੀਚਰ ਪਹਿਲਾਂ ਵਾਂਗ ਕੰਮ ਕਰਨ ਲੱਗਦੇ ਹਨ।