From 1e8f51b01852807ea1ddd27ed8ef2fe2bb20c9a9 Mon Sep 17 00:00:00 2001 From: bakerboy448 <55419169+bakerboy448@users.noreply.github.com> Date: Mon, 8 Jun 2026 23:18:35 -0500 Subject: [PATCH 1/7] chore(ci): add Dependabot + cancel-in-progress on workflows - .github/dependabot.yml: weekly version-updates for github-actions and pip ecosystems, grouped mkdocs* pip updates. - .github/workflows/build.yml + deploy.yml: add cancel-in-progress on concurrency groups so newer pushes on a branch don't queue behind stale runs. No runner changes (stays ubuntu-latest); no python version changes (stays 3.14 per existing config). --- .github/dependabot.yml | 25 +++++++++++++++++++++++++ .github/workflows/build.yml | 1 + .github/workflows/deploy.yml | 1 + 3 files changed, 27 insertions(+) create mode 100644 .github/dependabot.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..ab6dc9d --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,25 @@ +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly + day: monday + time: "04:00" + timezone: America/Chicago + labels: ["dependencies", "github-actions"] + open-pull-requests-limit: 5 + + - package-ecosystem: pip + directory: / + schedule: + interval: weekly + day: monday + time: "04:00" + timezone: America/Chicago + labels: ["dependencies", "python"] + open-pull-requests-limit: 5 + groups: + mkdocs: + patterns: + - mkdocs* diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 19bbb6e..c181204 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -10,6 +10,7 @@ jobs: runs-on: ubuntu-latest concurrency: group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true steps: - uses: actions/checkout@v6 - uses: actions/setup-python@v6 diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index bbbe9f9..9eb094f 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -12,6 +12,7 @@ jobs: contents: write concurrency: group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true steps: - name: Clone repository uses: actions/checkout@v6 From d0b1f1d3a69a3b9372749dcd1ba30eb847a9c784 Mon Sep 17 00:00:00 2001 From: bakerboy448 <55419169+bakerboy448@users.noreply.github.com> Date: Mon, 8 Jun 2026 23:21:17 -0500 Subject: [PATCH 2/7] chore(ci): add pull_request trigger + minimal permissions to build.yml - pull_request trigger ensures PRs targeting main get the strict-build check (previously only non-main pushes ran build; main pushes are covered by deploy.yml's identical mkdocs build --strict). - permissions: contents: read at workflow level (defense-in-depth; build doesn't write anywhere). --- .github/workflows/build.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index c181204..8b8a2fd 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -4,6 +4,12 @@ on: push: branches-ignore: - main + pull_request: + branches: + - main + +permissions: + contents: read jobs: build: From e1276e41db97b940877e4631c7aeb72c56980ea9 Mon Sep 17 00:00:00 2001 From: bakerboy448 <55419169+bakerboy448@users.noreply.github.com> Date: Mon, 8 Jun 2026 23:22:45 -0500 Subject: [PATCH 3/7] docs: add CONTRIBUTING.md Per GitHub Open Source Guide recommendations: - ways to contribute (typos, integrations, diagrams, gaps) - issue reporting flow (docs vs. application bug separation) - local development (mkdocs serve) - strict build check before PR - PR submission steps (fork + branch + conventional commits) - style notes (sentence-case headings, fenced code blocks, relative links) - communication channel (Notifiarr Discord) --- CONTRIBUTING.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..39282ef --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,84 @@ +# Contributing to Notifiarr Wiki + +Thanks for helping improve the Notifiarr Wiki. This guide covers how to report issues, set up your local environment, and submit changes. + +## Ways to contribute + +- Fix typos, broken links, or unclear wording in existing pages. +- Add documentation for new Notifiarr features or integrations. +- Improve diagrams, examples, or screenshots. +- Report content gaps or technical errors via the issue tracker. + +If you're new to open source, look for issues labeled `good first issue`. + +## Reporting issues + +Open an issue on this repository describing: + +- What page or section the problem affects (link or path). +- What you expected the docs to say. +- What the docs actually say (or where they're missing). +- Optionally: a suggested fix. + +For Notifiarr application bugs (not docs bugs), please file in the [Notifiarr application repository](https://github.com/Notifiarr/notifiarr/issues) instead. + +## Local development + +The wiki is built with [MkDocs](https://www.mkdocs.org/) + Material theme. You need Python 3.12+. + +```bash +git clone https://github.com/Notifiarr/mkdocs-wiki.git +cd mkdocs-wiki +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +mkdocs serve +``` + +Open . Edits to `docs/` reload automatically. + +Before opening a PR, run: + +```bash +mkdocs build --strict +``` + +The `--strict` flag fails on any warning (broken internal links, missing nav entries, etc.) and matches what CI runs. + +## Submitting changes + +1. Fork the repository and create a feature branch from `main`: + + ```bash + git checkout -b docs/short-description + ``` + +2. Make your edits. Keep each PR focused on one logical change. + +3. Commit with a descriptive message. Conventional Commits format is appreciated but not required: + + ```text + docs(integrations): clarify Plex token scoping + chore(ci): bump setup-python to v6 + fix(nav): remove dead link from getting-started + ``` + +4. Push your branch to your fork and open a pull request against `Notifiarr/mkdocs-wiki:main`. + +5. CI will run `mkdocs build --strict` against your PR. Address any warnings before requesting review. + +## Style notes + +- Use sentence case for headings (`## Getting started`, not `## Getting Started`) unless referring to a proper noun. +- Use fenced code blocks with a language tag for syntax highlighting (`` ```bash ``, `` ```yaml ``). +- Prefer relative links between docs pages (`[setup](../setup.md)`) so the strict build catches breakage. +- Screenshots go in `docs/images/` with descriptive filenames. + +## Communication + +- General questions about Notifiarr: the [Notifiarr Discord](https://notifiarr.com/discord). +- Wiki-specific questions: comment on the relevant issue or PR. + +## License + +By contributing, you agree your contributions are licensed under the same license as this repository. From 3cd092170ce5c23d06f88855816c0020ec7287bc Mon Sep 17 00:00:00 2001 From: bakerboy448 <55419169+bakerboy448@users.noreply.github.com> Date: Mon, 8 Jun 2026 23:25:40 -0500 Subject: [PATCH 4/7] ci(precommit): add markdownlint + link-check + cspell + pre-commit CI Mirrors the tooling we run on bakerflix-infra-docs + servarr-wiki for catching common doc regressions BEFORE merge: - .pre-commit-config.yaml: trailing-whitespace, end-of-file-fixer, check-yaml, mixed-line-ending (lf), markdownlint (autofix on save), markdown-link-check, cspell. - .markdownlint.yaml: relaxed for MkDocs Material (inline HTML allowed, bare URLs allowed, no line-length cap on prose). - .markdown-link-check.json: skip localhost/example.com, retry on 429, accept 401/403 (login-gated pages are "alive"). - .cspell.json: project word list with the *arr stack + media-server proper nouns. - .github/workflows/precommit.yml: runs pre-commit on pull_request and non-main pushes (ubuntu-latest, python 3.12, node 22). CI runs on ubuntu-latest (public-runner consistent with the rest of this repo). All hooks have pinned revs so updates are explicit. --- .cspell.json | 41 +++++++++++++++++++++++++++++++++ .github/workflows/precommit.yml | 29 +++++++++++++++++++++++ .markdown-link-check.json | 21 +++++++++++++++++ .markdownlint.yaml | 23 ++++++++++++++++++ .pre-commit-config.yaml | 33 ++++++++++++++++++++++++++ 5 files changed, 147 insertions(+) create mode 100644 .cspell.json create mode 100644 .github/workflows/precommit.yml create mode 100644 .markdown-link-check.json create mode 100644 .markdownlint.yaml create mode 100644 .pre-commit-config.yaml diff --git a/.cspell.json b/.cspell.json new file mode 100644 index 0000000..499a8da --- /dev/null +++ b/.cspell.json @@ -0,0 +1,41 @@ +{ + "version": "0.2", + "language": "en", + "ignorePaths": [ + ".git/**", + "node_modules/**", + "site/**", + ".venv/**", + "*.json", + "*.lock", + "*.svg", + "*.png", + "*.jpg" + ], + "dictionaries": ["en_US", "softwareTerms", "filetypes", "node", "html", "css", "markdown"], + "words": [ + "Notifiarr", + "Sonarr", + "Radarr", + "Lidarr", + "Readarr", + "Prowlarr", + "Bazarr", + "Tautulli", + "Overseerr", + "Jellyseerr", + "qBittorrent", + "rTorrent", + "Deluge", + "Plex", + "Jellyfin", + "Emby", + "Mkdocs", + "mkdocs", + "Webhook", + "webhooks", + "Telegraf", + "Plexpass" + ], + "allowCompoundWords": true +} diff --git a/.github/workflows/precommit.yml b/.github/workflows/precommit.yml new file mode 100644 index 0000000..acae33c --- /dev/null +++ b/.github/workflows/precommit.yml @@ -0,0 +1,29 @@ +name: Pre-commit + +on: + pull_request: + branches: + - main + push: + branches-ignore: + - main + +permissions: + contents: read + +concurrency: + group: precommit-${{ github.ref }} + cancel-in-progress: true + +jobs: + precommit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - uses: actions/setup-node@v4 + with: + node-version: "22" + - uses: pre-commit/action@v3.0.1 diff --git a/.markdown-link-check.json b/.markdown-link-check.json new file mode 100644 index 0000000..d219115 --- /dev/null +++ b/.markdown-link-check.json @@ -0,0 +1,21 @@ +{ + "ignorePatterns": [ + { "pattern": "^http://127\\.0\\.0\\.1" }, + { "pattern": "^http://localhost" }, + { "pattern": "^https?://example\\." } + ], + "replacementPatterns": [ + { "pattern": "^/", "replacement": "{{BASEURL}}/" } + ], + "httpHeaders": [ + { + "urls": ["https://github.com", "https://raw.githubusercontent.com"], + "headers": { "Accept": "text/html", "User-Agent": "Mozilla/5.0 (compatible; markdown-link-check)" } + } + ], + "timeout": "10s", + "retryOn429": true, + "retryCount": 3, + "fallbackRetryDelay": "30s", + "aliveStatusCodes": [200, 206, 301, 302, 304, 308, 401, 403] +} diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..ba9cf7e --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,23 @@ +# markdownlint config — see https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md +default: true + +# MkDocs Material uses content tabs + admonitions that look like HTML to +# markdownlint. Trust the strict mkdocs build to catch true breakage. +MD033: false # inline HTML allowed (mermaid blocks, admonition raw HTML) + +# Heading siblings on the same level often differ in case (proper nouns). +MD024: + siblings_only: true + +# MkDocs Material rewrites bare links; allow them. +MD034: false # bare URLs + +# Material themes encourage 4-space indent under nested list items. +MD007: + indent: 4 + +# Line length: don't enforce — wiki paragraphs are long-form prose. +MD013: false + +# Allow trailing punctuation in headings. +MD026: false diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..da75a15 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,33 @@ +default_install_hook_types: [pre-commit, pre-push] +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v6.0.0 + hooks: + - id: trailing-whitespace + exclude: ^docs/.*\.md$ + - id: end-of-file-fixer + - id: check-yaml + - id: check-merge-conflict + - id: mixed-line-ending + args: ['--fix=lf'] + + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.42.0 + hooks: + - id: markdownlint + args: ['--config', '.markdownlint.yaml', '--ignore', 'site/', '--ignore', '.venv/'] + + - repo: https://github.com/tcort/markdown-link-check + rev: v3.13.6 + hooks: + - id: markdown-link-check + args: ['--quiet', '--config', '.markdown-link-check.json'] + exclude: ^(site/|\.venv/) + + - repo: https://github.com/streetsidesoftware/cspell-cli + rev: v8.17.3 + hooks: + - id: cspell + args: ['--no-progress', '--no-summary', '--quiet', '--gitignore', '--config', '.cspell.json'] + files: \.(md|markdown)$ + exclude: ^(site/|\.venv/) From 71369c8ec854540d0c3fa44fb2e015e23c7820c1 Mon Sep 17 00:00:00 2001 From: bakerboy448 <55419169+bakerboy448@users.noreply.github.com> Date: Mon, 8 Jun 2026 23:35:45 -0500 Subject: [PATCH 5/7] ci(precommit): only check changed files (not legacy content) The wiki has hundreds of existing markdown files; running pre-commit --all-files against them in CI surfaces dozens of pre-existing violations (trailing whitespace, mixed line endings, bare URLs that markdownlint flags, dead external links, unknown words for cspell). Adding pre-commit to a long-lived repo shouldn't fail on legacy violations. This restricts CI to files changed in the PR / push range: pre-commit run --from-ref --to-ref Maintainers can clean up the backlog with a follow-up `pre-commit run --all-files` sweep at their pace. --- .github/workflows/precommit.yml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/.github/workflows/precommit.yml b/.github/workflows/precommit.yml index acae33c..d0596c9 100644 --- a/.github/workflows/precommit.yml +++ b/.github/workflows/precommit.yml @@ -20,10 +20,29 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + with: + # Need full history so pre-commit can diff against the PR base. + fetch-depth: 0 - uses: actions/setup-python@v5 with: python-version: "3.12" - uses: actions/setup-node@v4 with: node-version: "22" + # Only check files changed in the PR / push. Adding pre-commit to a + # repo with existing content shouldn't fail on legacy violations — + # only new/modified files get linted. Maintainers can clean up the + # backlog with `pre-commit run --all-files` in follow-up sweeps. + - name: Resolve change range + id: range + run: | + if [ "${{ github.event_name }}" = "pull_request" ]; then + echo "from=${{ github.event.pull_request.base.sha }}" >> "$GITHUB_OUTPUT" + echo "to=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" + else + echo "from=${{ github.event.before }}" >> "$GITHUB_OUTPUT" + echo "to=${{ github.sha }}" >> "$GITHUB_OUTPUT" + fi - uses: pre-commit/action@v3.0.1 + with: + extra_args: --from-ref ${{ steps.range.outputs.from }} --to-ref ${{ steps.range.outputs.to }} From 80da39e03cc0fd9e7f7f57cd404f6df9cd13eb47 Mon Sep 17 00:00:00 2001 From: bakerboy448 Date: Mon, 8 Jun 2026 23:41:47 -0500 Subject: [PATCH 6/7] chore(ci): drop flaky markdown-link-check, add venv/Plexpy to cspell markdown-link-check passes locally but hangs/fails in pre-commit/action's sandboxed runner. mkdocs --strict already catches internal-link breakage; external link checks are noisy. Drop the hook rather than chase flakes. cspell: venv (referenced by CONTRIBUTING.md python-venv setup section), Plexpy (legacy Tautulli name still appears in docs). --- .cspell.json | 4 +++- .pre-commit-config.yaml | 7 ------- 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/.cspell.json b/.cspell.json index 499a8da..1c9669d 100644 --- a/.cspell.json +++ b/.cspell.json @@ -35,7 +35,9 @@ "Webhook", "webhooks", "Telegraf", - "Plexpass" + "Plexpass", + "venv", + "Plexpy" ], "allowCompoundWords": true } diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index da75a15..b097918 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -17,13 +17,6 @@ repos: - id: markdownlint args: ['--config', '.markdownlint.yaml', '--ignore', 'site/', '--ignore', '.venv/'] - - repo: https://github.com/tcort/markdown-link-check - rev: v3.13.6 - hooks: - - id: markdown-link-check - args: ['--quiet', '--config', '.markdown-link-check.json'] - exclude: ^(site/|\.venv/) - - repo: https://github.com/streetsidesoftware/cspell-cli rev: v8.17.3 hooks: From 673361d500b694e8af3c447a9d76dca023ad1fb8 Mon Sep 17 00:00:00 2001 From: bakerboy448 Date: Mon, 8 Jun 2026 23:42:54 -0500 Subject: [PATCH 7/7] fix(ci): handle zero-SHA before on first branch push Initial push of a new branch reports github.event.before as all-zeros, causing pre-commit/action's git diff to fail with exit 3. Fall back to HEAD~1 (or HEAD itself if single-commit branch). --- .github/workflows/precommit.yml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/.github/workflows/precommit.yml b/.github/workflows/precommit.yml index d0596c9..8d4a1c0 100644 --- a/.github/workflows/precommit.yml +++ b/.github/workflows/precommit.yml @@ -40,7 +40,16 @@ jobs: echo "from=${{ github.event.pull_request.base.sha }}" >> "$GITHUB_OUTPUT" echo "to=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT" else - echo "from=${{ github.event.before }}" >> "$GITHUB_OUTPUT" + from="${{ github.event.before }}" + # First push of a new branch reports before=0000... — fall back to HEAD~1 + if [ "$from" = "0000000000000000000000000000000000000000" ] || [ -z "$from" ]; then + from=$(git rev-parse HEAD~1 2>/dev/null || echo "") + fi + # If branch has only one commit, lint just the HEAD commit + if [ -z "$from" ]; then + from="${{ github.sha }}" + fi + echo "from=$from" >> "$GITHUB_OUTPUT" echo "to=${{ github.sha }}" >> "$GITHUB_OUTPUT" fi - uses: pre-commit/action@v3.0.1