chore: add Markdown format check - #2736
Conversation
Signed-off-by: WenyXu <wenymedia@gmail.com>
There was a problem hiding this comment.
Pull request overview
This PR adds pinned, local Markdown tooling (markdownlint + Prettier) and new pnpm scripts so contributors can lint and format Markdown consistently within the docs repository.
Changes:
- Add
markdownlint-cli@0.42.0andprettier@3.5.3as pinned devDependencies. - Introduce
pnpmscripts for Markdown linting and formatting (lint:md,format:md,format:md:check). - Add
.markdownlintignoreto exclude generated/output directories from Markdown linting.
Reviewed changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
pnpm-lock.yaml |
Locks the newly introduced Markdown tooling dependencies and their transitive dependency graph. |
package.json |
Adds pinned devDependencies and exposes new pnpm scripts for linting/formatting Markdown. |
.markdownlintignore |
Excludes node_modules/ and generated build outputs from markdownlint runs. |
Files not reviewed (1)
- pnpm-lock.yaml: Generated file
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 39827a8ca6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Deploying greptime-docs with
|
| Latest commit: |
c0e875b
|
| Status: | ⚡️ Build in progress... |
Signed-off-by: WenyXu <wenymedia@gmail.com>
WenyXu
changed the title
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c0e875bd27
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| } | ||
|
|
||
| const paths = providedPaths.filter(path => path !== '--') | ||
| const base = execFileSync('git', ['merge-base', 'HEAD', 'origin/main'], { encoding: 'utf8' }).trim() |
There was a problem hiding this comment.
For pull requests targeting dev, the build job in .github/workflows/node-build.yml still invokes this script, but the hard-coded origin/main merge base makes changedPaths include unrelated changes accumulated on dev since it diverged from main. If any of those pre-existing Markdown files are not Prettier-compliant, every otherwise unrelated PR into dev fails this check; derive the baseline from the pull request's base branch or SHA instead.
Useful? React with 👍 / 👎.
| } | ||
|
|
||
| const paths = providedPaths.filter(path => path !== '--') | ||
| const base = execFileSync('git', ['merge-base', 'HEAD', 'origin/main'], { encoding: 'utf8' }).trim() |
There was a problem hiding this comment.
When a contributor supplies explicit paths from a source archive, a clone whose primary remote is not named origin, or any checkout without origin/main, the command fails here before it reaches paths.length > 0. Explicit inputs do not need a merge base, so resolve the Git baseline only in the no-input branch; otherwise even node scripts/format-markdown.mjs --check AGENTS.md cannot perform the requested check.
Useful? React with 👍 / 👎.
|
|
||
| const paths = providedPaths.filter(path => path !== '--') | ||
| const base = execFileSync('git', ['merge-base', 'HEAD', 'origin/main'], { encoding: 'utf8' }).trim() | ||
| const changedPaths = execFileSync('git', ['diff', '--name-only', '--diff-filter=ACMR', base], { |
There was a problem hiding this comment.
When a contributor creates a new documentation page and runs the bare formatting command before staging it, git diff --name-only <base> omits that untracked file, so the script either reports that there is nothing to format or silently checks only older files. The page is detected only after it is added or committed, commonly turning the subsequent CI run into the first formatting failure; combine this result with untracked, non-ignored Markdown paths.
Useful? React with 👍 / 👎.
| } | ||
|
|
||
| const prettier = fileURLToPath(new URL('../node_modules/prettier/bin/prettier.cjs', import.meta.url)) | ||
| const result = spawnSync(process.execPath, [prettier, mode, ...inputs], { stdio: 'inherit' }) |
There was a problem hiding this comment.
When a contributor follows the usage text and runs pnpm format:md -- i18n/zh or passes the repository root, the directory is forwarded unchanged. Prettier's CLI help defines operands as file/dir/glob and lists JSON, YAML, TypeScript, and other parsers, so --write recursively rewrites those supported files alongside Markdown—including the localized navigation JSON under i18n/zh; expand or filter directory inputs to .md and .mdx before invoking Prettier.
AGENTS.md reference: AGENTS.md:L44-L45
Useful? React with 👍 / 👎.
What changed
Adds pinned local Prettier tooling and package scripts so contributors can format changed Markdown and MDX files reproducibly:
pnpm format:mdpnpm format:md:checkBy default, the scripts target Markdown and MDX files changed from
origin/main; callers can append explicit paths for narrower checks. The Node.js CI build job runspnpm format:md:checkwith full Git history available for that comparison.Scope
Verification
node scripts/format-markdown.mjs --checknode scripts/format-markdown.mjs --check -- docs/user-guide/deployments-administration/monitoring/events i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/monitoring/eventsnpm exec --yes --package=pnpm@9.15.4 -- pnpm format:md:checknpm exec --yes --package=pnpm@9.15.4 -- pnpm format:md:check -- docs/user-guide/deployments-administration/monitoring/events i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/monitoring/eventsprettier --check .github/workflows/node-build.yml scripts/format-markdown.mjs package.jsongit diff --checkChecklist