Skip to content

Add GitHub Actions CI for Markdown Linting and Manifest Integrity #198

Open

Description

@huzaifaalmesbah

Summary

This issue proposes introducing an automated GitHub Actions CI workflow to validate markdown files and verify the integrity of bin/handbook-manifest.json on every pull request and push to trunk.


Motivation

All markdown documentation in this repository is synchronized with the live Make WordPress Test Handbook.

Currently, the repository has no automated CI checks for documentation quality or synchronization readiness:

  1. Manifest Discrepancies: bin/handbook-manifest.json defines the sidebar hierarchy and URL routing on Make WordPress. When new guides are added, renamed, or moved, it is easy for contributors to forget to register them in the manifest (or leave stale entries behind).
  2. Markdown Inconsistencies: Fenced code blocks without language specifiers, malformed headings, broken relative links, and invalid HTML can slip through manual reviews.

Automating these checks in CI will give contributors and reviewers fast, automated feedback and prevent broken handbook synchronizations.


Proposed Scope of Work

1. Manifest Integrity Validator (.github/scripts/validate-manifest.mjs)

A lightweight Node.js script that verifies:

  • Every .md file in the repository (excluding README.md, .github/, etc.) is registered in bin/handbook-manifest.json.
  • Every entry in bin/handbook-manifest.json points to a valid file that exists on disk.
  • Parent-child references in the manifest point to valid existing slugs.
  • bin/handbook-manifest.json is valid JSON.

2. Markdown Linter Configuration (.markdownlint.json)

  • Add a configuration file for markdownlint-cli tailored to Make WordPress handbook conventions (e.g. allowing certain handbook callout HTML tags like <div class="callout..."> while enforcing proper heading hierarchy and fenced code block languages).

3. GitHub Actions Workflow (.github/workflows/lint-handbook.yml)

  • Run on pull_request and push to trunk.
  • Steps:
    1. Check out code and set up Node.js.
    2. Run the manifest integrity script (node .github/scripts/validate-manifest.mjs).
    3. Run markdown linting (npx markdownlint-cli "**/*.md" --ignore node_modules).

Benefits

  • Catches missing manifest registrations before PRs are merged.
  • Maintains high code block and markdown syntax consistency across all handbook pages.
  • Reduces reviewer workload by automating structural validation.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions