Add docs quality gates for Markdown changes

.github/workflows/docs_quality.yml

@@ -0,0 +1,58 @@
+name: Docs Quality
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md"
+      - ".github/workflows/docs_quality.yml"
+      - ".markdownlint-cli2.yaml"
+      - "lychee.toml"
+  push:
+    branches:
+      - main
+    paths:
+      - "**/*.md"
+      - ".github/workflows/docs_quality.yml"
+      - ".markdownlint-cli2.yaml"
+      - "lychee.toml"
+
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  docs-quality:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Collect changed Markdown files
+        id: changed-markdown
+        uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62 # v47
+        with:
+          files: |
+            **/*.md
+
+      - name: Lint changed Markdown files
+        if: steps.changed-markdown.outputs.any_changed == 'true'
+        uses: DavidAnson/markdownlint-cli2-action@v23
+        with:
+          config: .markdownlint-cli2.yaml
+          globs: ${{ steps.changed-markdown.outputs.all_changed_files }}
+          separator: " "
+
+      - name: Check changed Markdown links
+        if: steps.changed-markdown.outputs.any_changed == 'true'
+        uses: lycheeverse/lychee-action@v2.7.0
+        with:
+          args: >-
+            --config ./lychee.toml
+            ${{ steps.changed-markdown.outputs.all_changed_files }}

.gitignore

@@ -2,5 +2,6 @@ node_modules/
 __pycache__/
 .vscode/
 .idea/
+.lycheecache
 
 .DS_Store

.markdownlint-cli2.yaml

@@ -0,0 +1,10 @@
+---
+config:
+  default: true
+  first-line-heading: false
+  line-length: false
+  no-duplicate-heading:
+    siblings_only: true
+  no-inline-html: false
+noInlineConfig: true
+noProgress: true

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thanks for helping improve the Hugging Face Hub docs.
+
+## Docs workflow
+
+1. Edit the relevant Markdown files.
+2. Open a pull request.
+3. Review the preview artifacts from the existing docs build workflows.
+4. Make sure the docs quality checks pass for the Markdown files you changed.
+
+## Preview docs locally
+
+Install the doc builder first:
+
+```bash
+pip install hf-doc-builder
+pip install black watchdog
+```
+
+Preview the main Hub docs locally:
+
+```bash
+doc-builder preview hub {YOUR_PATH}/hub-docs/docs/hub/ --not_python_module
+```
+
+This repository also contains dedicated docs trees for `docs/inference-providers/`, `docs/sagemaker/`, and `docs/xet/`, each with their own preview workflow in `.github/workflows/`.
+
+## Run docs quality checks locally
+
+The repo-wide docs quality workflow lints changed Markdown files and validates their external links.
+
+Lint the Markdown files you changed with `markdownlint-cli2`:
+
+```bash
+npx markdownlint-cli2 --config .markdownlint-cli2.yaml README.md docs/hub/index.md
+```
+
+Install `lychee` using the method that matches your platform from the official docs, then check the same files for broken links:
+
+```bash
+lychee --config ./lychee.toml README.md docs/hub/index.md
+```
+
+Replace the example paths with the Markdown files from your branch.

README.md

@@ -5,26 +5,15 @@ This repository regroups documentation and information that is hosted on the Hug
 You can access the Hugging Face Hub documentation in the `docs` folder at [hf.co/docs/hub](https://hf.co/docs/hub).
 
 For some related components, check out the [Hugging Face Hub JS repository](https://github.com/huggingface/huggingface.js)
+
 - Utilities to interact with the Hub: [huggingface/huggingface.js/packages/hub](https://github.com/huggingface/huggingface.js/tree/main/packages/hub)
 - Hub Inference, powered by our Inference Providers: [huggingface/huggingface.js/packages/inference](https://github.com/huggingface/huggingface.js/tree/main/packages/inference)
 - Hub Tasks (as visible on the page [hf.co/tasks](https://hf.co/tasks)):  [huggingface/huggingface.js/packages/tasks](https://github.com/huggingface/huggingface.js/tree/main/packages/tasks)
 
-### How to contribute to the docs
+## How to contribute to the docs
 
 Just add/edit the Markdown files, commit them, and create a PR.
 Then the CI bot will build the preview page and provide a url for you to look at the result!
 
 For simple edits, you don't need a local build environment.
-
-### Previewing locally
-
-```bash
-# install doc-builder (if not done already)
-pip install hf-doc-builder
-
-# you may also need to install some extra dependencies
-pip install black watchdog
-
-# run `doc-builder preview` cmd
-doc-builder preview hub {YOUR_PATH}/hub-docs/docs/hub/ --not_python_module
-```
+For local preview instructions and the new Markdown/link quality checks, see [CONTRIBUTING.md](CONTRIBUTING.md).

lychee.toml

@@ -0,0 +1,6 @@
+accept = ["200..=204", "429"]
+cache = true
+exclude_all_private = true
+max_retries = 2
+retry_wait_time = 2
+timeout = 20