render-engine 2026.6.2a3__tar.gz → 2026.7.1a3__tar.gz

{render_engine-2026.6.2a3 → render_engine-2026.7.1a3}/.github/scripts/publish_prerelease.py

@@ -23,6 +23,8 @@ surrounding project environment:
     uv run --script .github/scripts/publish_prerelease.py selftest
 """
 
+import shlex
+import subprocess
 from datetime import date
 
 import rich_click as click
@@ -55,6 +57,15 @@ def bump(current: str) -> None:
     click.echo(next_version(Version(current), date.today()))
 
 
+@cli.command()
+@click.argument("command")
+def bump_from_command(command: str) -> None:
+    """Execute the given command and then bump the result. Must output to JSON array of values"""
+    cmd_output = subprocess.run(shlex.split(command), timeout=5, capture_output=True, text=True)
+    current_version = max(map(Version, cmd_output.stdout.splitlines()))
+    click.echo(next_version(current_version, date.today()))
+
+
 @cli.command()
 def selftest() -> None:
     """Run offline checks of the version rules."""

{render_engine-2026.6.2a3 → render_engine-2026.7.1a3}/.github/workflows/lint.yml

@@ -4,20 +4,23 @@ on:
     branches: [main]
   workflow_dispatch:
 
-permissions:
-  contents: write
-  pull-requests: write
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 
 jobs:
   lint-python:
     name: Format and Lint Python
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.1
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
-          fetch-depth: 0
+          persist-credentials: false
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
         with:
           python-version: 3.14
       - name: Install dependencies
@@ -29,8 +32,10 @@ jobs:
     name: Lint Markdown
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.1
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: lint-test
-        uses: DavidAnson/markdownlint-cli2-action@v23
+        uses: DavidAnson/markdownlint-cli2-action@ded1f9488f68a970bc66ea5619e13e9b52e601cd # v23.2.0
         with:
           globs: '**/*.md'

{render_engine-2026.6.2a3 → render_engine-2026.7.1a3}/.github/workflows/publish-prerelease.yml

@@ -11,7 +11,8 @@ on:
         default: true
 
 permissions:
-  contents: write
+  contents: write # gives access to apply the tag
+  actions: write # permission to run the workflow for publish
 
 concurrency:
   group: release-publish
@@ -26,7 +27,7 @@ jobs:
        contains(github.event.pull_request.labels.*.name, 'release'))
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false   # checkout only fetches the publish script
       - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
@@ -41,15 +42,11 @@ jobs:
           DRY_RUN: ${{ github.event.inputs.dry_run || 'false' }}
         run: |
           # Latest release in the repo; the bump script computes the next one.
-          latest="$(gh release list --json name --jq '.[].name' \
-            | grep -E '^[0-9]{4}\.[0-9]+\.[0-9]+([ab][0-9]+)?$' \
-            | sort -V | tail -1)"
-          version="$(uv run --script .github/scripts/publish_prerelease.py bump "$latest")"
-          echo "Latest tag: $latest -> next: $version"
-          echo "version=$version" >> "$GITHUB_OUTPUT"
+          version=$(uv run --script .github/scripts/publish_prerelease.py bump-from "gh release list --json name --jq '.[].name'")
+          echo "Next Version: $version"
 
           if [ "$DRY_RUN" = "true" ]; then
-            echo "DRY RUN — would publish $version"
+            echo "DRY RUN — Next Version would be: $version"
           else
             gh release create "$version" --prerelease --generate-notes --title "$version"
             gh workflow run publish.yml --ref "$version"

{render_engine-2026.6.2a3 → render_engine-2026.7.1a3}/.github/workflows/publish.yml

@@ -12,6 +12,7 @@ jobs:
     uses: ./.github/workflows/test.yml
     permissions:
       contents: read
+      pull-requests: write # This is needed for the coverage badge. Will fail on startup without it.
 
   build:
     needs: test
@@ -21,7 +22,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout source
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
 
@@ -34,7 +35,7 @@ jobs:
       - name: Build distributions
         run: uv build
       - name: Upload artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           path: ./dist
           name: render-engine
@@ -52,4 +53,4 @@ jobs:
           path: ./dist
           name: render-engine
       - name: Push to PyPI
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

{render_engine-2026.6.2a3 → render_engine-2026.7.1a3}/.github/workflows/scorecard.yml

@@ -32,12 +32,12 @@ jobs:
 
     steps:
       - name: "Checkout code"
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v4.1.1
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
 
       - name: "Run analysis"
-        uses: ossf/scorecard-action@05b42c624433fc40578a4040d5cf5e36ddca8cde # v2.4.2
+        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
         with:
           results_file: results.sarif
           results_format: sarif
@@ -59,7 +59,7 @@ jobs:
       # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
       # format to the repository Actions tab.
       - name: "Upload artifact"
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: SARIF
           path: results.sarif
@@ -68,6 +68,6 @@ jobs:
       # Upload the results to GitHub's code scanning dashboard (optional).
       # Commenting out will disable upload of results to your repo's Code Scanning dashboard
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@v4
+        uses: github/codeql-action/upload-sarif@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
         with:
           sarif_file: results.sarif

{render_engine-2026.6.2a3 → render_engine-2026.7.1a3}/.github/workflows/test.yml

@@ -13,12 +13,20 @@ on:
       - "pyproject.toml"
       - "requirements.txt"
 
+permissions:
+  contents: read
+
 jobs:
   gen-coverage-badge:
+    name: Generate Coverage Badge
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
-      - uses: actions/checkout@v6
-      - uses: astral-sh/setup-uv@v7
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
           python-version: "3.14"
           enable-cache: true
@@ -30,32 +38,35 @@ jobs:
         run: |
           uvx --with "genbadge[coverage]" genbadge coverage -i coverage.xml
       - name: Commit Badge
-        uses: stefanzweifel/git-auto-commit-action@v7
+        uses: stefanzweifel/git-auto-commit-action@4a55954c782fc1ea30b9056cd3e7a2b40ca8887d # v7.2.0
         with:
           commit_message: Update coverage badge [skip ci]
           file_pattern: coverage.svg
 
   test-against-python-matrix:
-    # Only test all the supported versions when a pull request is made or the workflow is called
-    if: ${{github.event_name == 'workflow_call'}} || ${{github.event_name == 'pull_request'}}
+    name: Test on all supported Python versions
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        # 3.14 is not run here because it is for the latest OK check so it would be redundant.
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.15"]
       fail-fast: true
     steps:
-      - uses: actions/checkout@v6.0.1
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: true # caching dependencies
       - name: Run tests
         run: |
-          uv run --dev pytest tests
+          uv run --dev --python ${{ matrix.python-version }} pytest tests
 
   test-against-latest-os:
     # Always run against the latest version on both Windows, Linux, MacOS
+    name: Test against latest OS
     if: github.event.pull_request.user.login != 'dependabot[bot]'
     strategy:
       matrix:
@@ -63,11 +74,13 @@ jobs:
       fail-fast: true
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v6.0.1
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
         with:
           python-version: "3.14"
           enable-cache: true # caching dependencies
       - name: run tests
-        run: uv run --dev pytest tests
+        run: uv run --dev --python 3.14 pytest tests

{render_engine-2026.6.2a3 → render_engine-2026.7.1a3}/.github/workflows/ty.yml

@@ -1,12 +1,15 @@
 name: Type Check
 
+permissions:
+  contents: read
+
 on:
   push:
     branches:
       - main
   pull_request:
     branches:
-        - main
+      - main
     paths:
       - "src/**"
       - "pyproject.toml"
@@ -16,7 +19,9 @@ jobs:
   ty_check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6.0.1
-      - uses: astral-sh/setup-uv@v7
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
       - name: Run type (ty) check
         run: uv run ty check src

render_engine-2026.7.1a3/.github/workflows/zizmor.yml

@@ -0,0 +1,28 @@
+name: GitHub Actions Security Analysis with zizmor 🌈
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["**"]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  zizmor:
+    name: Zizmor Check
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write # required for advanced security policy
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Run zizmor 🌈
+        uses: zizmorcore/zizmor-action@192e21d79ab29983730a13d1382995c2307fbcaa # v0.5.7

render_engine-2026.7.1a3/.pre-commit-config.yaml

@@ -0,0 +1,47 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.3.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.15.1
+    hooks:
+      # Run the linter.
+      - id: ruff-check
+        args: [--fix]
+      # Run the formatter.
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: ty-check
+        name: ty
+        entry: uv run ty check src/render_engine
+        language: system
+        types: [python]
+        pass_filenames: false
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.6.0
+    hooks:
+      - id: markdownlint-cli2
+        args: ["*.md", "docs/**/*.md"]
+  - repo: https://github.com/kjaymiller/pin-versions
+    rev: 2026.3.6
+    hooks:
+      - id: pin-versions
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    # Zizmor version.
+    rev: v1.26.1
+    hooks:
+      # Run the linter.
+      - id: zizmor
+  - repo: local
+    hooks:
+      - id: deptry
+        name: deptry
+        entry: uv run deptry src
+        language: system
+        always_run: true
+        pass_filenames: false

{render_engine-2026.6.2a3 → render_engine-2026.7.1a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: render_engine
-Version: 2026.6.2a3
+Version: 2026.7.1a3
 Summary: A Flexible Static Site Generator for Python
 Project-URL: homepage, https://github.com/render-engine/render-engine/
 Project-URL: repository, https://github.com/render-engine/render-engine/

{render_engine-2026.6.2a3 → render_engine-2026.7.1a3}/docs/docs/contributing/CONTRIBUTING.md

@@ -78,7 +78,7 @@ Once you've been [assigned an issue][being-assigned], you can begin working on a
 ### Dockerfile
 
 Our DevContainer is built primarily from a dockerfile. You can build from our Dockerfile directly which would
-ensure the manual configuration is ran (You will still need to fork and clone).
+ensure the manual configuration is run (You will still need to fork and clone).
 
 ## Verify Before Submitting
 
@@ -92,21 +92,14 @@ all supported versions.
 
 ## TODOs
 
-Todos are not encouraged all the time but if necessary please indicate any todos with the `# TODO` prefix.
-We use [todo-to-issue] as a GitHub Action to create issues from TODOs.
-
-When a PR containing `# TODO` comments is opened, a bot will comment suggesting a maintainer
-add the **todo-to-issue** label. Once a maintainer adds the label, the action will:
-
-1. Create GitHub issues for each TODO
-2. Update the TODO comments in your code with the issue number and link
-3. Commit the changes back to your PR branch
-
-The label is removed automatically afterward and can be re-applied if new TODOs are added.
+To-dos are not encouraged all the time but if necessary please indicate any todos with the `# TODO` prefix.
+Before submitting a PR with a `# TODO` please make sure to open the corresponding [issue in GitHub] and include
+the link as part of the `# TODO` comment. PRs opened that include a `# TODO` comment without a corresponding
+GitHub issue will be requested to create the issue and update the comment prior to merge.
 
 ## Contributing to Documentation
 
-Render Engine uses [readthedocs][readthedocs] in combination with [MkDocs][uv[Material for MkDocs][material],
+Render Engine uses [readthedocs][readthedocs] in combination with [MkDocs], [Material for MkDocs],
 and [mkdocsstrings][mkdocsstrings] to generate documentation.
 
 - 📝 update docstrings for functions, methods, and classes.
@@ -119,7 +112,7 @@ Test your docs changes by running the command **FROM THE PROJECT ROOT**.
 You can start the documentation server on the default port (8000):
 
 ```sh
-just docs 
+just docs
 ```
 
 Or, you can specify a custom port:
@@ -149,7 +142,7 @@ This attestation should mean that the AI model is included as a co-Author of the
 
 The AI assistant is your copilot. You are still responsible for code changes submitted.
 Low quality contributions or code that cannot be defended by the USER (not their AI model)
-will result in issues/prs being immediately closed.
+will result in issues/PRs being immediately closed.
 Multiple low quality contributions will result in your user account being banned from contribution.
 
 [AI attestation]: #ai-attestation
@@ -161,11 +154,11 @@ Multiple low quality contributions will result in your user account being banned
 [dev-container]: https://render-engine.readthedocs.io/en/latest/contributing/environment_setup#developing-locally
 [codespaces]: https://render-engine.readthedocs.io/en/latest/contributing/environment_setup#using-codespaces
 [readthedocs]: https://readthedocs.org
-[mkdocs]: https://www.mkdocs.org
-[material]: https://squidfunk.github.io/mkdocs-material/
+[MkDocs]: https://www.mkdocs.org
+[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/
 [mkdocsstrings]: https://mkdocsstrings.readthedocs.io/en/latest/
 [code of conduct]: https://github.com/render-engine/render-engine/blob/main/.github/CODE_OF_CONDUCT.md
 [docs-contributing]: https://render-engine.readthedocs.io/en/latest/contributing/CONTRIBUTING/#instead-of-making-a-change-in-render-engines-code-consider
-[todo-to-issue]: https://github.com/marketplace/actions/todo-to-issue
 [Wait to be assigned an issue]: #wait-to-be-assigned-issues
 [Formatting your PR]: #formatting-your-pr
+[issue in GitHub]: https://github.com/render-engine/render-engine/issues/new/choose

{render_engine-2026.6.2a3 → render_engine-2026.7.1a3}/docs/docs/contributing/github-actions-file-patterns.md

@@ -201,27 +201,6 @@ paths:
   - "requirements.txt"
 ```
 
-### Documentation Labels
-
-From `.github/labeler.yml`:
-
-```yaml
-documentation:
-  - changed-files:
-    - any-glob-to-any-file: ['docs/**', 'guides/**']
-    - any-glob-to-any-file: '**/*.md'
-```
-
-### Source Code Labels
-
-```yaml
-source:
-  - all:
-    - changed-files:
-      - any-glob-to-any-file: 'src/**/*'
-      - all-globs-to-all-files: '!src/docs/*'
-```
-
 ## Troubleshooting
 
 ### Workflow Not Running When Expected

{render_engine-2026.6.2a3 → render_engine-2026.7.1a3}/docs/docs/site.md

@@ -40,6 +40,11 @@ Site(
     render_xml_site_map: bool = False,
     slug_only_urls: bool = False,
     site_vars: object | dict = SENTINEL,
+    static_include_patterns: set[str] | None = None,
+    static_exclude_patterns: set[str] | None = None,
+    static_exclude_dirs: set[str] | None = None,
+    static_include_dirs: set[str] | None = None,
+    include_static_in_site_map: bool = False,
 ) -> None:
     pass
 ```
@@ -58,6 +63,11 @@ The `Site` constructor takes the following keyword arguments:
 | `render_xml_site_map`  | `bool`       | When True render the site map as an XML file. Default: False.                            |
 | `slug_only_urls`       | `bool`       | Default value for Page objects rendering slub only URLS. Default: False                  |
 | `site_vars`            | `dict`       | The site_vars dictionary containing data to be passed to all templates during rendering. |
+| `static_include_patterns` | `set[str] \| None` | Glob patterns a static file must match to be included. Default: `None` (no filtering). |
+| `static_exclude_patterns` | `set[str] \| None` | Glob patterns that exclude a static file even if it matched an include pattern. Default: `None`. |
+| `static_exclude_dirs`  | `set[str] \| None` | Directory names to skip entirely under any static path. Default: `None`. |
+| `static_include_dirs`  | `set[str] \| None` | Subdirectory paths that override `static_exclude_dirs` for matching subdirectories. Default: `None`. |
+| `include_static_in_site_map` | `bool` | When True, static files are added to the site map. Default: `False`. |
 <!-- markdownlint-enable MD056 -->
 <!-- markdownlint-enable MD060 -->
 

render_engine-2026.7.1a3/docs/docs/site_map.md

@@ -0,0 +1,151 @@
+---
+title: "SiteMap Objects"
+description: "Overview of the SiteMap"
+date: September 27, 2025
+tags: ["site-map"]
+---
+Prior to rendering the `Site` Render Engine will create a `SiteMap` containing searchable information
+about all of the `Collection` and `Page` objects it has.
+
+## Searching the `SiteMap`
+
+To search the `SiteMap` use the `find` method.
+
+```python
+    def find(
+        self,
+        value: str,
+        attr: str = "slug",
+        collection: str = None,
+        full_search: bool = False,
+    ) -> SiteMapEntry | None:
+```
+
+### Parameters
+
+- `value`: The value to search for
+- `attr`: Optional attribute to search by. Options are `slug`, `title`, `path_name`. Defaults to `slug`.
+- `collection`: Limit the search to a single `Collection`. Defaults to `None`.
+- `full_search`: Search all `Page` and `Collection` objects. Defaults to `False`.
+
+Notes:
+
+1. If `collection` is set the search will be limited to that `Collection` object regardless of whether
+`full_search` is set.
+2. If `full_search` is set it will return the first match found. If you have 3 pages with the same `slug`,
+1 not in a `Collection` and 2 others in different `Collection` objects, the first one defined will be the
+one found.
+
+## Generating an HTML site map
+
+The `SiteMap` object has an `html` property that will return an HTML sitemap with _absolute_ URLs with the
+`Site`'s `SITE_URL`.
+
+As a convenience, Render Engine will generate a site map page if the `Site` property of `render_html_site_map`
+is `True` (it defaults to `False`.) Please note that this will not be templated. Should you wish the generated
+site map to be on a template you can add the following to your app:
+
+```python
+@app.page
+class SiteMapPage(Page):
+    template = "site_map_template.html"
+    content = "{{ site_map.html }}"
+    skip_site_map = True
+```
+
+Please note the `skip_site_map = True` to avoid having a self-referential link to the site map.
+
+## Generating an XML site map
+
+To have your site generate an XML site map set the `render_xml_site_map` property of your `Site` object
+to `True` (defaults to `False`.) This will create the `site_map.xml` file in the root output directory
+of your site.
+
+## Including Static Files in the Site Map
+
+By default, the `SiteMap` also includes an entry for every static file found in
+the `Site`'s `static_paths` (e.g. images, CSS, JS, and any other files copied
+from your static directories). This means static assets show up in both the
+generated HTML site map and the XML site map alongside your `Page` and
+`Collection` entries.
+
+Static file entries use the URL they are ultimately served at, based on where
+`static_paths` are copied to in the output directory. For example, a file at
+`static/images/logo.png` will appear in the site map with the URL
+`/static/images/logo.png`.
+
+If you want to add static files to a `SiteMap` manually — for example, when
+working with the `SiteMap` object directly rather than through `Site.render()`
+— use the `add_static_files` method:
+
+```python
+def add_static_files(
+    self,
+    static_paths: Iterable[str | Path],
+    include_patterns: Iterable[str] | None = None,
+    exclude_patterns: Iterable[str] | None = None,
+    exclude_dirs: Iterable[str] | None = None,
+    include_dirs: Iterable[str] | None = None,
+) -> None:
+```
+
+<!--  markdownlint-disable-next-line MD024 -->
+### Parameters
+
+- `static_paths`: An iterable of directories (as `str` or `Path`) to walk for
+  static files. This is normally `Site.static_paths`, the same set of
+  directories copied to the output folder.
+- `include_patterns`: An iterable of glob patterns a file must match to be
+  included in the site map. Defaults to `None`, meaning no filtering — every
+  file is included.
+- `exclude_patterns`: An iterable of glob patterns that exclude a file even
+  if it matched an `include_patterns` entry. Defaults to `None`, excluding
+  nothing.
+- `exclude_dirs`: An iterable of directory names to skip entirely, matched
+  against any path segment relative to the static directory. Defaults to
+  `None`, excluding nothing.
+- `include_dirs`: An iterable of subdirectory paths that override
+  `exclude_dirs`, forcing inclusion for matching subdirectories even if a
+  parent directory was excluded. Defaults to `None`, meaning no override.
+
+Note: `SiteMap.update()` will automatically call `add_static_files` for you
+if the `SiteMap` has `static_paths` set and `include_static_in_site_map` is
+`True`, using `Site.static_include_patterns`, `Site.static_exclude_patterns`,
+`Site.static_exclude_dirs`, and `Site.static_include_dirs` — so in most cases
+you won't need to call this directly, or configure filtering anywhere except
+on your `Site` object. Setting `include_static_in_site_map=False` on `Site`
+excludes static files from the site map entirely, without affecting whether
+they are copied to the output directory. For example:
+
+```python
+site = Site(
+    static_paths={"static"},
+    static_include_patterns=("*.css", "*.js", "*.png"),
+    static_exclude_dirs=("drafts",),
+    static_include_dirs=("drafts/public",),
+    include_static_in_site_map=True,
+)
+```
+
+## The `SiteMapEntry` object
+
+The `SiteMap` is a collection of `SiteMapEntry` objects. Each `SiteMapEntry` has the following attributes
+and properties:
+
+### Attributes and Properties
+
+- `slug` - The `slug` for the referenced `Page` or `Collection`.
+- `title` - The `title` for the referenced `Page` or `Collection`.
+- `path_name` - The `path_name` for the referenced `Page` or `Collection`.
+- `entries` - A list of `SiteMapEntry` objects representing the `Page` objects in a given `Collection`.
+for a `Page` this will be an empty `list`.
+- `url_for` - This property will provide the _relative_ URL for the given entry.
+
+## The `StaticSiteMapEntry` object
+
+`StaticSiteMapEntry` is a subclass of `SiteMapEntry` used to represent static
+files (images, CSS, JS, etc.) in the site map, rather than `Page` or
+`Collection` objects. It shares the same `url_for` property and `__str__`
+behavior as `SiteMapEntry`, so it can be used interchangeably anywhere a
+`SiteMapEntry` is expected — for example, when iterating over a `SiteMap` or
+using `SiteMap.find()`.