infra: follow-up actions after caffeinelabs/motoko#6132 merges

[marc0olo]

Context

caffeinelabs/motoko#6132 (docs/transform-free-sync) restructures doc/md/ to be Starlight-ready so that an rsync of that directory produces a correct, buildable Motoko section in developer-docs with no (or minimal) post-processing.

This issue tracks the developer-docs changes needed once that PR merges and a new release tag is cut.

Do not start this work until #6132 merges. The weekly sync-motoko.yml workflow will open an automated bump PR when a new release is tagged. Review and merge that PR first, then address the items below.

Action items

1. Add BNF syntax highlighting

doc/md/reference/language-manual.md has 30 BNF grammar blocks that currently fall back to plaintext and emit a build warning.

caffeinelabs/motoko#6132 added doc/site/syntaxes/bnf.tmLanguage.json and registered it in doc/site/ec.config.mjs. Copy both changes to developer-docs:

• Copy doc/site/syntaxes/bnf.tmLanguage.json from the motoko repo to syntaxes/bnf.tmLanguage.json here
• Add to ec.config.mjs:

  const bnf = {
    ...JSON.parse(fs.readFileSync("./syntaxes/bnf.tmLanguage.json", "utf-8")),
    name: "bnf",
  };
  // then add bnf to langs: [motoko, candid, bnf]

• Verify: npm run build should no longer emit WARN [astro-expressive-code] language "bnf" lines

2. Test autogenerate and simplify sidebar-motoko.mjs

sidebar-motoko.mjs has a TRANSITIONAL comment explaining it exists because the upstream source did not have Starlight sidebar.label / sidebar.order frontmatter on subdirectory index files. #6132 adds that metadata.

Note: the motoko doc/site/ preview (which loads content via a symlink) found that docsLoader() + symlink does not recognise index.md files as group entry points — they appear as orphan child pages. Developer-docs loads content via a direct rsync copy, not a symlink, so this limitation may not apply here. Test with the bump PR's content to confirm.

After the bump PR merges:

• Try replacing sidebar-motoko.mjs with the one-liner:

  export const motokoSidebar = {
    label: "Motoko",
    collapsed: true,
    autogenerate: { directory: "languages/motoko" },
  };

• Run npm run dev and verify the sidebar matches the current explicit structure (correct labels, ordering, Fundamentals subsections collapsed by default, base-core-migration hidden)
• If autogenerate produces the correct result: delete sidebar-motoko.mjs, update the import in sidebar.mjs, done
• If it does not: document why (specific missing frontmatter) and leave the explicit list, updating it for any new pages added in #6132

3. Evaluate postprocessor simplification

scripts/postprocess-motoko.mjs currently does:

• External URL rewrites (internetcomputer.org/docs/* and docs.motoko.org/* → internal paths)
• ./core/<Module>.md → https://mops.one/core/docs/<Module>
• Aside syntax normalization (:::info → :::note, :::warn → :::caution)
• Em-dash replacement (— → : )
• Bare numeric-prefix link stripping
• <motokoExamples> placeholder insertion (rewrites old ../examples/ paths)

Review the synced content diff from the bump PR and identify which of these are now handled upstream in doc/md/. Remove postprocessor steps that are redundant. Keep only what is still genuinely needed.

Key changes in #6132 that make postprocessor steps redundant:

• §3 (file-embed paths): upstream now uses <motokoExamples> directly, so the postprocessor insertion step becomes a no-op. remark-include-file.mjs still resolves <motokoExamples> at build time — that is unaffected.
• §4 (delete _category_.yml): the files no longer exist in upstream, so removal is a no-op
• §5 + §6 (numeric prefix removal + link updates): links no longer have numeric prefixes in upstream
• §9 (aside syntax): mostly handled upstream; Changelog entries may still have old syntax

Em-dash replacement is likely still needed for pre-existing em-dashes in Changelog.md entries that were not fixed in #6132.

4. Remove the planning doc

.docs-plan/motoko-repo-sync-proposal.md was created in PR #261 to track the upstream roadmap. Once #6132 merges and this issue is resolved, delete it (or confirm it was already removed in the bump PR).

Sync recommendation

sync from caffeinelabs/motoko doc/md