chore: fix markdown lint coverage, write-translations command, and a deprecation - #35
Merged
Merged
Conversation
docs/architecture.md and its Chinese translation contain 8 ```mermaid fenced blocks, but @docusaurus/theme-mermaid was never installed and markdown.mermaid was never enabled. Docusaurus fell back to treating the blocks as plain code, so the architecture diagrams shipped to the site as raw mermaid source text. Install the theme, enable markdown.mermaid, and map the diagram theme to the site colour mode so diagrams do not stay light on a dark page. Verified in the browser: all 4 diagrams on /docs/architecture render as SVG in both colour modes, and neither locale's build output contains a language-mermaid block any more. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The markdownlint globs only covered README.md, CHANGELOG.md and docs/*.md. That is three top-level files: every doc under docs/**/ and the entire i18n/ tree went unchecked, so the "Markdown Lint" gate did not actually guard the documentation. CHANGELOG.md does not exist in this repository at all. Widen the globs to *.md, docs/**/*.md and i18n/**/*.md. This takes the linted set from 3 files to 49 and surfaces two MD040 violations in the operator template (en and zh), fixed here by tagging the kubectl output block as `text`. Verified with the same markdownlint-cli2 version the action pins (0.15.0): 49 files, 0 errors. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both AGENTS.md and the contributor-facing document guideline told people
to run write-translations with `--locale zh`, contradicting AGENTS.md's
own rule that `zh` is a path, not a locale key (the locale is `zh-Hans`).
The bigger problem is the missing `--` separator: `npm run
write-translations --locale zh` makes npm swallow `--locale` as its own
flag and pass a bare `zh` through as a positional argument, which
docusaurus reads as a site directory:
[ERROR] ENOENT: no such file or directory, lstat '<repo>/zh'
Correct both to `npm run write-translations -- --locale zh-Hans`, and
switch the guideline from `yarn` to npm since this repository has no
yarn.lock. Also fixes the MD034/MD040 violations that AGENTS.md picked up
now that root-level markdown is linted.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Docusaurus warned on every build, twice per run (once per locale), that the top-level siteConfig.onBrokenMarkdownLinks option is deprecated and will be removed in v4. Move it under markdown.hooks, alongside the mermaid option already in that block. Build output is now warning-free. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
5 tasks
whg517
added a commit
that referenced
this pull request
Aug 24, 2026
PR #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.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
Three small repository-hygiene fixes. Stacked on #33 — please merge that first. Until #33 lands, this PR's diff also shows the mermaid commit; it will shrink automatically once #33 is merged.
Changes
ci: lint the whole markdown tree, not just three filesThe markdownlint globs covered
README.md,CHANGELOG.mdanddocs/*.md— three top-level files. Everything underdocs/**/and the entirei18n/tree went unchecked, so the Markdown Lint gate was not actually guarding the documentation.CHANGELOG.mddoes not exist in this repository.Widened to
*.md,docs/**/*.md,i18n/**/*.md: the linted set goes from 3 files to 49. This surfaced two MD040 violations in the operator template (en + zh), fixed by tagging thekubectloutput block astext.docs: fix the broken write-translations commandAGENTS.mdanddocs/developer-manual/document-guideline.mdboth told contributors to run--locale zh, contradicting AGENTS.md's own rule thatzhis a path and the locale key iszh-Hans.More importantly the
--separator was missing, so the documented command fails outright — npm swallows--localeas its own flag and passes a barezhthrough as a positional argument, which docusaurus reads as a site directory:Corrected to
npm run write-translations -- --locale zh-Hans. The guideline also saidyarn; this repository has noyarn.lock.chore: migrate onBrokenMarkdownLinks off the deprecated locationDocusaurus warned on every build, twice per run (once per locale), that top-level
siteConfig.onBrokenMarkdownLinksis deprecated and will be removed in v4. Moved undermarkdown.hooks.Testing
npm run buildpasses (both locales), now warning-freenpx tsc --noEmitpassesmarkdownlint-cli2@0.15.0, as permarkdownlint-cli2-action@v18.0.0): 49 files, 0 errors🤖 Generated with Claude Code