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

Uhamishaji wa Astro 7 kwenda injini ya markdown ya Sätteri inayotegemea Rust unageuza vizuizi vya display-math kuwa kodi ya kawaida, unaondoa nanga za vichwa vya habari (heading anchors) na kutupa chaguzi za markdown zilizoundwa maalum – jambo linalowapa shida wale wote waliofanya sasisho na sasa wanaona milinganyo iliyoharibika kwenye tovuti zao.

Ikiwa unategemea hisabati ya mtindo wa LaTeX, viungo vya vichwa vya habari vya kiotomatiki, au programu nyongeza (plugins) za markdown maalum, sasisho hili linaweza kufanya maudhui yako yasomeke na urambazaji wako usitumike, hivyo ni muhimu kulirekebisha haraka.

Kwa nini sasisho lilivuruga mambo

Astro sasa inatumia Sätteri kama kichakataji chake kikuu cha Markdown. Sätteri inabadilisha mpangilio ambao programu nyongeza zinatumika: inafanya syntax highlighting kabla ya programu nyongeza za HTML-AST (HAST) ambazo unaweza kuwa umezisanidi. Mabadiliko hayo yanamaanisha mifumo mitatu ya kawaida huacha kufanya kazi:

• Display math – vizuizi vilivyowekwa kati ya $$ … $$ vinachukuliwa kama kodi ya kawaida kwa sababu highlighter inafanya kazi kwanza.
• Heading anchors – programu nyongeza zinazozalisha slugs (ID zinazofaa kwa URL) na kisha kuunganisha vichwa hivyo kiotomatiki (autolink) hazioni tena ID hizo, hivyo viungo havijatengenezwa.
• Custom options – mipangilio yoyote ya ziada uliyoiweka moja kwa moja kwenye kichakataji cha Sätteri inapuuzwa; Astro inapitisha tu nyanja tatu zilizofafanuliwa mapema.

Marekebisho ya uhakika

1. Tengeneza (Render) hisabati kwenye markdown-AST (MDAST) badala ya HTML-AST

Mchakato wa markdown wa Astro una nafasi mbili za programu nyongeza:

• mdastPlugins – hufanya kazi kwenye mti wa markdown uliopasuliwa kabla haujawa HTML.
• hastPlugins – hufanya kazi kwenye mti wa HTML baada ya ubadilishaji.

Kwa sababu highlighter inafanya kazi kabla ya hastPlugins, hisabati inageuzwa kuwa kizuizi cha kodi. Hamisha programu nyongeza yako ya hisabati (math plugin) kwenda kwenye mdastPlugins.

export default {
  markdown: {
    mdastPlugins: [
      // put remark-math (or your custom math handler) here
    ],
    // leave hastPlugins for things that truly need HTML nodes
  }
}

2. Panga upya programu nyongeza za slug na autolink kwa vichwa vya habari

Mipangilio ya kawaida huweka programu nyongeza ya kuzalisha slug ikifuatiwa na programu nyongeza ya autolink. Katika Astro, programu nyongeza ya heading-ID iliyojengewa ndani inafanya kazi baada ya orodha yako, hivyo haikiachi chochote kwa programu nyongeza ya autolink kuunganisha. Weka programu nyongeza ya slug kwanza kwenye orodha, kisha programu nyongeza ya autolink.

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

Sasa kila kichwa cha habari kinapokea ID na programu nyongeza ya autolink inaweza kukizungushia nanga (anchor) inayofaa.

3. Weka mipangilio ya ziada katika ngazi ya juu ya kitu cha markdown cha Astro

Astro inapitisha tu nyanja tatu mahususi kwa kichakataji cha Sätteri. Chochote unachoweka ndani ya kichakataji (kwa mfano, kitu cha shikiConfig) kinaondolewa. Hamisha mipangilio hiyo ya ziada kwenda kwenye ngazi ya juu ya usanidi wa markdown.

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

Mwongozo wa haraka wa kubadilisha programu nyongeza za remark za kawaida

Programu nyongeza ya remark ya zamani	Bendera mpya ya feature ya 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

Badilisha jina la programu nyongeza na bendera ya features.* inayolingana kwenye usanidi wako wa Astro.

Mbinu bora wakati wa kuhamisha programu nyongeza kwenda Sätteri

• Factory pattern – tengeneza nakala mpya ya programu nyongeza kwa kila hati ili kuepuka kuvuja kwa hali (state) kati ya kurasa.
• Immutable nodes – usibadilishe kamwe noda (node) papo hapo; rudisha noda mpya ili kichakataji kiweze kufuatilia mabadiliko kwa usahihi.
• Insert helpers – tumia ctx.insertBefore au ctx.insertAfter unapohitaji kuongeza noda ndugu (sibling nodes), badala ya kukata mti (splicing the tree) mwenyewe.

Kufuata sheria hizi huifanya programu nyongeza iwe thabiti na kuzuia hitilafu (bugs) ngumu kufuatilia.

Nini cha kufuatilia baadaye

Nyaraka za Astro bado zinaorodhesha mpangilio wa zamani wa programu nyongeza kama chaguo-msingi, hivyo miradi mipya inaweza kupata tabia hiyo iliyoharibika bila kukusudia. Kuwa mwangalifu na matoleo yanayokuja ya Astro kwa ajili ya urekebishaji unaoweza kujengewa ndani unaoweza kupanga upya programu nyongeza ya heading-ID ya ndani. Wakati huo huo, hatua hapo juu ndizo njia pekee za kuaminika za kurejesha uwasilishaji wa hisabati, nanga za vichwa vya habari, na chaguzi za markdown maalum baada ya kuhamia Astro 7.

Muhtasari: Uhamishaji kwenda injini ya Sätteri ya Astro 7 unahitaji kuhamisha ushughulikiaji wa hisabati kwenda kwenye mdastPlugins, kuweka programu nyongeza ya slug mbele ya autolinks, na kutoa mipangilio yoyote ya ziada ya markdown kutoka kwenye kitu cha kichakataji; mara tu marekebisho hayo matatu yanapofanyika, milinganyo ya tovuti yako, viungo vya urambazaji, na vipengele vya markdown maalum vitafanya kazi kama awali.