diff --git a/.cspell.json b/.cspell.json new file mode 100644 index 0000000..1c9669d --- /dev/null +++ b/.cspell.json @@ -0,0 +1,43 @@ +{ + "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", + "venv", + "Plexpy" + ], + "allowCompoundWords": true +} 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..8b8a2fd 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -4,12 +4,19 @@ on: push: branches-ignore: - main + pull_request: + branches: + - main + +permissions: + contents: read jobs: build: 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 diff --git a/.github/workflows/precommit.yml b/.github/workflows/precommit.yml new file mode 100644 index 0000000..8d4a1c0 --- /dev/null +++ b/.github/workflows/precommit.yml @@ -0,0 +1,57 @@ +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 + 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 + 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 + with: + extra_args: --from-ref ${{ steps.range.outputs.from }} --to-ref ${{ steps.range.outputs.to }} 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..b097918 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,26 @@ +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/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/) 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.