From 37158391a9f8ffb384039618ff9ee7733bfc74e6 Mon Sep 17 00:00:00 2001 From: fabthebest Date: Thu, 23 Apr 2026 15:41:37 -0400 Subject: [PATCH 1/2] ci: add docs quality gates for markdown changes --- .github/workflows/docs_quality.yml | 58 ++++++++++++++++++++++++++++++ .gitignore | 1 + .markdownlint-cli2.yaml | 10 ++++++ CONTRIBUTING.md | 45 +++++++++++++++++++++++ README.md | 17 ++------- lychee.toml | 6 ++++ 6 files changed, 123 insertions(+), 14 deletions(-) create mode 100644 .github/workflows/docs_quality.yml create mode 100644 .markdownlint-cli2.yaml create mode 100644 CONTRIBUTING.md create mode 100644 lychee.toml diff --git a/.github/workflows/docs_quality.yml b/.github/workflows/docs_quality.yml new file mode 100644 index 0000000000..6683e7cb03 --- /dev/null +++ b/.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 }} diff --git a/.gitignore b/.gitignore index b2ed9d557e..5aae0c56e2 100644 --- a/.gitignore +++ b/.gitignore @@ -2,5 +2,6 @@ node_modules/ __pycache__/ .vscode/ .idea/ +.lycheecache .DS_Store diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000000..0d16ed3a14 --- /dev/null +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..4ab781aa15 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index d92027cbbe..8dde651362 100644 --- a/README.md +++ b/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). diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 0000000000..3c3eb34cd4 --- /dev/null +++ b/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 From 99edee500076aef7a7931abae03bc0ddaab973ed Mon Sep 17 00:00:00 2001 From: fabthebest Date: Thu, 23 Apr 2026 16:35:12 -0400 Subject: [PATCH 2/2] ci: pin docs quality actions --- .github/workflows/docs_quality.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs_quality.yml b/.github/workflows/docs_quality.yml index 6683e7cb03..0473217a6a 100644 --- a/.github/workflows/docs_quality.yml +++ b/.github/workflows/docs_quality.yml @@ -43,7 +43,7 @@ jobs: - name: Lint changed Markdown files if: steps.changed-markdown.outputs.any_changed == 'true' - uses: DavidAnson/markdownlint-cli2-action@v23 + uses: DavidAnson/markdownlint-cli2-action@ce4853d43830c74c1753b39f3cf40f71c2031eb9 # v23 with: config: .markdownlint-cli2.yaml globs: ${{ steps.changed-markdown.outputs.all_changed_files }} @@ -51,8 +51,9 @@ jobs: - name: Check changed Markdown links if: steps.changed-markdown.outputs.any_changed == 'true' - uses: lycheeverse/lychee-action@v2.7.0 + uses: lycheeverse/lychee-action@a8c4c7cb88f0c7386610c35eb25108e448569cb0 # v2.7.0 with: + failIfEmpty: false args: >- --config ./lychee.toml ${{ steps.changed-markdown.outputs.all_changed_files }}