From 23a11a3e624a4f2715fa6d79f9af8701a1b05cde Mon Sep 17 00:00:00 2001
From: SimonJasansky <s.jasansky@outlook.de>
Date: Mon, 25 Aug 2025 11:55:46 +0000
Subject: [PATCH 01/23] feat: support mkdocs and add automatic docs deployment
 for GitHub Pages

---
 README.md                                     |  8 +++
 copier.yml                                    |  9 ++++
 template/.gitignore.jinja                     | 11 ++++
 template/pyproject.toml.jinja                 | 43 +++++++++++++++
 ...tool != 'None' %}docs.yml{% endif %}.jinja | 52 ++++++++++++++++++
 .../index.md.jinja                            | 21 ++++++++
 .../reference/index.md.jinja                  |  5 ++
 ... == 'mkdocs' %}mkdocs.yml{% endif %}.jinja | 53 +++++++++++++++++++
 8 files changed, 202 insertions(+)
 create mode 100644 template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool != 'None' %}docs.yml{% endif %}.jinja
 create mode 100644 template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/index.md.jinja
 create mode 100644 template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/reference/index.md.jinja
 create mode 100644 template/{% if documentation_tool == 'mkdocs' %}mkdocs.yml{% endif %}.jinja

diff --git a/README.md b/README.md
index 5f17442b..068fd5b4 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@ A modern [Copier template](https://github.com/copier-org/copier) for scaffolding
 - ♻️ Continuous integration with [GitHub Actions](https://docs.github.com/en/actions) or [GitLab CI/CD](https://docs.gitlab.com/ee/ci/)
 - 🧪 Test coverage with [Coverage.py](https://github.com/nedbat/coveragepy)
 - 🧰 Dependency updates with [Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates)
+- 📚 Documentation with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) or [pdoc](https://pdoc.dev/)
 
 ## ✨ Using
 
@@ -91,6 +92,13 @@ To migrate a project from Cookiecutter to Copier, follow these steps:
 
 5. Create a PR from your branch, review it, and merge it!
 
+## 📚 Generate Docs
+
+If you are using GitHub as your repository host and choose one of the supported documentation frameworks, your docs will be published automatically to GitHub Pages. They will be available at `https://<username>.github.io/<repository>`.
+
+> [!TIP]
+> Ensure the source for GitHub Pages is set to "GitHub Actions" in your repository settings under **Settings** → **Pages**. For more details, see [Configuring a publishing source for your GitHub Pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site).
+
 ## Contributing
 
 <details>
diff --git a/copier.yml b/copier.yml
index bb0c82da..2169581d 100644
--- a/copier.yml
+++ b/copier.yml
@@ -91,6 +91,15 @@ with_typer_cli:
   help: Does your {{ project_type }} need a Typer CLI?
   default: false
 
+documentation_tool:
+  type: str
+  help: Which documentation tool do you want to use for your {{ project_type }}?
+  choices:
+    MkDocs (Material theme): mkdocs
+    pdoc: pdoc
+    None: None
+  default: mkdocs
+
 project_name_kebab_case:
   when: false
   default: "{{ project_name | lower | replace(' ', '-') }}"
diff --git a/template/.gitignore.jinja b/template/.gitignore.jinja
index 253d2bad..fac8ee4a 100644
--- a/template/.gitignore.jinja
+++ b/template/.gitignore.jinja
@@ -69,3 +69,14 @@ uv.lock
 
 # VS Code
 .vscode/
+{%- if documentation_tool == 'mkdocs' %}
+
+# MkDocs
+site/
+{%- endif %}
+
+{%- if documentation_tool == 'pdoc' %}
+
+# pdoc
+docs/
+{%- endif %}
diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja
index 712dd299..57dd7343 100644
--- a/template/pyproject.toml.jinja
+++ b/template/pyproject.toml.jinja
@@ -36,7 +36,13 @@ source = "{{ project_url }}"
 changelog = "{{ project_url.rstrip('/') }}/{% if ci == 'gitlab' %}-/{% endif %}blob/main/CHANGELOG.md"
 {%- endif %}
 releasenotes = "{{ project_url.rstrip('/') }}/{% if ci == 'gitlab' %}-/{% endif %}releases"
+{%- if documentation_tool != 'None' %}
+{%- if ci == 'github' %}
+documentation = "https://{{ project_url.split('/')[-2] }}.github.io/{{ project_url.split('/')[-1] }}"
+{%- else %}
 documentation = "{{ project_url }}"
+{%- endif %}
+{%- endif %}
 issues = "{{ project_url.rstrip('/') }}/{% if ci == 'gitlab' %}-/{% endif %}issues"
 
 [dependency-groups]  # https://docs.astral.sh/uv/concepts/projects/dependencies/#development-dependencies
@@ -49,7 +55,12 @@ dev = [
   "ipython (>=8.18.0)",
   "ipywidgets (>=8.1.2)",
   "mypy (>=1.14.1)",
+  {%- if documentation_tool == 'mkdocs' %}
+  "mkdocs-material (>=9.5.21)",
+  "mkdocstrings[python] (>=0.26.2)",
+  {%- elif documentation_tool == 'pdoc' %}
   "pdoc (>=15.0.1)",
+  {%- endif %}
   {%- if project_type == 'package' %}
   "poethepoet (>=0.32.1)",
   {%- endif %}
@@ -207,8 +218,12 @@ type = "simple"
     cmd = "echo 'Serving app (placeholder)...'"
 {%- endif %}
 
+{%- if documentation_tool != 'None' %}
   [tool.poe.tasks.docs]
   help = "Generate this {{ project_type }}'s docs"
+  {%- if documentation_tool == 'mkdocs' %}
+  cmd = "mkdocs build"
+  {%- elif documentation_tool == 'pdoc' %}
   cmd = """
     pdoc
       --docformat $docformat
@@ -227,6 +242,34 @@ type = "simple"
     name = "outputdirectory"
     options = ["--output-directory"]
     default = "docs"
+  {%- endif %}
+
+  [tool.poe.tasks.docs-serve]
+  help = "Serve the docs locally"
+  {%- if documentation_tool == 'mkdocs' %}
+  cmd = "mkdocs serve"
+  {%- elif documentation_tool == 'pdoc' %}
+  cmd = """
+    pdoc
+      --docformat numpy
+      --host $host
+      --port $port
+      {{ project_name_snake_case }}
+    """
+
+    [[tool.poe.tasks.docs-serve.args]]
+    help = "Bind socket to this host (default: localhost)"
+    name = "host"
+    options = ["--host"]
+    default = "localhost"
+
+    [[tool.poe.tasks.docs-serve.args]]
+    help = "Bind socket to this port (default: 8080)"
+    name = "port"
+    options = ["--port"]
+    default = "8080"
+  {%- endif %}
+{%- endif %}
 
   [tool.poe.tasks.lint]
   help = "Lint this {{ project_type }}"
diff --git a/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool != 'None' %}docs.yml{% endif %}.jinja b/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool != 'None' %}docs.yml{% endif %}.jinja
new file mode 100644
index 00000000..c8a5accc
--- /dev/null
+++ b/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool != 'None' %}docs.yml{% endif %}.jinja	
@@ -0,0 +1,52 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        
+      - name: Set up Python
+        run: uv python install {{ python_version }}
+        
+      - name: Install dependencies
+        run: uv sync --group dev
+        
+      - name: Build docs
+        run: uv run poe docs
+      
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+        
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: {% if documentation_tool == 'mkdocs' %}site{% else %}docs{% endif %}
+          
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ "{{" }} steps.deployment.outputs.page_url {{ "}}" }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
\ No newline at end of file
diff --git a/template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/index.md.jinja b/template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/index.md.jinja
new file mode 100644
index 00000000..9716c88f
--- /dev/null
+++ b/template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/index.md.jinja	
@@ -0,0 +1,21 @@
+# {{ project_name }}
+
+{{ project_description }}
+
+## Installation
+
+```bash
+pip install {{ project_name_kebab_case }}
+```
+
+## Quick Start
+
+```python
+import {{ project_name_snake_case }}
+
+# Your code here
+```
+
+## API Reference
+
+See the [API Reference](reference/index.md) for detailed documentation.
diff --git a/template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/reference/index.md.jinja b/template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/reference/index.md.jinja
new file mode 100644
index 00000000..f24e3ece
--- /dev/null
+++ b/template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/reference/index.md.jinja	
@@ -0,0 +1,5 @@
+{% if documentation_tool == 'mkdocs' -%}
+# API Reference
+
+::: {{ project_name_snake_case }}
+{%- endif %}
diff --git a/template/{% if documentation_tool == 'mkdocs' %}mkdocs.yml{% endif %}.jinja b/template/{% if documentation_tool == 'mkdocs' %}mkdocs.yml{% endif %}.jinja
new file mode 100644
index 00000000..5d6c0262
--- /dev/null
+++ b/template/{% if documentation_tool == 'mkdocs' %}mkdocs.yml{% endif %}.jinja	
@@ -0,0 +1,53 @@
+{% if documentation_tool == 'mkdocs' -%}
+site_name: {{ project_name }}
+site_description: {{ project_description }}
+site_url: {{ project_url }}
+repo_url: {{ project_url }}
+repo_name: {{ project_url.split('/')[-2:] | join('/') }}
+
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.highlight
+    - search.share
+    - content.code.copy
+  palette:
+    - scheme: default
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+nav:
+  - Home: index.md
+  - API Reference: reference/
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: numpy
+            show_source: true
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+{%- endif %}

From d63c316caca80a449caea93ca71872454fddea84 Mon Sep 17 00:00:00 2001
From: SimonJasansky <s.jasansky@outlook.de>
Date: Wed, 27 Aug 2025 14:41:48 +0000
Subject: [PATCH 02/23] feat: address PR comments

remove pdoc, add docs badge to README, reduce redundant code and minimized pre-set options in mkdocs.yaml
---
 copier.yml                                    | 10 +---
 template/.gitignore.jinja                     |  8 +--
 template/README.md.jinja                      |  2 +-
 template/pyproject.toml.jinja                 | 59 +------------------
 ...entation_tool %}docs.yml{% endif %}.jinja} | 24 +++-----
 .../index.md.jinja                            |  3 +
 .../index.md.jinja                            |  3 +
 ...ntation_tool %}mkdocs.yml{% endif %}.jinja | 28 +++++++++
 .../reference/index.md.jinja                  |  5 --
 ... == 'mkdocs' %}mkdocs.yml{% endif %}.jinja | 53 -----------------
 10 files changed, 49 insertions(+), 146 deletions(-)
 rename template/{% if ci == 'github' %}.github{% endif %}/workflows/{{% if documentation_tool != 'None' %}docs.yml{% endif %}.jinja => {% if documentation_tool %}docs.yml{% endif %}.jinja} (69%)
 rename template/{{% if documentation_tool == 'mkdocs' %}docs{% endif %} => {% if documentation_tool %}docs{% endif %}}/index.md.jinja (85%)
 create mode 100644 template/{% if documentation_tool %}docs{% endif %}/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja
 create mode 100644 template/{% if documentation_tool %}mkdocs.yml{% endif %}.jinja
 delete mode 100644 template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/reference/index.md.jinja
 delete mode 100644 template/{% if documentation_tool == 'mkdocs' %}mkdocs.yml{% endif %}.jinja

diff --git a/copier.yml b/copier.yml
index 2169581d..331be5da 100644
--- a/copier.yml
+++ b/copier.yml
@@ -92,13 +92,9 @@ with_typer_cli:
   default: false
 
 documentation_tool:
-  type: str
-  help: Which documentation tool do you want to use for your {{ project_type }}?
-  choices:
-    MkDocs (Material theme): mkdocs
-    pdoc: pdoc
-    None: None
-  default: mkdocs
+  type: bool
+  help: Do you want to set up documentation for your {{ project_type }} using MkDocs?
+  default: true
 
 project_name_kebab_case:
   when: false
diff --git a/template/.gitignore.jinja b/template/.gitignore.jinja
index fac8ee4a..785e9f0d 100644
--- a/template/.gitignore.jinja
+++ b/template/.gitignore.jinja
@@ -69,14 +69,8 @@ uv.lock
 
 # VS Code
 .vscode/
-{%- if documentation_tool == 'mkdocs' %}
+{%- if documentation_tool %}
 
 # MkDocs
 site/
 {%- endif %}
-
-{%- if documentation_tool == 'pdoc' %}
-
-# pdoc
-docs/
-{%- endif %}
diff --git a/template/README.md.jinja b/template/README.md.jinja
index 4c4487f4..96f74a24 100644
--- a/template/README.md.jinja
+++ b/template/README.md.jinja
@@ -1,4 +1,4 @@
-[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTE3IDE2VjdsLTYgNU0yIDlWOGwxLTFoMWw0IDMgOC04aDFsNCAyIDEgMXYxNGwtMSAxLTQgMmgtMWwtOC04LTQgM0gzbC0xLTF2LTFsMy0zIi8+PC9zdmc+)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url={{ project_url }}){% if ci == 'github' %} [![Open in GitHub Codespaces](https://img.shields.io/static/v1?label=GitHub%20Codespaces&message=Open&color=blue&logo=github)](https://github.com/codespaces/new/{{ project_url.replace("https://github.com/", "") }}){% endif %}
+[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTE3IDE2VjdsLTYgNU0yIDlWOGwxLTFoMWw0IDMgOC04aDFsNCAyIDEgMXYxNGwtMSAxLTQgMmgtMWwtOC04LTQgM0gzbC0xLTF2LTFsMy0zIi8+PC9zdmc+)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url={{ project_url }}){% if ci == 'github' %} [![Open in GitHub Codespaces](https://img.shields.io/static/v1?label=GitHub%20Codespaces&message=Open&color=blue&logo=github)](https://github.com/codespaces/new/{{ project_url.replace("https://github.com/", "") }}){% endif %}{% if documentation_tool and ci == 'github' %} [![Documentation](https://img.shields.io/static/v1?label=Documentation&message=View&color=blue&logo=read-the-docs)](https://{{ project_url.split('/')[-2] }}.github.io/{{ project_url.split('/')[-1] }}){% endif %}
 
 # {{ project_name }}
 
diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja
index 57dd7343..b7620249 100644
--- a/template/pyproject.toml.jinja
+++ b/template/pyproject.toml.jinja
@@ -55,11 +55,11 @@ dev = [
   "ipython (>=8.18.0)",
   "ipywidgets (>=8.1.2)",
   "mypy (>=1.14.1)",
-  {%- if documentation_tool == 'mkdocs' %}
+  {%- if documentation_tool %}
   "mkdocs-material (>=9.5.21)",
+  {%- if project_type == 'package' %}
   "mkdocstrings[python] (>=0.26.2)",
-  {%- elif documentation_tool == 'pdoc' %}
-  "pdoc (>=15.0.1)",
+  {%- endif %}
   {%- endif %}
   {%- if project_type == 'package' %}
   "poethepoet (>=0.32.1)",
@@ -218,59 +218,6 @@ type = "simple"
     cmd = "echo 'Serving app (placeholder)...'"
 {%- endif %}
 
-{%- if documentation_tool != 'None' %}
-  [tool.poe.tasks.docs]
-  help = "Generate this {{ project_type }}'s docs"
-  {%- if documentation_tool == 'mkdocs' %}
-  cmd = "mkdocs build"
-  {%- elif documentation_tool == 'pdoc' %}
-  cmd = """
-    pdoc
-      --docformat $docformat
-      --output-directory $outputdirectory
-      {{ project_name_snake_case }}
-    """
-
-    [[tool.poe.tasks.docs.args]]
-    help = "The docstring style (default: numpy)"
-    name = "docformat"
-    options = ["--docformat"]
-    default = "numpy"
-
-    [[tool.poe.tasks.docs.args]]
-    help = "The output directory (default: docs)"
-    name = "outputdirectory"
-    options = ["--output-directory"]
-    default = "docs"
-  {%- endif %}
-
-  [tool.poe.tasks.docs-serve]
-  help = "Serve the docs locally"
-  {%- if documentation_tool == 'mkdocs' %}
-  cmd = "mkdocs serve"
-  {%- elif documentation_tool == 'pdoc' %}
-  cmd = """
-    pdoc
-      --docformat numpy
-      --host $host
-      --port $port
-      {{ project_name_snake_case }}
-    """
-
-    [[tool.poe.tasks.docs-serve.args]]
-    help = "Bind socket to this host (default: localhost)"
-    name = "host"
-    options = ["--host"]
-    default = "localhost"
-
-    [[tool.poe.tasks.docs-serve.args]]
-    help = "Bind socket to this port (default: 8080)"
-    name = "port"
-    options = ["--port"]
-    default = "8080"
-  {%- endif %}
-{%- endif %}
-
   [tool.poe.tasks.lint]
   help = "Lint this {{ project_type }}"
   cmd = """
diff --git a/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool != 'None' %}docs.yml{% endif %}.jinja b/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool %}docs.yml{% endif %}.jinja
similarity index 69%
rename from template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool != 'None' %}docs.yml{% endif %}.jinja
rename to template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool %}docs.yml{% endif %}.jinja
index c8a5accc..ad8c2312 100644
--- a/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool != 'None' %}docs.yml{% endif %}.jinja	
+++ b/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool %}docs.yml{% endif %}.jinja	
@@ -14,22 +14,20 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  build:
+  build-and-deploy:
+    if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ "{{" }} steps.deployment.outputs.page_url {{ "}}" }}
     steps:
       - uses: actions/checkout@v4
       
       - name: Install uv
         uses: astral-sh/setup-uv@v4
         
-      - name: Set up Python
-        run: uv python install {{ python_version }}
-        
-      - name: Install dependencies
-        run: uv sync --group dev
-        
       - name: Build docs
-        run: uv run poe docs
+        run: uv run mkdocs build
       
       - name: Setup Pages
         uses: actions/configure-pages@v5
@@ -37,16 +35,8 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: {% if documentation_tool == 'mkdocs' %}site{% else %}docs{% endif %}
+          path: site
           
-  deploy:
-    if: github.ref == 'refs/heads/main'
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ "{{" }} steps.deployment.outputs.page_url {{ "}}" }}
-    steps:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
\ No newline at end of file
diff --git a/template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/index.md.jinja b/template/{% if documentation_tool %}docs{% endif %}/index.md.jinja
similarity index 85%
rename from template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/index.md.jinja
rename to template/{% if documentation_tool %}docs{% endif %}/index.md.jinja
index 9716c88f..ceae78e3 100644
--- a/template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/index.md.jinja	
+++ b/template/{% if documentation_tool %}docs{% endif %}/index.md.jinja	
@@ -2,6 +2,8 @@
 
 {{ project_description }}
 
+{%- if project_type == 'package' %}
+
 ## Installation
 
 ```bash
@@ -19,3 +21,4 @@ import {{ project_name_snake_case }}
 ## API Reference
 
 See the [API Reference](reference/index.md) for detailed documentation.
+{%- endif %}
diff --git a/template/{% if documentation_tool %}docs{% endif %}/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja b/template/{% if documentation_tool %}docs{% endif %}/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja
new file mode 100644
index 00000000..a85cc970
--- /dev/null
+++ b/template/{% if documentation_tool %}docs{% endif %}/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja	
@@ -0,0 +1,3 @@
+# API Reference
+
+::: {{ project_name_snake_case }}
diff --git a/template/{% if documentation_tool %}mkdocs.yml{% endif %}.jinja b/template/{% if documentation_tool %}mkdocs.yml{% endif %}.jinja
new file mode 100644
index 00000000..406011c9
--- /dev/null
+++ b/template/{% if documentation_tool %}mkdocs.yml{% endif %}.jinja	
@@ -0,0 +1,28 @@
+site_name: {{ project_name }}
+site_description: {{ project_description }}
+site_url: {{ project_url }}
+repo_url: {{ project_url }}
+repo_name: {{ project_url.split('/')[-2:] | join('/') }}
+
+theme:
+  name: material
+
+nav:
+  - Home: index.md
+{%- if project_type == 'package' %}
+  - API Reference: reference/
+{%- endif %}
+
+plugins:
+  - search
+{%- if project_type == 'package' %}
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: numpy
+{%- endif %}
+
+markdown_extensions:
+  - pymdownx.superfences
+  - pymdownx.highlight
diff --git a/template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/reference/index.md.jinja b/template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/reference/index.md.jinja
deleted file mode 100644
index f24e3ece..00000000
--- a/template/{% if documentation_tool == 'mkdocs' %}docs{% endif %}/reference/index.md.jinja	
+++ /dev/null
@@ -1,5 +0,0 @@
-{% if documentation_tool == 'mkdocs' -%}
-# API Reference
-
-::: {{ project_name_snake_case }}
-{%- endif %}
diff --git a/template/{% if documentation_tool == 'mkdocs' %}mkdocs.yml{% endif %}.jinja b/template/{% if documentation_tool == 'mkdocs' %}mkdocs.yml{% endif %}.jinja
deleted file mode 100644
index 5d6c0262..00000000
--- a/template/{% if documentation_tool == 'mkdocs' %}mkdocs.yml{% endif %}.jinja	
+++ /dev/null
@@ -1,53 +0,0 @@
-{% if documentation_tool == 'mkdocs' -%}
-site_name: {{ project_name }}
-site_description: {{ project_description }}
-site_url: {{ project_url }}
-repo_url: {{ project_url }}
-repo_name: {{ project_url.split('/')[-2:] | join('/') }}
-
-theme:
-  name: material
-  features:
-    - navigation.tabs
-    - navigation.sections
-    - navigation.expand
-    - navigation.top
-    - search.highlight
-    - search.share
-    - content.code.copy
-  palette:
-    - scheme: default
-      primary: blue
-      accent: blue
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
-    - scheme: slate
-      primary: blue
-      accent: blue
-      toggle:
-        icon: material/brightness-4
-        name: Switch to light mode
-
-nav:
-  - Home: index.md
-  - API Reference: reference/
-
-plugins:
-  - search
-  - mkdocstrings:
-      handlers:
-        python:
-          options:
-            docstring_style: numpy
-            show_source: true
-
-markdown_extensions:
-  - admonition
-  - pymdownx.details
-  - pymdownx.superfences
-  - pymdownx.highlight:
-      anchor_linenums: true
-  - pymdownx.inlinehilite
-  - pymdownx.snippets
-{%- endif %}

From 5e8a41e7cca4927098559cf8856e875ffe8f15e9 Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Mon, 1 Sep 2025 16:52:34 +0200
Subject: [PATCH 03/23] Update README.md

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 068fd5b4..cf312b22 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ A modern [Copier template](https://github.com/copier-org/copier) for scaffolding
 - ♻️ Continuous integration with [GitHub Actions](https://docs.github.com/en/actions) or [GitLab CI/CD](https://docs.gitlab.com/ee/ci/)
 - 🧪 Test coverage with [Coverage.py](https://github.com/nedbat/coveragepy)
 - 🧰 Dependency updates with [Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates)
-- 📚 Documentation with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) or [pdoc](https://pdoc.dev/)
+- 📚 Documentation with [MkDocs](https://github.com/mkdocs/mkdocs)
 
 ## ✨ Using
 

From a632e45ac6dd590c4b816f1efc0aba4ed2277884 Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Tue, 2 Sep 2025 09:21:31 +0200
Subject: [PATCH 04/23] Update template/README.md.jinja

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 template/README.md.jinja | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/template/README.md.jinja b/template/README.md.jinja
index 96f74a24..6c20f642 100644
--- a/template/README.md.jinja
+++ b/template/README.md.jinja
@@ -1,4 +1,4 @@
-[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTE3IDE2VjdsLTYgNU0yIDlWOGwxLTFoMWw0IDMgOC04aDFsNCAyIDEgMXYxNGwtMSAxLTQgMmgtMWwtOC04LTQgM0gzbC0xLTF2LTFsMy0zIi8+PC9zdmc+)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url={{ project_url }}){% if ci == 'github' %} [![Open in GitHub Codespaces](https://img.shields.io/static/v1?label=GitHub%20Codespaces&message=Open&color=blue&logo=github)](https://github.com/codespaces/new/{{ project_url.replace("https://github.com/", "") }}){% endif %}{% if documentation_tool and ci == 'github' %} [![Documentation](https://img.shields.io/static/v1?label=Documentation&message=View&color=blue&logo=read-the-docs)](https://{{ project_url.split('/')[-2] }}.github.io/{{ project_url.split('/')[-1] }}){% endif %}
+[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTE3IDE2VjdsLTYgNU0yIDlWOGwxLTFoMWw0IDMgOC04aDFsNCAyIDEgMXYxNGwtMSAxLTQgMmgtMWwtOC04LTQgM0gzbC0xLTF2LTFsMy0zIi8+PC9zdmc+)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url={{ project_url }}){% if ci == 'github' %} [![Open in GitHub Codespaces](https://img.shields.io/static/v1?label=GitHub%20Codespaces&message=Open&color=blue&logo=github)](https://github.com/codespaces/new/{{ project_url.replace("https://github.com/", "") }}){% endif %}{% if ci == 'github' %} [![Documentation](https://img.shields.io/static/v1?label=Documentation&message=View&color=blue&logo=readme&logoColor=white)](https://{{ project_url.split('/')[-2] }}.github.io/{{ project_url.split('/')[-1] }}){% endif %}
 
 # {{ project_name }}
 

From ff90ea03e09662977a06c2fd649c25ba2f327c83 Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Tue, 2 Sep 2025 09:22:00 +0200
Subject: [PATCH 05/23] Update uv version

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 .../{% if documentation_tool %}docs.yml{% endif %}.jinja        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool %}docs.yml{% endif %}.jinja b/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool %}docs.yml{% endif %}.jinja
index ad8c2312..ceb271db 100644
--- a/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool %}docs.yml{% endif %}.jinja	
+++ b/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool %}docs.yml{% endif %}.jinja	
@@ -24,7 +24,7 @@ jobs:
       - uses: actions/checkout@v4
       
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v6
         
       - name: Build docs
         run: uv run mkdocs build

From 517b0568127e7aacb402d6694c06c306420ccd37 Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Tue, 2 Sep 2025 09:23:24 +0200
Subject: [PATCH 06/23] Update mkdocs.yml

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 template/{% if documentation_tool %}mkdocs.yml{% endif %}.jinja | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/template/{% if documentation_tool %}mkdocs.yml{% endif %}.jinja b/template/{% if documentation_tool %}mkdocs.yml{% endif %}.jinja
index 406011c9..e2922568 100644
--- a/template/{% if documentation_tool %}mkdocs.yml{% endif %}.jinja	
+++ b/template/{% if documentation_tool %}mkdocs.yml{% endif %}.jinja	
@@ -10,7 +10,7 @@ theme:
 nav:
   - Home: index.md
 {%- if project_type == 'package' %}
-  - API Reference: reference/
+  - Reference: reference/
 {%- endif %}
 
 plugins:

From a697fbac2bce97f71d6912071c705f620977e331 Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Tue, 2 Sep 2025 09:23:48 +0200
Subject: [PATCH 07/23] update index.md

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 .../index.md.jinja                                              | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/template/{% if documentation_tool %}docs{% endif %}/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja b/template/{% if documentation_tool %}docs{% endif %}/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja
index a85cc970..fd2ee526 100644
--- a/template/{% if documentation_tool %}docs{% endif %}/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja	
+++ b/template/{% if documentation_tool %}docs{% endif %}/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja	
@@ -1,3 +1,3 @@
-# API Reference
+# Reference
 
 ::: {{ project_name_snake_case }}

From c4d2932ff7be528d8cefc300080a4e2e69d6556e Mon Sep 17 00:00:00 2001
From: SimonJasansky <s.jasansky@outlook.de>
Date: Tue, 2 Sep 2025 08:02:04 +0000
Subject: [PATCH 08/23] feat: remove documentation_tool from copier questions
 and always support mkdocs

---
 copier.yml                                    | 10 ++++-----
 template/.gitignore.jinja                     |  2 --
 template/README.md.jinja                      |  2 +-
 ....yml{% endif %}.jinja => mkdocs.yml.jinja} |  2 +-
 template/pyproject.toml.jinja                 | 12 +----------
 ...cs.yml{% endif %}.jinja => docs.yml.jinja} |  0
 .../index.md.jinja                            | 21 -------------------
 7 files changed, 8 insertions(+), 41 deletions(-)
 rename template/{{% if documentation_tool %}mkdocs.yml{% endif %}.jinja => mkdocs.yml.jinja} (93%)
 rename template/{% if ci == 'github' %}.github{% endif %}/workflows/{{% if documentation_tool %}docs.yml{% endif %}.jinja => docs.yml.jinja} (100%)

diff --git a/copier.yml b/copier.yml
index 331be5da..3963558a 100644
--- a/copier.yml
+++ b/copier.yml
@@ -91,11 +91,6 @@ with_typer_cli:
   help: Does your {{ project_type }} need a Typer CLI?
   default: false
 
-documentation_tool:
-  type: bool
-  help: Do you want to set up documentation for your {{ project_type }} using MkDocs?
-  default: true
-
 project_name_kebab_case:
   when: false
   default: "{{ project_name | lower | replace(' ', '-') }}"
@@ -103,3 +98,8 @@ project_name_kebab_case:
 project_name_snake_case:
   when: false
   default: "{{ project_name | lower | replace(' ', '_') }}"
+
+documentation_url:
+  when: false
+  default: "{% if ci == 'github' %}https://{{ project_url.split('/')[-2] }}.github.io/{{ project_url.split('/')[-1] }}{% else %}{{ project_url }}{% endif %}"
+
diff --git a/template/.gitignore.jinja b/template/.gitignore.jinja
index 785e9f0d..90c69353 100644
--- a/template/.gitignore.jinja
+++ b/template/.gitignore.jinja
@@ -69,8 +69,6 @@ uv.lock
 
 # VS Code
 .vscode/
-{%- if documentation_tool %}
 
 # MkDocs
 site/
-{%- endif %}
diff --git a/template/README.md.jinja b/template/README.md.jinja
index 6c20f642..1451740c 100644
--- a/template/README.md.jinja
+++ b/template/README.md.jinja
@@ -1,4 +1,4 @@
-[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTE3IDE2VjdsLTYgNU0yIDlWOGwxLTFoMWw0IDMgOC04aDFsNCAyIDEgMXYxNGwtMSAxLTQgMmgtMWwtOC04LTQgM0gzbC0xLTF2LTFsMy0zIi8+PC9zdmc+)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url={{ project_url }}){% if ci == 'github' %} [![Open in GitHub Codespaces](https://img.shields.io/static/v1?label=GitHub%20Codespaces&message=Open&color=blue&logo=github)](https://github.com/codespaces/new/{{ project_url.replace("https://github.com/", "") }}){% endif %}{% if ci == 'github' %} [![Documentation](https://img.shields.io/static/v1?label=Documentation&message=View&color=blue&logo=readme&logoColor=white)](https://{{ project_url.split('/')[-2] }}.github.io/{{ project_url.split('/')[-1] }}){% endif %}
+[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTE3IDE2VjdsLTYgNU0yIDlWOGwxLTFoMWw0IDMgOC04aDFsNCAyIDEgMXYxNGwtMSAxLTQgMmgtMWwtOC04LTQgM0gzbC0xLTF2LTFsMy0zIi8+PC9zdmc+)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url={{ project_url }}){% if ci == 'github' %} [![Open in GitHub Codespaces](https://img.shields.io/static/v1?label=GitHub%20Codespaces&message=Open&color=blue&logo=github)](https://github.com/codespaces/new/{{ project_url.replace("https://github.com/", "") }}){% endif %}{% if ci == 'github' %} [![Documentation](https://img.shields.io/static/v1?label=Documentation&message=View&color=blue&logo=readme&logoColor=white)]({{ documentation_url }}){% endif %}
 
 # {{ project_name }}
 
diff --git a/template/{% if documentation_tool %}mkdocs.yml{% endif %}.jinja b/template/mkdocs.yml.jinja
similarity index 93%
rename from template/{% if documentation_tool %}mkdocs.yml{% endif %}.jinja
rename to template/mkdocs.yml.jinja
index e2922568..086b1cb7 100644
--- a/template/{% if documentation_tool %}mkdocs.yml{% endif %}.jinja	
+++ b/template/mkdocs.yml.jinja
@@ -1,6 +1,6 @@
 site_name: {{ project_name }}
 site_description: {{ project_description }}
-site_url: {{ project_url }}
+site_url: {{ documentation_url }}
 repo_url: {{ project_url }}
 repo_name: {{ project_url.split('/')[-2:] | join('/') }}
 
diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja
index b7620249..34009558 100644
--- a/template/pyproject.toml.jinja
+++ b/template/pyproject.toml.jinja
@@ -36,13 +36,7 @@ source = "{{ project_url }}"
 changelog = "{{ project_url.rstrip('/') }}/{% if ci == 'gitlab' %}-/{% endif %}blob/main/CHANGELOG.md"
 {%- endif %}
 releasenotes = "{{ project_url.rstrip('/') }}/{% if ci == 'gitlab' %}-/{% endif %}releases"
-{%- if documentation_tool != 'None' %}
-{%- if ci == 'github' %}
-documentation = "https://{{ project_url.split('/')[-2] }}.github.io/{{ project_url.split('/')[-1] }}"
-{%- else %}
-documentation = "{{ project_url }}"
-{%- endif %}
-{%- endif %}
+docs = "{{ documentation_url }}"
 issues = "{{ project_url.rstrip('/') }}/{% if ci == 'gitlab' %}-/{% endif %}issues"
 
 [dependency-groups]  # https://docs.astral.sh/uv/concepts/projects/dependencies/#development-dependencies
@@ -55,13 +49,9 @@ dev = [
   "ipython (>=8.18.0)",
   "ipywidgets (>=8.1.2)",
   "mypy (>=1.14.1)",
-  {%- if documentation_tool %}
   "mkdocs-material (>=9.5.21)",
   {%- if project_type == 'package' %}
   "mkdocstrings[python] (>=0.26.2)",
-  {%- endif %}
-  {%- endif %}
-  {%- if project_type == 'package' %}
   "poethepoet (>=0.32.1)",
   {%- endif %}
   "pre-commit (>=4.0.1)",
diff --git a/template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool %}docs.yml{% endif %}.jinja b/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja
similarity index 100%
rename from template/{% if ci == 'github' %}.github{% endif %}/workflows/{% if documentation_tool %}docs.yml{% endif %}.jinja
rename to template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja
diff --git a/template/{% if documentation_tool %}docs{% endif %}/index.md.jinja b/template/{% if documentation_tool %}docs{% endif %}/index.md.jinja
index ceae78e3..3f65d4f2 100644
--- a/template/{% if documentation_tool %}docs{% endif %}/index.md.jinja	
+++ b/template/{% if documentation_tool %}docs{% endif %}/index.md.jinja	
@@ -1,24 +1,3 @@
 # {{ project_name }}
 
 {{ project_description }}
-
-{%- if project_type == 'package' %}
-
-## Installation
-
-```bash
-pip install {{ project_name_kebab_case }}
-```
-
-## Quick Start
-
-```python
-import {{ project_name_snake_case }}
-
-# Your code here
-```
-
-## API Reference
-
-See the [API Reference](reference/index.md) for detailed documentation.
-{%- endif %}

From a17abf161a635927001f482b72abc970ee8b091c Mon Sep 17 00:00:00 2001
From: SimonJasansky <s.jasansky@outlook.de>
Date: Tue, 2 Sep 2025 08:13:12 +0000
Subject: [PATCH 09/23] fix: rename docs folder

---
 .../index.md.jinja                                                | 0
 .../index.md.jinja                                                | 0
 2 files changed, 0 insertions(+), 0 deletions(-)
 rename template/{{% if documentation_tool %}docs{% endif %} => docs}/index.md.jinja (100%)
 rename template/{{% if documentation_tool %}docs{% endif %} => docs}/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja (100%)

diff --git a/template/{% if documentation_tool %}docs{% endif %}/index.md.jinja b/template/docs/index.md.jinja
similarity index 100%
rename from template/{% if documentation_tool %}docs{% endif %}/index.md.jinja
rename to template/docs/index.md.jinja
diff --git a/template/{% if documentation_tool %}docs{% endif %}/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja b/template/docs/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja
similarity index 100%
rename from template/{% if documentation_tool %}docs{% endif %}/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja
rename to template/docs/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja

From a9ea4b157074271a6b42a03f993164153bacb20c Mon Sep 17 00:00:00 2001
From: SimonJasansky <s.jasansky@outlook.de>
Date: Tue, 2 Sep 2025 08:17:13 +0000
Subject: [PATCH 10/23] fix: update README

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index cf312b22..5b8821f1 100644
--- a/README.md
+++ b/README.md
@@ -94,7 +94,7 @@ To migrate a project from Cookiecutter to Copier, follow these steps:
 
 ## 📚 Generate Docs
 
-If you are using GitHub as your repository host and choose one of the supported documentation frameworks, your docs will be published automatically to GitHub Pages. They will be available at `https://<username>.github.io/<repository>`.
+If you are using GitHub as your repository host, your docs will be published automatically to GitHub Pages, and will be available at `https://<username>.github.io/<repository>`.
 
 > [!TIP]
 > Ensure the source for GitHub Pages is set to "GitHub Actions" in your repository settings under **Settings** → **Pages**. For more details, see [Configuring a publishing source for your GitHub Pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site).

From ab9cdcede152d8a81da91d6c2d320b89f6ff5420 Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Fri, 5 Sep 2025 09:48:29 +0200
Subject: [PATCH 11/23] Apply suggestion from @lsorber

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 README.md | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5b8821f1..114261fb 100644
--- a/README.md
+++ b/README.md
@@ -92,12 +92,18 @@ To migrate a project from Cookiecutter to Copier, follow these steps:
 
 5. Create a PR from your branch, review it, and merge it!
 
-## 📚 Generate Docs
+### Generate and publish your Python project's docs
 
-If you are using GitHub as your repository host, your docs will be published automatically to GitHub Pages, and will be available at `https://<username>.github.io/<repository>`.
+To generate and serve your Python project's docs, run:
+
+```sh
+poe docs --serve
+```
+
+If your project is on GitHub, your docs will be published automatically to GitHub Pages every time you update the default branch. You can view the docs by clicking on the ![Documentation](https://img.shields.io/static/v1?label=Documentation&message=View&color=blue&logo=readme&logoColor=white)] badge in your project's README.
 
 > [!TIP]
-> Ensure the source for GitHub Pages is set to "GitHub Actions" in your repository settings under **Settings** → **Pages**. For more details, see [Configuring a publishing source for your GitHub Pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site).
+> Make sure to [configure the source of your project's GitHub Pages as GitHub Actions in your project settings](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) to allow the GitHub Actions workflow to publish your docs.
 
 ## Contributing
 

From 02765c36f4c5de153aa38b9027b0034c417f4002 Mon Sep 17 00:00:00 2001
From: SimonJasansky <s.jasansky@outlook.de>
Date: Fri, 5 Sep 2025 08:07:26 +0000
Subject: [PATCH 12/23] feat: address PR comments

---
 copier.yml                                      |  2 +-
 template/.gitignore.jinja                       |  6 +++---
 template/pyproject.toml.jinja                   | 17 +++++++++++++++++
 .../workflows/docs.yml.jinja                    |  4 ++--
 4 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/copier.yml b/copier.yml
index 3963558a..44d7c933 100644
--- a/copier.yml
+++ b/copier.yml
@@ -101,5 +101,5 @@ project_name_snake_case:
 
 documentation_url:
   when: false
-  default: "{% if ci == 'github' %}https://{{ project_url.split('/')[-2] }}.github.io/{{ project_url.split('/')[-1] }}{% else %}{{ project_url }}{% endif %}"
+  default: "{% if ci == 'github' %}https://{{ project_url.rstrip('/').split('/')[-2] }}.github.io/{{ project_url.rstrip('/').split('/')[-1] }}{% else %}{{ project_url }}{% endif %}"
 
diff --git a/template/.gitignore.jinja b/template/.gitignore.jinja
index 90c69353..fe2b5e5d 100644
--- a/template/.gitignore.jinja
+++ b/template/.gitignore.jinja
@@ -33,6 +33,9 @@ notebooks/
 # mise
 mise.local.toml
 
+# MkDocs
+site/
+
 # mypy
 .dmypy.json
 .mypy_cache/
@@ -69,6 +72,3 @@ uv.lock
 
 # VS Code
 .vscode/
-
-# MkDocs
-site/
diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja
index 34009558..6d725649 100644
--- a/template/pyproject.toml.jinja
+++ b/template/pyproject.toml.jinja
@@ -155,6 +155,23 @@ convention = "numpy"
 type = "simple"
 
 [tool.poe.tasks]
+
+  [tool.poe.tasks.docs]
+  help = "Build or serve the documentation"
+  shell = """
+    if [ $serve ]
+    then {
+      mkdocs build && mkdocs serve
+    } else {
+      mkdocs build
+    } fi
+    """
+
+    [[tool.poe.tasks.docs.args]]
+    help = "Serve the documentation locally with live reload"
+    type = "boolean"
+    name = "serve"
+    options = ["--serve"]
 {%- if with_fastapi_api %}
 
   [tool.poe.tasks.serve]
diff --git a/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja b/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja
index ceb271db..2b37f29d 100644
--- a/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja	
+++ b/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja	
@@ -29,10 +29,10 @@ jobs:
       - name: Build docs
         run: uv run mkdocs build
       
-      - name: Setup Pages
+      - name: Configure GitHub Pages
         uses: actions/configure-pages@v5
         
-      - name: Upload artifact
+      - name: Upload GitHub Pages artifact 
         uses: actions/upload-pages-artifact@v3
         with:
           path: site

From c88f0f017bd4c34eb3596f6b0a740376497f0ffe Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Tue, 9 Sep 2025 15:16:38 +0200
Subject: [PATCH 13/23] Update template/{% if ci == 'github' %}.github{% endif
 %}/workflows/docs.yml.jinja

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 .../workflows/docs.yml.jinja                                  | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja b/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja
index 2b37f29d..d079cb38 100644
--- a/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja	
+++ b/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja	
@@ -16,11 +16,15 @@ concurrency:
 jobs:
   build-and-deploy:
     if: github.ref == 'refs/heads/main'
+
     runs-on: ubuntu-latest
+
     environment:
       name: github-pages
       url: ${{ "{{" }} steps.deployment.outputs.page_url {{ "}}" }}
+
     steps:
+      - name: Checkout
       - uses: actions/checkout@v4
       
       - name: Install uv

From bbdcf7c1665aeaf6fa1c0ace30b698ce3a56aa0e Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Tue, 9 Sep 2025 15:17:18 +0200
Subject: [PATCH 14/23] Update template/mkdocs.yml.jinja

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 template/mkdocs.yml.jinja | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/template/mkdocs.yml.jinja b/template/mkdocs.yml.jinja
index 086b1cb7..f3230ef4 100644
--- a/template/mkdocs.yml.jinja
+++ b/template/mkdocs.yml.jinja
@@ -24,5 +24,5 @@ plugins:
 {%- endif %}
 
 markdown_extensions:
-  - pymdownx.superfences
   - pymdownx.highlight
+  - pymdownx.superfences

From c1d23c8b6862af241c470090534a1412f528f29c Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Tue, 9 Sep 2025 15:19:27 +0200
Subject: [PATCH 15/23] Update template/mkdocs.yml.jinja

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 template/mkdocs.yml.jinja | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/template/mkdocs.yml.jinja b/template/mkdocs.yml.jinja
index f3230ef4..65ddc9a9 100644
--- a/template/mkdocs.yml.jinja
+++ b/template/mkdocs.yml.jinja
@@ -11,6 +11,9 @@ nav:
   - Home: index.md
 {%- if project_type == 'package' %}
   - Reference: reference/
+
+watch:
+  - src
 {%- endif %}
 
 plugins:

From bcf2e546e71495908590dd3736244fbce2fa664a Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Tue, 9 Sep 2025 15:24:46 +0200
Subject: [PATCH 16/23] Update template/mkdocs.yml.jinja

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 template/mkdocs.yml.jinja | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/template/mkdocs.yml.jinja b/template/mkdocs.yml.jinja
index 65ddc9a9..e6e2911a 100644
--- a/template/mkdocs.yml.jinja
+++ b/template/mkdocs.yml.jinja
@@ -3,6 +3,16 @@ site_description: {{ project_description }}
 site_url: {{ documentation_url }}
 repo_url: {{ project_url }}
 repo_name: {{ project_url.split('/')[-2:] | join('/') }}
+{%- if typing == 'strict' %}
+
+strict: true
+
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+  anchors: warn
+{%- endif %}
 
 theme:
   name: material

From c36a0180da2644a0693f7f9a2d06877b3c8ba14c Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Tue, 9 Sep 2025 15:26:17 +0200
Subject: [PATCH 17/23] Update template/pyproject.toml.jinja

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 template/pyproject.toml.jinja | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja
index 6d725649..a3ffbb99 100644
--- a/template/pyproject.toml.jinja
+++ b/template/pyproject.toml.jinja
@@ -161,7 +161,7 @@ type = "simple"
   shell = """
     if [ $serve ]
     then {
-      mkdocs build && mkdocs serve
+      mkdocs serve
     } else {
       mkdocs build
     } fi

From 5c3ecb88a918b0504d749c8029dae1a8673c4f1f Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Tue, 9 Sep 2025 15:27:48 +0200
Subject: [PATCH 18/23] Update README.md

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 114261fb..f5691187 100644
--- a/README.md
+++ b/README.md
@@ -92,9 +92,9 @@ To migrate a project from Cookiecutter to Copier, follow these steps:
 
 5. Create a PR from your branch, review it, and merge it!
 
-### Generate and publish your Python project's docs
+### Build and publish your Python project's docs
 
-To generate and serve your Python project's docs, run:
+To build and serve your Python project's docs, run:
 
 ```sh
 poe docs --serve

From 27b4e64bf313fecbe87f11c1273b8a5aed109524 Mon Sep 17 00:00:00 2001
From: SimonJasansky <s.jasansky@outlook.de>
Date: Tue, 9 Sep 2025 13:49:16 +0000
Subject: [PATCH 19/23] fix(docs.yml): yaml syntax error

---
 .../workflows/docs.yml.jinja                                    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja b/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja
index d079cb38..4b1284e9 100644
--- a/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja	
+++ b/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja	
@@ -25,7 +25,7 @@ jobs:
 
     steps:
       - name: Checkout
-      - uses: actions/checkout@v4
+        uses: actions/checkout@v4
       
       - name: Install uv
         uses: astral-sh/setup-uv@v6

From ca92a3ceac3191fed77d2d9547fccaa809d1ca03 Mon Sep 17 00:00:00 2001
From: SimonJasansky <s.jasansky@outlook.de>
Date: Tue, 9 Sep 2025 13:52:44 +0000
Subject: [PATCH 20/23] feat(mkdocs.yml): strip trailing slashes when parsing
 project_url

---
 template/mkdocs.yml.jinja | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/template/mkdocs.yml.jinja b/template/mkdocs.yml.jinja
index e6e2911a..5168889c 100644
--- a/template/mkdocs.yml.jinja
+++ b/template/mkdocs.yml.jinja
@@ -2,7 +2,7 @@ site_name: {{ project_name }}
 site_description: {{ project_description }}
 site_url: {{ documentation_url }}
 repo_url: {{ project_url }}
-repo_name: {{ project_url.split('/')[-2:] | join('/') }}
+repo_name: {{ project_url.rstrip('/').split('/')[-2:] | join('/') }}
 {%- if typing == 'strict' %}
 
 strict: true

From 61a41a32ec9fc7bef2f2139790a78f17b2875b1c Mon Sep 17 00:00:00 2001
From: SimonJasansky <s.jasansky@outlook.de>
Date: Tue, 9 Sep 2025 13:55:29 +0000
Subject: [PATCH 21/23] feat: move API reference from dedicated folder
 /reference to file reference.md

---
 ...f project_type == 'package' %}reference.md{% endif %}.jinja} | 0
 template/mkdocs.yml.jinja                                       | 2 +-
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename template/docs/{{% if project_type == 'package' %}reference{% endif %}/index.md.jinja => {% if project_type == 'package' %}reference.md{% endif %}.jinja} (100%)

diff --git a/template/docs/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja b/template/docs/{% if project_type == 'package' %}reference.md{% endif %}.jinja
similarity index 100%
rename from template/docs/{% if project_type == 'package' %}reference{% endif %}/index.md.jinja
rename to template/docs/{% if project_type == 'package' %}reference.md{% endif %}.jinja
diff --git a/template/mkdocs.yml.jinja b/template/mkdocs.yml.jinja
index 5168889c..8c764426 100644
--- a/template/mkdocs.yml.jinja
+++ b/template/mkdocs.yml.jinja
@@ -20,7 +20,7 @@ theme:
 nav:
   - Home: index.md
 {%- if project_type == 'package' %}
-  - Reference: reference/
+  - Reference: reference.md
 
 watch:
   - src

From 81309990f846d826c762e3bf1f6a366763e67680 Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Wed, 10 Sep 2025 09:58:00 +0200
Subject: [PATCH 22/23] Update template/pyproject.toml.jinja

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 template/pyproject.toml.jinja | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja
index a3ffbb99..8b638d43 100644
--- a/template/pyproject.toml.jinja
+++ b/template/pyproject.toml.jinja
@@ -36,7 +36,7 @@ source = "{{ project_url }}"
 changelog = "{{ project_url.rstrip('/') }}/{% if ci == 'gitlab' %}-/{% endif %}blob/main/CHANGELOG.md"
 {%- endif %}
 releasenotes = "{{ project_url.rstrip('/') }}/{% if ci == 'gitlab' %}-/{% endif %}releases"
-docs = "{{ documentation_url }}"
+documentation = "{{ documentation_url }}"
 issues = "{{ project_url.rstrip('/') }}/{% if ci == 'gitlab' %}-/{% endif %}issues"
 
 [dependency-groups]  # https://docs.astral.sh/uv/concepts/projects/dependencies/#development-dependencies

From f84eae723f6eb1941a8f10e9d4feb2c68fa9b0d9 Mon Sep 17 00:00:00 2001
From: Simon Jasansky <64031597+SimonJasansky@users.noreply.github.com>
Date: Wed, 10 Sep 2025 11:18:03 +0200
Subject: [PATCH 23/23] Update template/{% if ci == 'github' %}.github{% endif
 %}/workflows/docs.yml.jinja

Co-authored-by: Laurent Sorber <laurent.sorber@gmail.com>
---
 .../workflows/docs.yml.jinja                              | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja b/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja
index 4b1284e9..07e118c7 100644
--- a/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja	
+++ b/template/{% if ci == 'github' %}.github{% endif %}/workflows/docs.yml.jinja	
@@ -11,12 +11,10 @@ permissions:
 
 concurrency:
   group: "pages"
-  cancel-in-progress: false
+  cancel-in-progress: true
 
 jobs:
   build-and-deploy:
-    if: github.ref == 'refs/heads/main'
-
     runs-on: ubuntu-latest
 
     environment:
@@ -25,7 +23,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
       
       - name: Install uv
         uses: astral-sh/setup-uv@v6
@@ -37,7 +35,7 @@ jobs:
         uses: actions/configure-pages@v5
         
       - name: Upload GitHub Pages artifact 
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
         with:
           path: site