skills.rest
mariadb-corporation
mariadb-corporationOFFICIAL
Explore all skills by this author →
WebsiteGitHub

docs-check

Validates changed MariaDB documentation pages against CI-mirroring lint and structural checks.

28|115|Updated Jan 28, 2025
Search Tags:#documentation#lint#link checker#lychee#GitBook#codespell#ci validation
One-click install
npx skills add https://github.com/mariadb-corporation/mariadb-docs --skill docs-check-mariadb-corporation
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: docs-check
Source: https://github.com/mariadb-corporation/mariadb-docs/tree/main/.claude/skills/docs-check
Command: npx skills add https://github.com/mariadb-corporation/mariadb-docs --skill docs-check-mariadb-corporation

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires codespell, lychee.

What problem does it solve? Docs contributors often discover broken links, spelling errors, dead includes, or orphaned pages only after CI fails on their pull request. This Skill runs the same checks locally on changed files before committing, so a docs PR passes on the first push. ## Core Features & Use Cases - CI-mirroring lint: Runs codespell and lychee link-check with the exact CI flags via the canonical doc-lint.sh script, reporting PASS/FAIL/SKIPPED per check. - Structural gates: Detects dead GitBook includes, broken heading anchors, orphaned pages missing from SUMMARY.md, and gutted pages that lost most of their content. - Heuristic review: Checks frontmatter presence, GitBook block balance, link style conventions, and fact-check report paper trails for DOCS-XXXX branches. - Use Case: Before opening a PR that edits three server documentation pages, ask the Skill to validate them; it reports a broken link and an unclosed tabs block with file:line and concrete fixes. ## Quick Start Ask the assistant to run docs-check on your changed documentation files before committing to confirm they will pass CI.

Frequently Asked Questions about docs-check

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check documentation changes before opening a PR?▼

Run docs-check on your changed Markdown files before committing. It executes codespell and lychee with CI-mirroring flags plus structural checks for includes, anchors, orphans, and gutted pages, then reports PASS, FAIL, or SKIPPED per check.

How to validate GitBook links and heading anchors locally?▼

The doc-lint.sh script runs lychee for links and a history-aware fragment checker for heading anchors. The anchor gate compares against a base commit so pre-existing dead anchors do not fail unrelated work.

What tools are required to run the docs lint checks?▼

codespell and lychee are needed for spelling and link checks; install codespell via pipx. python3 and a git work tree are required for the anchor, orphan, and shrink gates. Missing tools cause a SKIPPED report, not a failure.

Why does the anchor check fail on files I did not edit?▼

The fragment gate scans the whole tree because renaming a heading breaks inbound links from untouched pages. If the findings belong to main rather than your branch, rebase onto current main so they become pre-existing at the base.

Can I acknowledge a deliberately unlisted or shrunken page?▼

Yes, add an orphan or shrink entry with a reason to .claude/hooks/doc-lint-allow.yml, which the CI gate reads. The check then reports WARN instead of FAIL, and stale entries must be removed in the same PR.

Related Skills

Explore More Software Engineering Skills→
ivvycodeivvycode
2

gitbook

Edit GitBook content in Git repositories using frontmatter and block syntax.

Official
Intermediate
ponylangponylang
218

add-linux-bootstrap-platform

Automate adding Linux distros as ponyup bootstrap-test targets across CI workflows.

Official
Advanced
ValorInvestigatorValorInvestigator

fact-check-workflow

Extract claims, gather evidence, and document corrections for journalism fact-checking.

Community
Advanced
nebinfranebinfra

neb-verify

Run Go build/vet/test, Helm lint/validate, and Git status checks before commits.

Official
Advanced