Skip to content

Introduce reusable docs workflow#27

Open
josbeir wants to merge 3 commits into5.xfrom
doc-workflows
Open

Introduce reusable docs workflow#27
josbeir wants to merge 3 commits into5.xfrom
doc-workflows

Conversation

@josbeir
Copy link
Copy Markdown

@josbeir josbeir commented Apr 2, 2026

This refactors and moves the documentation workflow from the docs repository into a reusable workflow we can adapt for our plugins too.

See cakephp/docs#8268 for a usage example.

Simple workflow usage example:

jobs:
  validate:
    uses: cakephp/.github/.github/workflows/docs-validation.yml@5.x
    with:
      docs-path: 'docs'
      enable-config-js-check: true
      enable-json-lint: true
      enable-toc-check: true
      enable-spell-check: true
      enable-markdown-lint: true
      enable-link-check: true
      linkchecker-baseline: '.github/linkchecker-baseline.json'
      tools-ref: '5.x'

Copilot AI review requested due to automatic review settings April 2, 2026 08:41
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR introduces a reusable GitHub Actions workflow for validating documentation across repositories by centralizing shared linting and link-checking tooling/configuration in this repo.

Changes:

  • Add a reusable docs-validation workflow with optional steps for TOC validation, JSON linting, markdownlint, cspell, and internal link checks.
  • Add shared Node.js validation scripts for TOC link validation and internal markdown link/anchor validation (with baseline support).
  • Add shared markdownlint and cspell configuration, including a custom markdownlint rule.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
docs-validation/markdownlint-rules/no-space-after-fence.cjs Adds a custom markdownlint rule to disallow a space between backticks and the info string.
docs-validation/cspell.json Adds a shared cspell configuration and project dictionary.
docs-validation/check-toc-links.cjs Adds a script to validate that .vitepress/toc_*.json links resolve to markdown files.
docs-validation/check-links.cjs Adds an internal markdown link/anchor checker with optional baseline support.
docs-validation/.markdownlint-cli2.jsonc Adds a shared markdownlint-cli2 configuration wiring in the custom rule.
.github/workflows/docs-validation.yml Adds the reusable workflow that pulls shared tools/configs from cakephp/.github.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants