Merge branch 'dev' into chore/plugin-documentation

Moves the date parsing plugin section under the extending section
Adds a section about how the 2 install types can add external plugins
2026-03-29 20:32:44 +00:00 · 2026-03-27 10:18:22 -07:00 · 2026-03-23 12:56:43 -07:00 · 2026-03-23 12:56:38 -07:00 · 2026-03-23 12:56:34 -07:00
20 changed files with 557 additions and 245 deletions
--- a/.github/ISSUE_TEMPLATE/bug-report.yml
+++ b/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -21,6 +21,7 @@ body:
        - [The installation instructions](https://docs.paperless-ngx.com/setup/#installation).
        - [Existing issues and discussions](https://github.com/paperless-ngx/paperless-ngx/search?q=&type=issues).
        - Disable any custom container initialization scripts, if using
+        - Remove any third-party parser plugins — issues caused by or requiring changes to a third-party plugin will be closed without investigation.

        If you encounter issues while installing or configuring Paperless-ngx, please post in the ["Support" section of the discussions](https://github.com/paperless-ngx/paperless-ngx/discussions/new?category=support).
  - type: textarea
@@ -120,5 +121,7 @@ body:
          required: true
        - label: I have already searched for relevant existing issues and discussions before opening this report.
          required: true
+        - label: I have reproduced this issue with all third-party parser plugins removed. I understand that issues caused by third-party plugins will be closed without investigation.
+          required: true
        - label: I have updated the title field above with a concise description.
          required: true
--- a/.github/workflows/ci-backend.yml
+++ b/.github/workflows/ci-backend.yml
@@ -21,7 +21,7 @@ jobs:
      backend_changed: ${{ steps.force.outputs.run_all == 'true' || steps.filter.outputs.backend == 'true' }}
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
        with:
          fetch-depth: 0
      - name: Decide run mode
@@ -49,7 +49,7 @@ jobs:
      - name: Detect changes
        id: filter
        if: steps.force.outputs.run_all != 'true'
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        uses: dorny/paths-filter@v3.0.2
        with:
          base: ${{ steps.range.outputs.base }}
          ref: ${{ steps.range.outputs.ref }}
@@ -71,18 +71,18 @@ jobs:
      fail-fast: false
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
      - name: Start containers
        run: |
          docker compose --file docker/compose/docker-compose.ci-test.yml pull --quiet
          docker compose --file docker/compose/docker-compose.ci-test.yml up --detach
      - name: Set up Python
        id: setup-python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@v6.2.0
        with:
          python-version: "${{ matrix.python-version }}"
      - name: Install uv
-        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
+        uses: astral-sh/setup-uv@v7.3.1
        with:
          version: ${{ env.DEFAULT_UV_VERSION }}
          enable-cache: true
@@ -119,13 +119,13 @@ jobs:
            pytest
      - name: Upload test results to Codecov
        if: always()
-        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5.5.2
+        uses: codecov/codecov-action@v5.5.2
        with:
          flags: backend-python-${{ matrix.python-version }}
          files: junit.xml
          report_type: test_results
      - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5.5.2
+        uses: codecov/codecov-action@v5.5.2
        with:
          flags: backend-python-${{ matrix.python-version }}
          files: coverage.xml
@@ -144,14 +144,14 @@ jobs:
      DEFAULT_PYTHON: "3.12"
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
      - name: Set up Python
        id: setup-python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@v6.2.0
        with:
          python-version: "${{ env.DEFAULT_PYTHON }}"
      - name: Install uv
-        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
+        uses: astral-sh/setup-uv@v7.3.1
        with:
          version: ${{ env.DEFAULT_UV_VERSION }}
          enable-cache: true
@@ -173,7 +173,7 @@ jobs:
            check \
            src/
      - name: Cache Mypy
-        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
+        uses: actions/cache@v5.0.3
        with:
          path: .mypy_cache
          # Keyed by OS, Python version, and dependency hashes
--- a/.github/workflows/ci-docker.yml
+++ b/.github/workflows/ci-docker.yml
@@ -41,7 +41,7 @@ jobs:
      ref-name: ${{ steps.ref.outputs.name }}
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
      - name: Determine ref name
        id: ref
        run: |
@@ -104,9 +104,9 @@ jobs:
          echo "repository=${repo_name}"
          echo "name=${repo_name}" >> $GITHUB_OUTPUT
      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+        uses: docker/setup-buildx-action@v4.0.0
      - name: Login to GitHub Container Registry
-        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
+        uses: docker/login-action@v4.0.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
@@ -119,7 +119,7 @@ jobs:
          sudo rm -rf "$AGENT_TOOLSDIRECTORY"
      - name: Docker metadata
        id: docker-meta
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        uses: docker/metadata-action@v6.0.0
        with:
          images: |
            ${{ env.REGISTRY }}/${{ steps.repo.outputs.name }}
@@ -130,7 +130,7 @@ jobs:
            type=semver,pattern={{major}}.{{minor}}
      - name: Build and push by digest
        id: build
-        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
+        uses: docker/build-push-action@v7.0.0
        with:
          context: .
          file: ./Dockerfile
@@ -152,7 +152,7 @@ jobs:
          echo "${digest}" > "/tmp/digests/digest-${{ matrix.arch }}.txt"
      - name: Upload digest
        if: steps.check-push.outputs.should-push == 'true'
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@v7.0.0
        with:
          name: digests-${{ matrix.arch }}
          path: /tmp/digests/digest-${{ matrix.arch }}.txt
@@ -169,7 +169,7 @@ jobs:
      packages: write
    steps:
      - name: Download digests
-        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
+        uses: actions/download-artifact@v8.0.0
        with:
          path: /tmp/digests
          pattern: digest-*.txt
@@ -179,29 +179,29 @@ jobs:
          echo "Downloaded digests:"
          ls -la /tmp/digests/
      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+        uses: docker/setup-buildx-action@v4.0.0
      - name: Login to GitHub Container Registry
-        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
+        uses: docker/login-action@v4.0.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Login to Docker Hub
        if: needs.build-arch.outputs.push-external == 'true'
-        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
+        uses: docker/login-action@v4.0.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      - name: Login to Quay.io
        if: needs.build-arch.outputs.push-external == 'true'
-        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
+        uses: docker/login-action@v4.0.0
        with:
          registry: quay.io
          username: ${{ secrets.QUAY_USERNAME }}
          password: ${{ secrets.QUAY_ROBOT_TOKEN }}
      - name: Docker metadata
        id: docker-meta
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        uses: docker/metadata-action@v6.0.0
        with:
          images: |
            ${{ env.REGISTRY }}/${{ needs.build-arch.outputs.repository }}
--- a/.github/workflows/ci-docs.yml
+++ b/.github/workflows/ci-docs.yml
@@ -23,7 +23,7 @@ jobs:
      docs_changed: ${{ steps.force.outputs.run_all == 'true' || steps.filter.outputs.docs == 'true' }}
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
        with:
          fetch-depth: 0
      - name: Decide run mode
@@ -51,7 +51,7 @@ jobs:
      - name: Detect changes
        id: filter
        if: steps.force.outputs.run_all != 'true'
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        uses: dorny/paths-filter@v3.0.2
        with:
          base: ${{ steps.range.outputs.base }}
          ref: ${{ steps.range.outputs.ref }}
@@ -68,16 +68,16 @@ jobs:
    name: Build Documentation
    runs-on: ubuntu-24.04
    steps:
-      - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+      - uses: actions/configure-pages@v5.0.0
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
      - name: Set up Python
        id: setup-python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@v6.2.0
        with:
          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
      - name: Install uv
-        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
+        uses: astral-sh/setup-uv@v7.3.1
        with:
          version: ${{ env.DEFAULT_UV_VERSION }}
          enable-cache: true
@@ -93,7 +93,7 @@ jobs:
            --frozen \
            zensical build --clean
      - name: Upload GitHub Pages artifact
-        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        uses: actions/upload-pages-artifact@v4.0.0
        with:
          path: site
          name: github-pages-${{ github.run_id }}-${{ github.run_attempt }}
@@ -107,7 +107,7 @@ jobs:
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy GitHub Pages
-        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
+        uses: actions/deploy-pages@v4.0.5
        id: deployment
        with:
          artifact_name: github-pages-${{ github.run_id }}-${{ github.run_attempt }}
--- a/.github/workflows/ci-frontend.yml
+++ b/.github/workflows/ci-frontend.yml
@@ -18,7 +18,7 @@ jobs:
      frontend_changed: ${{ steps.force.outputs.run_all == 'true' || steps.filter.outputs.frontend == 'true' }}
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
        with:
          fetch-depth: 0
      - name: Decide run mode
@@ -46,7 +46,7 @@ jobs:
      - name: Detect changes
        id: filter
        if: steps.force.outputs.run_all != 'true'
-        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        uses: dorny/paths-filter@v3.0.2
        with:
          base: ${{ steps.range.outputs.base }}
          ref: ${{ steps.range.outputs.ref }}
@@ -61,20 +61,20 @@ jobs:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
      - name: Install pnpm
-        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
+        uses: pnpm/action-setup@v4.2.0
        with:
          version: 10
      - name: Use Node.js 24
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        uses: actions/setup-node@v6.3.0
        with:
          node-version: 24.x
          cache: 'pnpm'
          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
      - name: Cache frontend dependencies
        id: cache-frontend-deps
-        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
+        uses: actions/cache@v5.0.3
        with:
          path: |
            ~/.pnpm-store
@@ -89,19 +89,19 @@ jobs:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
      - name: Install pnpm
-        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
+        uses: pnpm/action-setup@v4.2.0
        with:
          version: 10
      - name: Use Node.js 24
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        uses: actions/setup-node@v6.3.0
        with:
          node-version: 24.x
          cache: 'pnpm'
          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
      - name: Cache frontend dependencies
-        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
+        uses: actions/cache@v5.0.3
        with:
          path: |
            ~/.pnpm-store
@@ -124,19 +124,19 @@ jobs:
        shard-count: [4]
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
      - name: Install pnpm
-        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
+        uses: pnpm/action-setup@v4.2.0
        with:
          version: 10
      - name: Use Node.js 24
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        uses: actions/setup-node@v6.3.0
        with:
          node-version: 24.x
          cache: 'pnpm'
          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
      - name: Cache frontend dependencies
-        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
+        uses: actions/cache@v5.0.3
        with:
          path: |
            ~/.pnpm-store
@@ -148,13 +148,13 @@ jobs:
        run: cd src-ui && pnpm run test --max-workers=2 --shard=${{ matrix.shard-index }}/${{ matrix.shard-count }}
      - name: Upload test results to Codecov
        if: always()
-        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5.5.2
+        uses: codecov/codecov-action@v5.5.2
        with:
          flags: frontend-node-${{ matrix.node-version }}
          directory: src-ui/
          report_type: test_results
      - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5.5.2
+        uses: codecov/codecov-action@v5.5.2
        with:
          flags: frontend-node-${{ matrix.node-version }}
          directory: src-ui/coverage/
@@ -175,19 +175,19 @@ jobs:
        shard-count: [2]
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
      - name: Install pnpm
-        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
+        uses: pnpm/action-setup@v4.2.0
        with:
          version: 10
      - name: Use Node.js 24
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        uses: actions/setup-node@v6.3.0
        with:
          node-version: 24.x
          cache: 'pnpm'
          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
      - name: Cache frontend dependencies
-        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
+        uses: actions/cache@v5.0.3
        with:
          path: |
            ~/.pnpm-store
@@ -206,21 +206,21 @@ jobs:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
        with:
          fetch-depth: 2
      - name: Install pnpm
-        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
+        uses: pnpm/action-setup@v4.2.0
        with:
          version: 10
      - name: Use Node.js 24
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        uses: actions/setup-node@v6.3.0
        with:
          node-version: 24.x
          cache: 'pnpm'
          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
      - name: Cache frontend dependencies
-        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
+        uses: actions/cache@v5.0.3
        with:
          path: |
            ~/.pnpm-store
--- a/.github/workflows/ci-lint.yml
+++ b/.github/workflows/ci-lint.yml
@@ -15,10 +15,10 @@ jobs:
    runs-on: ubuntu-slim
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
      - name: Install Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@v6.2.0
        with:
          python-version: "3.14"
      - name: Run prek
-        uses: j178/prek-action@0bb87d7f00b0c99306c8bcb8b8beba1eb581c037 # v1.1.1
+        uses: j178/prek-action@v1.1.1
--- a/.github/workflows/ci-release.yml
+++ b/.github/workflows/ci-release.yml
@@ -16,7 +16,7 @@ jobs:
    runs-on: ubuntu-24.04
    steps:
      - name: Wait for Docker build
-        uses: lewagon/wait-on-check-action@74049309dfeff245fe8009a0137eacf28136cb3c # v1.5.0
+        uses: lewagon/wait-on-check-action@v1.5.0
        with:
          ref: ${{ github.sha }}
          check-name: 'Build Docker Image'
@@ -28,14 +28,14 @@ jobs:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
      # ---- Frontend Build ----
      - name: Install pnpm
-        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
+        uses: pnpm/action-setup@v4.2.0
        with:
          version: 10
      - name: Use Node.js 24
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        uses: actions/setup-node@v6.3.0
        with:
          node-version: 24.x
          cache: 'pnpm'
@@ -47,11 +47,11 @@ jobs:
      # ---- Backend Setup ----
      - name: Set up Python
        id: setup-python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@v6.2.0
        with:
          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
      - name: Install uv
-        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
+        uses: astral-sh/setup-uv@v7.3.1
        with:
          version: ${{ env.DEFAULT_UV_VERSION }}
          enable-cache: true
@@ -118,7 +118,7 @@ jobs:
          sudo chown -R 1000:1000 paperless-ngx/
          tar -cJf paperless-ngx.tar.xz paperless-ngx/
      - name: Upload release artifact
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@v7.0.0
        with:
          name: release
          path: dist/paperless-ngx.tar.xz
@@ -133,7 +133,7 @@ jobs:
      version: ${{ steps.get-version.outputs.version }}
    steps:
      - name: Download release artifact
-        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
+        uses: actions/download-artifact@v8.0.0
        with:
          name: release
          path: ./
@@ -148,7 +148,7 @@ jobs:
          fi
      - name: Create release and changelog
        id: create-release
-        uses: release-drafter/release-drafter@6db134d15f3909ccc9eefd369f02bd1e9cffdf97 # v6.2.0
+        uses: release-drafter/release-drafter@v6.2.0
        with:
          name: Paperless-ngx ${{ steps.get-version.outputs.version }}
          tag: ${{ steps.get-version.outputs.version }}
@@ -159,7 +159,7 @@ jobs:
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Upload release archive
-        uses: shogo82148/actions-upload-release-asset@8f6863c6c894ba46f9e676ef5cccec4752723c1e # v1.9.2
+        uses: shogo82148/actions-upload-release-asset@v1.9.2
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          upload_url: ${{ steps.create-release.outputs.upload_url }}
@@ -176,16 +176,16 @@ jobs:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
        with:
          ref: main
      - name: Set up Python
        id: setup-python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@v6.2.0
        with:
          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
      - name: Install uv
-        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
+        uses: astral-sh/setup-uv@v7.3.1
        with:
          version: ${{ env.DEFAULT_UV_VERSION }}
          enable-cache: true
@@ -218,7 +218,7 @@ jobs:
          git commit -am "Changelog ${{ needs.publish-release.outputs.version }} - GHA"
          git push origin ${{ needs.publish-release.outputs.version }}-changelog
      - name: Create pull request
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@v8.0.0
        with:
          script: |
            const { repo, owner } = context.repo;
--- a/.github/workflows/cleanup-tags.yml
+++ b/.github/workflows/cleanup-tags.yml
@@ -27,7 +27,7 @@ jobs:
    steps:
      - name: Clean temporary images
        if: "${{ env.TOKEN != '' }}"
-        uses: stumpylog/image-cleaner-action/ephemeral@4fe057d991d63b8f6d5d22c40f17c1bca2226537 # v0.12.0
+        uses: stumpylog/image-cleaner-action/ephemeral@v0.12.0
        with:
          token: "${{ env.TOKEN }}"
          owner: "${{ github.repository_owner }}"
@@ -53,7 +53,7 @@ jobs:
    steps:
      - name: Clean untagged images
        if: "${{ env.TOKEN != '' }}"
-        uses: stumpylog/image-cleaner-action/untagged@4fe057d991d63b8f6d5d22c40f17c1bca2226537 # v0.12.0
+        uses: stumpylog/image-cleaner-action/untagged@v0.12.0
        with:
          token: "${{ env.TOKEN }}"
          owner: "${{ github.repository_owner }}"
--- a/.github/workflows/codeql-analysis.yml
+++ b/.github/workflows/codeql-analysis.yml
@@ -34,10 +34,10 @@ jobs:
        # Learn more about CodeQL language support at https://git.io/codeql-language-support
    steps:
      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
-        uses: github/codeql-action/init@c793b717bc78562f491db7b0e93a3a178b099162 # v4.32.5
+        uses: github/codeql-action/init@v4.32.5
        with:
          languages: ${{ matrix.language }}
          # If you wish to specify custom queries, you can do so here or in a config file.
@@ -45,4 +45,4 @@ jobs:
          # Prefix the list here with "+" to use these queries and those in the config file.
          # queries: ./path/to/local/query, your-org/your-repo/queries@main
      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@c793b717bc78562f491db7b0e93a3a178b099162 # v4.32.5
+        uses: github/codeql-action/analyze@v4.32.5
--- a/.github/workflows/crowdin.yml
+++ b/.github/workflows/crowdin.yml
@@ -13,11 +13,11 @@ jobs:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
        with:
          token: ${{ secrets.PNGX_BOT_PAT }}
      - name: crowdin action
-        uses: crowdin/github-action@8818ff65bfc4322384f983ea37e3926948c11745 # v2.15.0
+        uses: crowdin/github-action@v2.15.0
        with:
          upload_translations: false
          download_translations: true
--- a/.github/workflows/pr-bot.yml
+++ b/.github/workflows/pr-bot.yml
@@ -10,7 +10,7 @@ jobs:
      issues: read
      pull-requests: write
    steps:
-      - uses: peakoss/anti-slop@85daca1880e9e1af197fc06ea03349daf08f4202 # v0.2.1
+      - uses: peakoss/anti-slop@v0.2.1
        with:
          max-failures: 4
          failure-add-pr-labels: 'ai'
@@ -23,11 +23,11 @@ jobs:
    steps:
      - name: Label PR by file path or branch name
        # see .github/labeler.yml for the labeler config
-        uses: actions/labeler@634933edcd8ababfe52f92936142cc22ac488b1b # v6.0.1
+        uses: actions/labeler@v6.0.1
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
      - name: Label by size
-        uses: Gascon1/pr-size-labeler@deff8ed00a76639a7c0f197525bafa3350ba4c36 # v1.3.0
+        uses: Gascon1/pr-size-labeler@v1.3.0
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          xs_label: 'small-change'
@@ -37,7 +37,7 @@ jobs:
          fail_if_xl: 'false'
          excluded_files: /\.lock$/ /\.txt$/ ^src-ui/pnpm-lock\.yaml$ ^src-ui/messages\.xlf$ ^src/locale/en_US/LC_MESSAGES/django\.po$
      - name: Label by PR title
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@v8.0.0
        with:
          script: |
            const pr = context.payload.pull_request;
@@ -63,7 +63,7 @@ jobs:
            }
      - name: Label bot-generated PRs
        if: ${{ contains(github.actor, 'dependabot') || contains(github.actor, 'crowdin-bot') }}
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@v8.0.0
        with:
          script: |
            const pr = context.payload.pull_request;
@@ -88,7 +88,7 @@ jobs:
            }
      - name: Welcome comment
        if: ${{ !contains(github.actor, 'bot') }}
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        uses: actions/github-script@v8.0.0
        with:
          script: |
            const pr = context.payload.pull_request;
--- a/.github/workflows/project-actions.yml
+++ b/.github/workflows/project-actions.yml
@@ -19,6 +19,6 @@ jobs:
    if: github.event_name == 'pull_request_target' && (github.event.action == 'opened' || github.event.action == 'reopened') && github.event.pull_request.user.login != 'dependabot'
    steps:
      - name: Label PR with release-drafter
-        uses: release-drafter/release-drafter@6db134d15f3909ccc9eefd369f02bd1e9cffdf97 # v6.2.0
+        uses: release-drafter/release-drafter@v6.2.0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
--- a/.github/workflows/repo-maintenance.yml
+++ b/.github/workflows/repo-maintenance.yml
@@ -15,7 +15,7 @@ jobs:
    if: github.repository_owner == 'paperless-ngx'
    runs-on: ubuntu-24.04
    steps:
-      - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
+      - uses: actions/stale@v10.2.0
        with:
          days-before-stale: 7
          days-before-close: 14
@@ -37,7 +37,7 @@ jobs:
    if: github.repository_owner == 'paperless-ngx'
    runs-on: ubuntu-24.04
    steps:
-      - uses: dessant/lock-threads@7266a7ce5c1df01b1c6db85bf8cd86c737dadbe7 # v6.0.0
+      - uses: dessant/lock-threads@v6.0.0
        with:
          issue-inactive-days: '30'
          pr-inactive-days: '30'
@@ -57,7 +57,7 @@ jobs:
    if: github.repository_owner == 'paperless-ngx'
    runs-on: ubuntu-24.04
    steps:
-      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+      - uses: actions/github-script@v8.0.0
        with:
          script: |
            function sleep(ms) {
@@ -114,7 +114,7 @@ jobs:
    if: github.repository_owner == 'paperless-ngx'
    runs-on: ubuntu-24.04
    steps:
-      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+      - uses: actions/github-script@v8.0.0
        with:
          script: |
            function sleep(ms) {
@@ -206,7 +206,7 @@ jobs:
    if: github.repository_owner == 'paperless-ngx'
    runs-on: ubuntu-24.04
    steps:
-      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+      - uses: actions/github-script@v8.0.0
        with:
          script: |
            function sleep(ms) {
--- a/.github/workflows/translate-strings.yml
+++ b/.github/workflows/translate-strings.yml
@@ -11,7 +11,7 @@ jobs:
      contents: write
    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v6.0.2
        env:
          GH_REF: ${{ github.ref }} # sonar rule:githubactions:S7630 - avoid injection
        with:
@@ -19,13 +19,13 @@ jobs:
          ref: ${{ env.GH_REF }}
      - name: Set up Python
        id: setup-python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@v6.2.0
      - name: Install system dependencies
        run: |
          sudo apt-get update -qq
          sudo apt-get install -qq --no-install-recommends gettext
      - name: Install uv
-        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
+        uses: astral-sh/setup-uv@v7.3.1
        with:
          enable-cache: true
      - name: Install backend python dependencies
@@ -36,18 +36,18 @@ jobs:
      - name: Generate backend translation strings
        run: cd src/ && uv run manage.py makemessages -l en_US -i "samples*"
      - name: Install pnpm
-        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
+        uses: pnpm/action-setup@v4.2.0
        with:
          version: 10
      - name: Use Node.js 24
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        uses: actions/setup-node@v6.3.0
        with:
          node-version: 24.x
          cache: 'pnpm'
          cache-dependency-path: 'src-ui/pnpm-lock.yaml'
      - name: Cache frontend dependencies
        id: cache-frontend-deps
-        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
+        uses: actions/cache@v5.0.3
        with:
          path: |
            ~/.pnpm-store
@@ -63,7 +63,7 @@ jobs:
          cd src-ui
          pnpm run ng extract-i18n
      - name: Commit changes
-        uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7.1.0
+        uses: stefanzweifel/git-auto-commit-action@v7.1.0
        with:
          file_pattern: 'src-ui/messages.xlf src/locale/en_US/LC_MESSAGES/django.po'
          commit_message: "Auto translate strings"
--- a/docs/advanced_usage.md
+++ b/docs/advanced_usage.md
@@ -723,6 +723,81 @@ services:

 1. Note the `:ro` tag means the folder will be mounted as read only. This is for extra security against changes

+## Installing third-party parser plugins {#parser-plugins}
+
+Third-party parser plugins extend Paperless-ngx to support additional file
+formats. A plugin is a Python package that advertises itself under the
+`paperless_ngx.parsers` entry point group. Refer to the
+[developer documentation](development.md#making-custom-parsers) for how to
+create one.
+
+!!! warning "Third-party plugins are not officially supported"
+
+    The Paperless-ngx maintainers do not provide support for third-party
+    plugins. Issues caused by or requiring changes to a third-party plugin
+    will be closed without further investigation. Always reproduce problems
+    with all plugins removed before filing a bug report.
+
+### Docker
+
+Use a [custom container initialization script](#custom-container-initialization)
+to install the package before the webserver starts. Create a shell script and
+mount it into `/custom-cont-init.d`:
+
+```bash
+#!/bin/bash
+# /path/to/my/scripts/install-parsers.sh
+
+pip install my-paperless-parser-package
+```
+
+Mount it in your `docker-compose.yml`:
+
+```yaml
+services:
+  webserver:
+    # ...
+    volumes:
+      - /path/to/my/scripts:/custom-cont-init.d:ro
+```
+
+The script runs as `root` before the webserver starts, so the package will be
+available when Paperless-ngx discovers plugins at startup.
+
+### Bare metal
+
+Install the package into the same Python environment that runs Paperless-ngx.
+If you followed the standard bare-metal install guide, that is the `paperless`
+user's environment:
+
+```bash
+sudo -Hu paperless pip3 install my-paperless-parser-package
+```
+
+If you are using `uv` or a virtual environment, activate it first and then run:
+
+```bash
+uv pip install my-paperless-parser-package
+# or
+pip install my-paperless-parser-package
+```
+
+Restart all Paperless-ngx services after installation so the new plugin is
+discovered.
+
+### Verifying installation
+
+On the next startup, check the application logs for a line confirming
+discovery:
+
+```
+Loaded third-party parser 'My Parser' v1.0.0 by Acme Corp (entrypoint: 'my_parser').
+```
+
+If this line does not appear, verify that the package is installed in the
+correct environment and that its `pyproject.toml` declares the
+`paperless_ngx.parsers` entry point.
+
 ## MySQL Caveats {#mysql-caveats}

 ### Case Sensitivity
--- a/docs/development.md
+++ b/docs/development.md
@@ -370,121 +370,363 @@ docker build --file Dockerfile --tag paperless:local .

 ## Extending Paperless-ngx

-Paperless-ngx does not have any fancy plugin systems and will probably never
-have. However, some parts of the application have been designed to allow
-easy integration of additional features without any modification to the
-base code.
+Paperless-ngx supports third-party document parsers via a Python entry point
+plugin system. Plugins are distributed as ordinary Python packages and
+discovered automatically at startup — no changes to the Paperless-ngx source
+are required.
+
+!!! warning "Third-party plugins are not officially supported"
+
+    The Paperless-ngx maintainers do not provide support for third-party
+    plugins. Issues that are caused by or require changes to a third-party
+    plugin will be closed without further investigation. If you believe you
+    have found a bug in Paperless-ngx itself (not in a plugin), please
+    reproduce it with all third-party plugins removed before filing an issue.

 ### Making custom parsers

-Paperless-ngx uses parsers to add documents. A parser is
-responsible for:
+Paperless-ngx uses parsers to add documents. A parser is responsible for:

- Retrieving the content from the original
- Creating a thumbnail
- _optional:_ Retrieving a created date from the original
- _optional:_ Creating an archived document from the original
+- Extracting plain-text content from the document
+- Generating a thumbnail image
+- _optional:_ Detecting the document's creation date
+- _optional:_ Producing a searchable PDF archive copy

-Custom parsers can be added to Paperless-ngx to support more file types. In
-order to do that, you need to write the parser itself and announce its
-existence to Paperless-ngx.
+Custom parsers are distributed as ordinary Python packages and registered
+via a [setuptools entry point](https://setuptools.pypa.io/en/latest/userguide/entry_point.html).
+No changes to the Paperless-ngx source are required.

-The parser itself must extend `documents.parsers.DocumentParser` and
-must implement the methods `parse` and `get_thumbnail`. You can provide
-your own implementation to `get_date` if you don't want to rely on
-Paperless-ngx' default date guessing mechanisms.
+#### 1. Implementing the parser class
+
+Your parser must satisfy the `ParserProtocol` structural interface defined in
+`paperless.parsers`. The simplest approach is to write a plain class — no base
+class is required, only the right attributes and methods.
+
+**Class-level identity attributes**
+
+The registry reads these before instantiating the parser, so they must be
+plain class attributes (not instance attributes or properties):

 ```python
-class MyCustomParser(DocumentParser):
-
-    def parse(self, document_path, mime_type):
-        # This method does not return anything. Rather, you should assign
-        # whatever you got from the document to the following fields:
-
-        # The content of the document.
-        self.text = "content"
-
-        # Optional: path to a PDF document that you created from the original.
-        self.archive_path = os.path.join(self.tempdir, "archived.pdf")
-
-        # Optional: "created" date of the document.
-        self.date = get_created_from_metadata(document_path)
-
-    def get_thumbnail(self, document_path, mime_type):
-        # This should return the path to a thumbnail you created for this
-        # document.
-        return os.path.join(self.tempdir, "thumb.webp")
+class MyCustomParser:
+    name    = "My Format Parser"   # human-readable name shown in logs
+    version = "1.0.0"              # semantic version string
+    author  = "Acme Corp"          # author / organisation
+    url     = "https://example.com/my-parser"  # docs or issue tracker
 ```

-If you encounter any issues during parsing, raise a
-`documents.parsers.ParseError`.
+**Declaring supported MIME types**

-The `self.tempdir` directory is a temporary directory that is guaranteed
-to be empty and removed after consumption finished. You can use that
-directory to store any intermediate files and also use it to store the
-thumbnail / archived document.
-
-After that, you need to announce your parser to Paperless-ngx. You need to
-connect a handler to the `document_consumer_declaration` signal. Have a
-look in the file `src/paperless_tesseract/apps.py` on how that's done.
-The handler is a method that returns information about your parser:
+Return a `dict` mapping MIME type strings to preferred file extensions
+(including the leading dot). Paperless-ngx uses the extension when storing
+archive copies and serving files for download.

 ```python
-def myparser_consumer_declaration(sender, **kwargs):
+@classmethod
+def supported_mime_types(cls) -> dict[str, str]:
    return {
-        "parser": MyCustomParser,
-        "weight": 0,
-        "mime_types": {
-            "application/pdf": ".pdf",
-            "image/jpeg": ".jpg",
-        }
+        "application/x-my-format": ".myf",
+        "application/x-my-format-alt": ".myf",
    }
 ```

- `parser` is a reference to a class that extends `DocumentParser`.
- `weight` is used whenever two or more parsers are able to parse a
-  file: The parser with the higher weight wins. This can be used to
-  override the parsers provided by Paperless-ngx.
- `mime_types` is a dictionary. The keys are the mime types your
-  parser supports and the value is the default file extension that
-  Paperless-ngx should use when storing files and serving them for
-  download. We could guess that from the file extensions, but some
-  mime types have many extensions associated with them and the Python
-  methods responsible for guessing the extension do not always return
-  the same value.
+**Scoring**

-## Using Visual Studio Code devcontainer
+When more than one parser can handle a file, the registry calls `score()` on
+each candidate and picks the one with the highest result. Return `None` to
+decline handling a file even though the MIME type is listed as supported (for
+example, when a required external service is not configured).

-Another easy way to get started with development is to use Visual Studio
-Code devcontainers. This approach will create a preconfigured development
-environment with all of the required tools and dependencies.
-[Learn more about devcontainers](https://code.visualstudio.com/docs/devcontainers/containers).
-The .devcontainer/vscode/tasks.json and .devcontainer/vscode/launch.json files
-contain more information about the specific tasks and launch configurations (see the
-non-standard "description" field).
+| Score  | Meaning                                           |
+| ------ | ------------------------------------------------- |
+| `None` | Decline — do not handle this file                 |
+| `10`   | Default priority used by all built-in parsers     |
+| `> 10` | Override a built-in parser for the same MIME type |

-To get started:
+```python
+@classmethod
+def score(
+    cls,
+    mime_type: str,
+    filename: str,
+    path: "Path | None" = None,
+) -> int | None:
+    # Inspect filename or file bytes here if needed.
+    return 10
+```

-1. Clone the repository on your machine and open the Paperless-ngx folder in VS Code.
+**Archive and rendition flags**

-2. VS Code will prompt you with "Reopen in container". Do so and wait for the environment to start.
+```python
+@property
+def can_produce_archive(self) -> bool:
+    """True if parse() can produce a searchable PDF archive copy."""
+    return True   # or False if your parser doesn't produce PDFs

-3. In case your host operating system is Windows:
-   - The Source Control view in Visual Studio Code might show: "The detected Git repository is potentially unsafe as the folder is owned by someone other than the current user." Use "Manage Unsafe Repositories" to fix this.
-   - Git might have detecteded modifications for all files, because Windows is using CRLF line endings. Run `git checkout .` in the containers terminal to fix this issue.
+@property
+def requires_pdf_rendition(self) -> bool:
+    """True if the original format cannot be displayed by a browser
+    (e.g. DOCX, ODT) and the PDF output must always be kept."""
+    return False
+```

-4. Initialize the project by running the task **Project Setup: Run all Init Tasks**. This
-   will initialize the database tables and create a superuser. Then you can compile the front end
-   for production or run the frontend in debug mode.
+**Context manager — temp directory lifecycle**

-5. The project is ready for debugging, start either run the fullstack debug or individual debug
-   processes. Yo spin up the project without debugging run the task **Project Start: Run all Services**
+Paperless-ngx always uses parsers as context managers. Create a temporary
+working directory in `__enter__` (or `__init__`) and remove it in `__exit__`
+regardless of whether an exception occurred. Store intermediate files,
+thumbnails, and archive PDFs inside this directory.

-## Developing Date Parser Plugins
+```python
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Self
+from types import TracebackType
+
+from django.conf import settings
+
+class MyCustomParser:
+    ...
+
+    def __init__(self, logging_group: object = None) -> None:
+        settings.SCRATCH_DIR.mkdir(parents=True, exist_ok=True)
+        self._tempdir = Path(
+            tempfile.mkdtemp(prefix="paperless-", dir=settings.SCRATCH_DIR)
+        )
+        self._text: str | None = None
+        self._archive_path: Path | None = None
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        shutil.rmtree(self._tempdir, ignore_errors=True)
+```
+
+**Optional context — `configure()`**
+
+The consumer calls `configure()` with a `ParserContext` after instantiation
+and before `parse()`. If your parser doesn't need context, a no-op
+implementation is fine:
+
+```python
+from paperless.parsers import ParserContext
+
+def configure(self, context: ParserContext) -> None:
+    pass   # override if you need context.mailrule_id, etc.
+```
+
+**Parsing**
+
+`parse()` is the core method. It must not return a value; instead, store
+results in instance attributes and expose them via the accessor methods below.
+Raise `documents.parsers.ParseError` on any unrecoverable failure.
+
+```python
+from documents.parsers import ParseError
+
+def parse(
+    self,
+    document_path: Path,
+    mime_type: str,
+    *,
+    produce_archive: bool = True,
+) -> None:
+    try:
+        self._text = extract_text_from_my_format(document_path)
+    except Exception as e:
+        raise ParseError(f"Failed to parse {document_path}: {e}") from e
+
+    if produce_archive and self.can_produce_archive:
+        archive = self._tempdir / "archived.pdf"
+        convert_to_pdf(document_path, archive)
+        self._archive_path = archive
+```
+
+**Result accessors**
+
+```python
+def get_text(self) -> str | None:
+    return self._text
+
+def get_date(self) -> "datetime.datetime | None":
+    # Return a datetime extracted from the document, or None to let
+    # Paperless-ngx use its default date-guessing logic.
+    return None
+
+def get_archive_path(self) -> Path | None:
+    return self._archive_path
+```
+
+**Thumbnail**
+
+`get_thumbnail()` may be called independently of `parse()`. Return the path
+to a WebP image inside `self._tempdir`. The image should be roughly 500 × 700
+pixels.
+
+```python
+def get_thumbnail(self, document_path: Path, mime_type: str) -> Path:
+    thumb = self._tempdir / "thumb.webp"
+    render_thumbnail(document_path, thumb)
+    return thumb
+```
+
+**Optional methods**
+
+These are called by the API on demand, not during the consumption pipeline.
+Implement them if your format supports the information; otherwise return
+`None` / `[]`.
+
+```python
+def get_page_count(self, document_path: Path, mime_type: str) -> int | None:
+    return count_pages(document_path)
+
+def extract_metadata(
+    self,
+    document_path: Path,
+    mime_type: str,
+) -> "list[MetadataEntry]":
+    # Must never raise. Return [] if metadata cannot be read.
+    from paperless.parsers import MetadataEntry
+    return [
+        MetadataEntry(
+            namespace="https://example.com/ns/",
+            prefix="ex",
+            key="Author",
+            value="Alice",
+        )
+    ]
+```
+
+#### 2. Registering via entry point
+
+Add the following to your package's `pyproject.toml`. The key (left of `=`)
+is an arbitrary name used only in log output; the value is the
+`module:ClassName` import path.
+
+```toml
+[project.entry-points."paperless_ngx.parsers"]
+my_parser = "my_package.parsers:MyCustomParser"
+```
+
+Install your package into the same Python environment as Paperless-ngx (or
+add it to the Docker image), and the parser will be discovered automatically
+on the next startup. No configuration changes are needed.
+
+To verify discovery, check the application logs at startup for a line like:
+
+```
+Loaded third-party parser 'My Format Parser' v1.0.0 by Acme Corp (entrypoint: 'my_parser').
+```
+
+#### 3. Utilities
+
+`paperless.parsers.utils` provides helpers you can import directly:
+
+| Function                                | Description                                                      |
+| --------------------------------------- | ---------------------------------------------------------------- |
+| `read_file_handle_unicode_errors(path)` | Read a file as UTF-8, replacing invalid bytes instead of raising |
+| `get_page_count_for_pdf(path)`          | Count pages in a PDF using pikepdf                               |
+| `extract_pdf_metadata(path)`            | Extract XMP metadata from a PDF as a `list[MetadataEntry]`       |
+
+#### Minimal example
+
+A complete, working parser for a hypothetical plain-XML format:
+
+```python
+from __future__ import annotations
+
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Self
+from types import TracebackType
+import xml.etree.ElementTree as ET
+
+from django.conf import settings
+
+from documents.parsers import ParseError
+from paperless.parsers import ParserContext
+
+
+class XmlDocumentParser:
+    name    = "XML Parser"
+    version = "1.0.0"
+    author  = "Acme Corp"
+    url     = "https://example.com/xml-parser"
+
+    @classmethod
+    def supported_mime_types(cls) -> dict[str, str]:
+        return {"application/xml": ".xml", "text/xml": ".xml"}
+
+    @classmethod
+    def score(cls, mime_type: str, filename: str, path: Path | None = None) -> int | None:
+        return 10
+
+    @property
+    def can_produce_archive(self) -> bool:
+        return False
+
+    @property
+    def requires_pdf_rendition(self) -> bool:
+        return False
+
+    def __init__(self, logging_group: object = None) -> None:
+        settings.SCRATCH_DIR.mkdir(parents=True, exist_ok=True)
+        self._tempdir = Path(tempfile.mkdtemp(prefix="paperless-", dir=settings.SCRATCH_DIR))
+        self._text: str | None = None
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        shutil.rmtree(self._tempdir, ignore_errors=True)
+
+    def configure(self, context: ParserContext) -> None:
+        pass
+
+    def parse(self, document_path: Path, mime_type: str, *, produce_archive: bool = True) -> None:
+        try:
+            tree = ET.parse(document_path)
+            self._text = " ".join(tree.getroot().itertext())
+        except ET.ParseError as e:
+            raise ParseError(f"XML parse error: {e}") from e
+
+    def get_text(self) -> str | None:
+        return self._text
+
+    def get_date(self):
+        return None
+
+    def get_archive_path(self) -> Path | None:
+        return None
+
+    def get_thumbnail(self, document_path: Path, mime_type: str) -> Path:
+        from PIL import Image, ImageDraw
+        img = Image.new("RGB", (500, 700), color="white")
+        ImageDraw.Draw(img).text((10, 10), "XML Document", fill="black")
+        out = self._tempdir / "thumb.webp"
+        img.save(out, format="WEBP")
+        return out
+
+    def get_page_count(self, document_path: Path, mime_type: str) -> int | None:
+        return None
+
+    def extract_metadata(self, document_path: Path, mime_type: str) -> list:
+        return []
+```
+
+### Developing date parser plugins

 Paperless-ngx uses a plugin system for date parsing, allowing you to extend or replace the default date parsing behavior. Plugins are discovered using [Python entry points](https://setuptools.pypa.io/en/latest/userguide/entry_point.html).

-### Creating a Date Parser Plugin
+#### Creating a Date Parser Plugin

 To create a custom date parser plugin, you need to:

@@ -492,7 +734,7 @@ To create a custom date parser plugin, you need to:
 2. Implement the required abstract method
 3. Register your plugin via an entry point

-#### 1. Implementing the Parser Class
+##### 1. Implementing the Parser Class

 Your parser must extend `documents.plugins.date_parsing.DateParserPluginBase` and implement the `parse` method:

@@ -532,7 +774,7 @@ class MyDateParserPlugin(DateParserPluginBase):
        yield another_datetime
 ```

-#### 2. Configuration and Helper Methods
+##### 2. Configuration and Helper Methods

 Your parser instance is initialized with a `DateParserConfig` object accessible via `self.config`. This provides:

@@ -565,11 +807,11 @@ def _filter_date(
    """
 ```

-#### 3. Resource Management (Optional)
+##### 3. Resource Management (Optional)

 If your plugin needs to acquire or release resources (database connections, API clients, etc.), override the context manager methods. Paperless-ngx will always use plugins as context managers, ensuring resources can be released even in the event of errors.

-#### 4. Registering Your Plugin
+##### 4. Registering Your Plugin

 Register your plugin using a setuptools entry point in your package's `pyproject.toml`:

@@ -580,7 +822,7 @@ my_parser = "my_package.parsers:MyDateParserPlugin"

 The entry point name (e.g., `"my_parser"`) is used for sorting when multiple plugins are found. Paperless-ngx will use the first plugin alphabetically by name if multiple plugins are discovered.

-### Plugin Discovery
+#### Plugin Discovery

 Paperless-ngx automatically discovers and loads date parser plugins at runtime. The discovery process:

@@ -591,7 +833,7 @@ Paperless-ngx automatically discovers and loads date parser plugins at runtime.

 If multiple plugins are installed, a warning is logged indicating which plugin was selected.

-### Example: Simple Date Parser
+#### Example: Simple Date Parser

 Here's a minimal example that only looks for ISO 8601 dates:

@@ -623,3 +865,30 @@ class ISODateParserPlugin(DateParserPluginBase):
            if filtered_date is not None:
                yield filtered_date
 ```
+
+## Using Visual Studio Code devcontainer
+
+Another easy way to get started with development is to use Visual Studio
+Code devcontainers. This approach will create a preconfigured development
+environment with all of the required tools and dependencies.
+[Learn more about devcontainers](https://code.visualstudio.com/docs/devcontainers/containers).
+The .devcontainer/vscode/tasks.json and .devcontainer/vscode/launch.json files
+contain more information about the specific tasks and launch configurations (see the
+non-standard "description" field).
+
+To get started:
+
+1. Clone the repository on your machine and open the Paperless-ngx folder in VS Code.
+
+2. VS Code will prompt you with "Reopen in container". Do so and wait for the environment to start.
+
+3. In case your host operating system is Windows:
+   - The Source Control view in Visual Studio Code might show: "The detected Git repository is potentially unsafe as the folder is owned by someone other than the current user." Use "Manage Unsafe Repositories" to fix this.
+   - Git might have detecteded modifications for all files, because Windows is using CRLF line endings. Run `git checkout .` in the containers terminal to fix this issue.
+
+4. Initialize the project by running the task **Project Setup: Run all Init Tasks**. This
+   will initialize the database tables and create a superuser. Then you can compile the front end
+   for production or run the frontend in debug mode.
+
+5. The project is ready for debugging, start either run the fullstack debug or individual debug
+   processes. Yo spin up the project without debugging run the task **Project Start: Run all Services**
--- a/src/documents/tests/test_api_objects.py
+++ b/src/documents/tests/test_api_objects.py
@@ -360,7 +360,7 @@ class TestApiStoragePaths(DirectoriesMixin, APITestCase):
            content_type="application/json",
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data, "path/Something.pdf")
+        self.assertEqual(response.data, "path/Something")

    def test_test_storage_path_respects_none_placeholder_setting(self) -> None:
        """
@@ -390,7 +390,7 @@ class TestApiStoragePaths(DirectoriesMixin, APITestCase):
            content_type="application/json",
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data, "folder/none/Something.pdf")
+        self.assertEqual(response.data, "folder/none/Something")

        with override_settings(FILENAME_FORMAT_REMOVE_NONE=True):
            response = self.client.post(
@@ -399,7 +399,7 @@ class TestApiStoragePaths(DirectoriesMixin, APITestCase):
                content_type="application/json",
            )
        self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data, "folder/Something.pdf")
+        self.assertEqual(response.data, "folder/Something")

    def test_test_storage_path_requires_document_view_permission(self) -> None:
        owner = User.objects.create_user(username="owner")
@@ -447,27 +447,7 @@ class TestApiStoragePaths(DirectoriesMixin, APITestCase):
            content_type="application/json",
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data, "path/Shared.pdf")
-
-    def test_test_storage_path_prefers_existing_filename_extension(self) -> None:
-        document = Document.objects.create(
-            mime_type="image/jpeg",
-            filename="existing/Document.jpeg",
-            title="Something",
-            checksum="123",
-        )
-        response = self.client.post(
-            f"{self.ENDPOINT}test/",
-            json.dumps(
-                {
-                    "document": document.id,
-                    "path": "path/{{ title }}",
-                },
-            ),
-            content_type="application/json",
-        )
-        self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data, "path/Something.jpeg")
+        self.assertEqual(response.data, "path/Shared")

    def test_test_storage_path_exposes_basic_document_context_but_not_sensitive_owner_data(
        self,
@@ -498,12 +478,12 @@ class TestApiStoragePaths(DirectoriesMixin, APITestCase):
            content_type="application/json",
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data, "owner.pdf")
+        self.assertEqual(response.data, "owner")

        for expression, expected in (
-            ("{{ document.content }}", "Top secret content.pdf"),
-            ("{{ document.id }}", f"{document.id}.pdf"),
-            ("{{ document.page_count }}", "2.pdf"),
+            ("{{ document.content }}", "Top secret content"),
+            ("{{ document.id }}", str(document.id)),
+            ("{{ document.page_count }}", "2"),
        ):
            response = self.client.post(
                f"{self.ENDPOINT}test/",
@@ -565,7 +545,7 @@ class TestApiStoragePaths(DirectoriesMixin, APITestCase):
            content_type="application/json",
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data, "Private Correspondent.pdf")
+        self.assertEqual(response.data, "Private Correspondent")

        response = self.client.post(
            f"{self.ENDPOINT}test/",
@@ -580,7 +560,7 @@ class TestApiStoragePaths(DirectoriesMixin, APITestCase):
            content_type="application/json",
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data, "Private Correspondent.pdf")
+        self.assertEqual(response.data, "Private Correspondent")

    def test_test_storage_path_superuser_can_view_private_related_objects(self) -> None:
        owner = User.objects.create_user(username="owner")
@@ -609,7 +589,7 @@ class TestApiStoragePaths(DirectoriesMixin, APITestCase):
            content_type="application/json",
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data, "Private Correspondent.pdf")
+        self.assertEqual(response.data, "Private Correspondent")

    def test_test_storage_path_includes_doc_type_storage_path_and_tags(
        self,
@@ -656,7 +636,7 @@ class TestApiStoragePaths(DirectoriesMixin, APITestCase):
            content_type="application/json",
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data, "Private Type/private/path/Private Tag.pdf")
+        self.assertEqual(response.data, "Private Type/private/path/Private Tag")

        response = self.client.post(
            f"{self.ENDPOINT}test/",
@@ -669,7 +649,7 @@ class TestApiStoragePaths(DirectoriesMixin, APITestCase):
            content_type="application/json",
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data, "Private Type/Private Tag.pdf")
+        self.assertEqual(response.data, "Private Type/Private Tag")

    def test_test_storage_path_includes_custom_fields_for_visible_document(
        self,
@@ -705,7 +685,7 @@ class TestApiStoragePaths(DirectoriesMixin, APITestCase):
            content_type="application/json",
        )
        self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data, "42.pdf")
+        self.assertEqual(response.data, "42")


 class TestBulkEditObjects(APITestCase):
--- a/src/documents/views.py
+++ b/src/documents/views.py
@@ -3290,12 +3290,6 @@ class StoragePathViewSet(PermissionsAwareDocumentCountMixin, ModelViewSet):
        path = serializer.validated_data.get("path")

        result = format_filename(document, path)
-        if result:
-            extension = (
-                Path(str(document.filename)).suffix if document.filename else ""
-            ) or document.file_type
-            result_path = Path(result)
-            result = str(result_path.with_name(f"{result_path.name}{extension}"))
        return Response(result)


--- a/src/locale/en_US/LC_MESSAGES/django.po
+++ b/src/locale/en_US/LC_MESSAGES/django.po
@@ -2,7 +2,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: paperless-ngx\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2026-03-28 20:59+0000\n"
+"POT-Creation-Date: 2026-03-26 14:37+0000\n"
 "PO-Revision-Date: 2022-02-17 04:17\n"
 "Last-Translator: \n"
 "Language-Team: English\n"
@@ -1341,7 +1341,7 @@ msgstr ""
 msgid "Duplicate document identifiers are not allowed."
 msgstr ""

-#: documents/serialisers.py:2587 documents/views.py:3605
+#: documents/serialisers.py:2587 documents/views.py:3599
 #, python-format
 msgid "Documents not found: %(ids)s"
 msgstr ""
@@ -1613,20 +1613,20 @@ msgstr ""
 msgid "Invalid more_like_id"
 msgstr ""

-#: documents/views.py:3617
+#: documents/views.py:3611
 #, python-format
 msgid "Insufficient permissions to share document %(id)s."
 msgstr ""

-#: documents/views.py:3660
+#: documents/views.py:3654
 msgid "Bundle is already being processed."
 msgstr ""

-#: documents/views.py:3717
+#: documents/views.py:3711
 msgid "The share link bundle is still being prepared. Please try again later."
 msgstr ""

-#: documents/views.py:3727
+#: documents/views.py:3721
 msgid "The share link bundle is unavailable."
 msgstr ""

--- a/src/paperless/tests/settings/test_custom_parsers.py
+++ b/src/paperless/tests/settings/test_custom_parsers.py
@@ -79,15 +79,6 @@ class TestRedisSocketConversion:
                ),
                id="celery_style_socket_with_credentials",
            ),
-            # Empty username, password only: unix://:SECRET@/path.sock
-            pytest.param(
-                "unix://:SECRET@/run/redis/paperless.sock",
-                (
-                    "redis+socket://:SECRET@/run/redis/paperless.sock",
-                    "unix://:SECRET@/run/redis/paperless.sock",
-                ),
-                id="redis_py_style_socket_with_password_only",
-            ),
        ],
    )
    def test_redis_socket_parsing(
Author	SHA1	Message	Date
Trenton H	3d0d243057	Merge branch 'dev' into chore/plugin-documentation	2026-03-27 10:18:22 -07:00
Trenton H	7a192d021f	Moves the date parsing plugin section under the extending section	2026-03-23 12:56:43 -07:00
Trenton H	1e30490a46	Adds a section about how the 2 install types can add external plugins	2026-03-23 12:56:38 -07:00
Trenton H	bd9e529a63	Inital documentation updates for developing a plugin	2026-03-23 12:56:34 -07:00