diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml new file mode 100644 index 000000000..c7c4bfc76 --- /dev/null +++ b/.github/workflows/docs-quality.yml @@ -0,0 +1,38 @@ +name: Docs Quality Checks + +on: + pull_request: + paths: + - "**/*.md" + +jobs: + docs_quality: + name: Lint Markdown & Check Links + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + + + # MARKDOWNLINT + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 18 + + - name: Install markdownlint-cli + run: npm install -g markdownlint-cli + + - name: Run markdownlint + run: markdownlint "**/*.md" --config .markdownlint.json + + + # LYCHEE LINK CHECK + - name: Install lychee + uses: lycheeverse/lychee-action@v1.7.0 + with: + args: --config lychee.toml ./ + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 000000000..e8e8055c4 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,9 @@ +{ + "default": true, + "MD013": false, + "MD033": false, + "MD041": false, + "MD036": false, + "MD029": { "style": "ordered" }, + "line-length": false +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..dd05826c3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,40 @@ +Documentation Quality Checks +---------------------------- + +To maintain consistent, reliable documentation, we will now validate markdown files with these two tools: + +- **markdownlint:** this ensures consistent Markdown formatting + +- **lychee:** checks for broken external links + +The system will automatically run these checks in CI on every pull request.\ +You can also run them locally before submitting your PR. + +### **1\. Install markdownlint** + +`npm install -g markdownlint-cli` + +Run it: + +`markdownlint "**/*.md" --config .markdownlint.json` + +### **2\. Install and run lychee (link checker)** + +#### Install (Rust-based) + +`cargo install lychee-cli` + +#### Run it: + +`lychee --config lychee.toml ./` + +### **3\. Before opening a PR** + +Run: + +`markdownlint "**/*.md" +lychee ./` + +Fix any issues shown in the terminal. + +This ensures your PR passes CI and keeps our docs consistent. diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 000000000..96c44206a --- /dev/null +++ b/lychee.toml @@ -0,0 +1,17 @@ +# Ignore temporary or unstable domains +exclude = [ + "localhost", + "127.0.0.1" +] + +# Timeouts +timeout = 10 + +# Check all Markdown files +include = [ + "**/*.md" +] + +# Only treat actual broken links as failures +max-concurrency = 20 +verbosity = "error"