fix: remove duplicated markdown and themes config keys (main is red) - #36
Merged
Merged
Conversation
PR zncdatadev#35 was stacked on zncdatadev#33, so it carried zncdatadev#33's mermaid commit. zncdatadev#35 merged first, then zncdatadev#33 merged its own copy of the same change, leaving docusaurus.config.ts with two `markdown` keys and two `themes` keys. This broke main two ways: docusaurus.config.ts(34,3): error TS1117: An object literal cannot have multiple properties with the same name. TypeScript Lint has failed on main since fa4beab, and because the deploy job needs that check, the site has not deployed since c8a5e91. Functionally the duplicate `markdown` key also silently reverted the deprecation fix: the second literal wins, and it has no `hooks` member, so markdown.hooks.onBrokenMarkdownLinks was dropped and the v4 deprecation warning came back. Drop the duplicate block, keeping the one that carries hooks. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
5 tasks
whg517
added a commit
that referenced
this pull request
Aug 24, 2026
* chore: pin markdownlint and add lint/verify scripts Markdown lint ran through the GitHub action, which pins markdownlint-cli2 internally. Nothing told a contributor which version that was, so running `npx markdownlint-cli2` locally pulled the latest instead: 0.23 enforces MD060 (table-column-style) and reports ~46 violations on tables CI considers clean. That is a trap, and it already cost time in this repo. Move the version into package.json as an exact devDependency, matching what the action was already resolving, and put the globs in an npm script so local runs and CI cannot disagree: npm run lint:md markdownlint over *.md, docs/**, i18n/** npm run lint lint:md + typecheck npm run verify lint + build (mirrors CI end to end) Pinning to the version currently in effect keeps this a pure guardrail change with no new violations. Upgrading later means either fixing the MD060 tables or disabling that rule, and should be its own PR. Verified: `npm run verify` exits 0, linting 52 files with 0 errors. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * ci: split lint, build and deploy into separate jobs The workflow had three problems beyond naming. `npm install` with a committed lockfile can resolve differently from what the lockfile pins, so CI was not reproducible. Switched to `npm ci`, and added setup-node's npm cache while there. The build ran inside the deploy job, so on a pull request the check that actually verified the build was reported as "Deploy to GitHub Pages" — misleading, since nothing was being deployed. Build is now its own job, scoped to pull requests; deploy is scoped to main pushes and still builds what it publishes. No status check was required by branch protection, so renaming is safe. That deploy job also checked out shallow, while docusaurus is configured with showLastUpdateAuthor and showLastUpdateTime. Those read git history, so with depth 1 every page reported the same last-updated date. Both jobs that build now use fetch-depth: 0. Also scope the push trigger to main so forks stop running the full workflow on every branch push, cancel superseded pull request runs (but never an in-flight deploy), and drop the default token down to contents: read except in deploy. Lint now runs `npm run lint`, the same command contributors run locally. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs: rewrite AGENTS.md for agent onboarding, symlink CLAUDE.md AGENTS.md described the repository accurately enough but left out everything an agent actually needs to avoid breaking things, and a few details were wrong (typecheck is `tsc`, not `npx tsc --noEmit`). Add what was missing: - A single `npm run verify` as the definition of done, with the underlying commands spelled out - The four traps this repository has already produced: unpinned markdownlint reporting rules CI does not enforce, MD013's non-strict exemption making "max 200 characters" not literal, byte-vs-character counting inflating CJK line lengths, and mermaid being unverifiable from build output because it renders client-side - Content state: 13 of 24 pages are placeholders, with the command to list them, so an agent does not mistake a stub for a real page - The en/zh mirroring invariant and how to check it, since Docusaurus falls back to English and the build stays green when it is violated - The Chinese-prose-in-the-English-tree inconsistency, flagged as something not to copy - Which sidebar categories are autogenerated and which need editing - A do-not-stack-PRs rule, with the #33/#35/#36 breakage as the reason Also correct the "max 200 characters" rule, refresh the CI table for the new job layout, and point the PR template at `npm run verify`. CLAUDE.md is a symlink to AGENTS.md (git mode 120000, not a copy) so both conventions resolve to one file. Note for Windows contributors: with core.symlinks disabled git materialises it as a text file containing the target path. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
main is currently failing and the site has not deployed since
c8a5e91. This restores it.#35 was stacked on #33, so it carried #33's mermaid commit. #35 merged first, then #33 merged its own copy of the same change — leaving
docusaurus.config.tswith twomarkdownkeys and twothemeskeys. My fault for arranging the PRs that way: I made correctness depend on merge order, which was fragile.Impact
1. TypeScript Lint fails on main
Failing since
fa4beab(#33 merge). Thedeployjob hasneeds: [markdown-lint, typescript-lint], so GitHub Pages has not been updated sincec8a5e91— the mermaid fix from #33 is not live yet.2. The deprecation fix from #35 was silently reverted
Duplicate object keys mean the last literal wins. The second
markdownblock has nohooksmember, somarkdown.hooks.onBrokenMarkdownLinkswas dropped and the Docusaurus v4 deprecation warning came back.mermaid: truesurvived only because both copies happened to set it.Changes
markdownblock and the duplicatedthemesline, keeping the copy that carrieshooksTesting
npx tsc --noEmitpasses (was 2 errors)npm run buildpasses (both locales), warning-free againmarkdown,themes,onBrokenMarkdownLinkseach appear exactly oncelanguage-mermaidblocks left in either locale's outputproject-statuspage from docs(developer-manual): add project status page #34 still generated🤖 Generated with Claude Code