docs: restructure template and root docs to Diataxis folder-per-quadrant

.github/skills/backport-commit/references/file-mapping.md

@@ -25,7 +25,7 @@ Some files use conditionals in the filename itself.
 
 | Generated Path | Template Path |
 |---|---|
-| `docs/pages/examples.md` | `template/docs/pages/{% if include_examples %}examples.md{% endif %}.jinja` |
+| `docs/pages/tutorials/examples.md` | `template/docs/pages/tutorials/{% if include_examples %}examples.md{% endif %}.jinja` |
 | `docs/stylesheets/gallery.css` | `template/docs/stylesheets/{% if include_examples %}gallery.css{% endif %}` |
 | `tests/test_examples.py` | `template/tests/{% if include_examples %}test_examples.py{% endif %}.jinja` |
 

docs/index.md

@@ -20,7 +20,7 @@ A modern Python package template using [Copier](https://copier.readthedocs.io/)
 
 ## Get Started
 
-- **[Quick Start](pages/quickstart.md)** - Create your package in 5 minutes
+- **[Quick Start](pages/tutorials/quickstart.md)** - Create your package in 5 minutes
 
 ## How-to Guides
 

docs/pages/reference/project-structure.md

@@ -19,10 +19,17 @@ my-package/
 │   └── pull_request_template.md
 ├── docs/
 │   ├── index.md
-│   ├── getting-started.md
-│   ├── user-guide.md
-│   ├── api-reference.md
-│   └── contributing.md
+│   ├── tutorials/
+│   │   ├── getting-started.md
+│   │   └── examples.md
+│   ├── how-to/
+│   │   ├── configure.md
+│   │   ├── troubleshooting.md
+│   │   └── contribute.md
+│   ├── reference/
+│   │   └── api.md
+│   └── explanation/
+│       └── concepts.md
 ├── src/
 │   └── package_name/
 │       ├── __init__.py
@@ -99,10 +106,13 @@ The project uses a **src layout** - all package code lives under `src/<package_n
 | File | Purpose |
 |------|---------|
 | `index.md` | Documentation homepage |
-| `getting-started.md` | Installation and first steps (tutorial) |
-| `user-guide.md` | Usage guide scaffold (how-to) |
-| `api-reference.md` | Auto-generated API reference |
-| `contributing.md` | Full contributing guidelines |
+| `tutorials/getting-started.md` | Installation and first steps (tutorial) |
+| `tutorials/examples.md` | Interactive examples gallery (if `include_examples=true`) |
+| `how-to/configure.md` | Configuration guide scaffold |
+| `how-to/troubleshooting.md` | Common problems and solutions |
+| `how-to/contribute.md` | Full contributing guidelines |
+| `reference/api.md` | Auto-generated API reference |
+| `explanation/concepts.md` | Core concepts and architecture |
 
 ## Conditional Files
 
@@ -111,4 +121,4 @@ Some files are only generated based on template variable choices:
 | Condition | Files Generated |
 |-----------|----------------|
 | `include_actions=true` | `.github/workflows/*`, `.github/dependabot.yml` |
-| `include_examples=true` | `examples/hello.py`, `tests/test_examples.py`, `docs/pages/examples.md`, `docs/stylesheets/gallery.css` |
+| `include_examples=true` | `examples/hello.py`, `tests/test_examples.py`, `docs/pages/tutorials/examples.md`, `docs/stylesheets/gallery.css` |

docs/pages/quickstart.md → docs/pages/tutorials/quickstart.md

@@ -32,7 +32,7 @@ Answer the prompts about your project. You'll be asked for:
 - `include_actions`: Include GitHub Actions CI/CD workflows? (default: true)
 - `include_examples`: Include interactive [marimo](https://marimo.io/) notebooks in `examples/`? (default: true)
 
-See [Template Variables](reference/template-variables.md) in the Reference for detailed descriptions.
+See [Template Variables](../reference/template-variables.md) in the Reference for detailed descriptions.
 
 ## Initialize Your Project
 
@@ -121,7 +121,7 @@ git push origin v0.1.0
 
 This triggers: changelog generation → PR creation → (after merge) GitHub release → **manual approval** → PyPI publish.
 
-See the [Contributing Guide](how-to/contribute.md) for detailed release process documentation.
+See the [Contributing Guide](../how-to/contribute.md) for detailed release process documentation.
 
 ### ReadTheDocs (Documentation)
 
@@ -135,9 +135,9 @@ Documentation builds automatically on every push to main.
 
 ## Next Steps
 
-- **[Set Up CI/CD Services](how-to/setup-cicd.md)** - Configure Codecov, PyPI publishing, and ReadTheDocs
-- **[Customize Your Project](how-to/customize-template.md)** - Adjust ruff rules, coverage thresholds, and more
-- **[Add Dependencies](how-to/add-dependencies.md)** - Add runtime and development dependencies
-- **[Reference: Commands](reference/commands.md)** - Full command reference for just, nox, and uv
-- **[Contributing](how-to/contribute.md)** - Help improve the template
+- **[Set Up CI/CD Services](../how-to/setup-cicd.md)** - Configure Codecov, PyPI publishing, and ReadTheDocs
+- **[Customize Your Project](../how-to/customize-template.md)** - Adjust ruff rules, coverage thresholds, and more
+- **[Add Dependencies](../how-to/add-dependencies.md)** - Add runtime and development dependencies
+- **[Reference: Commands](../reference/commands.md)** - Full command reference for just, nox, and uv
+- **[Contributing](../how-to/contribute.md)** - Help improve the template
 - **[GitHub Template](https://github.com/stateful-y/python-package-copier)** - Source code and issues

mkdocs.yml

@@ -61,7 +61,8 @@ markdown_extensions:
 
 nav:
   - Home: index.md
-  - Quick Start: pages/quickstart.md
+  - Tutorials:
+    - Quick Start: pages/tutorials/quickstart.md
   - How-to Guides:
     - Set Up CI/CD Services: pages/how-to/setup-cicd.md
     - Customize Your Project: pages/how-to/customize-template.md

template/.github/skills/update-from-template/references/conflict-resolution.md

@@ -148,14 +148,19 @@ benchmarks = [
 # Template nav structure:
 nav:
   - Home: index.md
-  - Getting Started: pages/getting-started.md
-  - User Guide: pages/user-guide.md
-  - Examples: pages/examples.md        # conditional
-  - API Reference: pages/api-reference.md
-  - Contributing: pages/contributing.md
+  - Tutorials:
+    - Getting Started: pages/tutorials/getting-started.md
+    - Examples: pages/tutorials/examples.md  # conditional
+  - How-to Guides:
+    - Configure: pages/how-to/configure.md
+    - Troubleshooting: pages/how-to/troubleshooting.md
+    - Contributing: pages/how-to/contribute.md
+  - Reference:
+    - API Reference: pages/reference/api.md
+  - Explanation:
+    - Concepts: pages/explanation/concepts.md
 
 # Local additions to preserve (not in template):
-  - Tutorials: pages/tutorials.md       # KEEP
   - FAQ: pages/faq.md                   # KEEP
 ```
 

template/.github/skills/update-from-template/references/file-classification.md

@@ -76,8 +76,8 @@ mkdocs.yml
 noxfile.py
 justfile
 docs/index.md
-docs/pages/api-reference.md
-docs/pages/contributing.md
+docs/pages/reference/api.md
+docs/pages/how-to/contribute.md
 .github/workflows/tests.yml        # conditional: include_actions
 .github/workflows/pr-title.yml     # conditional: include_actions
 .github/workflows/publish-release.yml  # conditional: include_actions
@@ -95,9 +95,9 @@ Project-specific files where the template only provides initial scaffolding. Nev
 src/<package_name>/**              # All source code
 tests/**                           # All test files
 examples/**                        # conditional: include_examples
-docs/pages/user-guide.md
-docs/pages/getting-started.md
-docs/pages/examples.md             # conditional: include_examples
+docs/pages/explanation/concepts.md
+docs/pages/tutorials/getting-started.md
+docs/pages/tutorials/examples.md    # conditional: include_examples
 docs/examples/**                   # conditional: include_examples
 ```
 
@@ -160,7 +160,7 @@ This ensures the skill only spends effort merging files that actually have local
 - **Preserve local**: All changelog entries
 - **Strategy**: Keep the local CHANGELOG.md content. Only update the header/format if the template changed it. Never discard changelog entries.
 
-### docs/index.md, docs/pages/contributing.md, docs/pages/api-reference.md
+### docs/index.md, docs/pages/how-to/contribute.md, docs/pages/reference/api.md
 
 - **Accept from template**: Structural/format changes, new template sections
 - **Preserve local**: Custom content within existing sections, additional sections

template/CONTRIBUTING.md

@@ -18,7 +18,7 @@ just test-fast
 
 For the complete contributing guide - including test strategy, code quality standards, commit conventions, and CI/CD details - see:
 
-**[Full Contributing Guide](docs/pages/contributing.md)**
+**[Full Contributing Guide](docs/pages/how-to/contribute.md)**
 
 ## Reporting Issues
 

template/docs/hooks.py.jinja

@@ -529,7 +529,7 @@ def _build_module_toc(config, current_src_path=None):
     api_dir = docs_dir / "pages" / "api"
     project_root = docs_dir.parent
 
-    is_index = current_src_path is None or current_src_path == "pages/api-reference.md"
+    is_index = current_src_path is None or current_src_path == "pages/reference/api.md"
 
     modules = _get_submodules(project_root)
     module_toc = []
@@ -542,8 +542,8 @@ def _build_module_toc(config, current_src_path=None):
 
         # Compute relative URL
         if is_index:
-            # api-reference.md is at pages/api-reference/, submodule pages at pages/api/
-            page_url = f"../api/{md_filename.replace('.md', '/')}"
+            # reference/api.md is at pages/reference/api/, submodule pages at pages/api/
+            page_url = f"../../api/{md_filename.replace('.md', '/')}"
         else:
             page_url = f"../{md_filename.replace('.md', '/')}".replace("//", "/")
 
@@ -903,7 +903,7 @@ def on_page_content(html, page, config, files):
     if src.startswith("pages/api/generated/"):
         html = _process_api_page_content(html, page, config)
 
-    if src == "pages/api-reference.md":
+    if src == "pages/reference/api.md":
         # API index: flat module list (api-index.html template)
         page.meta["module_toc"] = _build_module_toc(config, current_src_path=src)
     elif (

template/docs/index.md.jinja

@@ -5,82 +5,68 @@
 
 {{ description }}
 
-[Add 1-2 paragraphs explaining:
-- What this package integrates or provides
-- The main value proposition
-- Key use cases or target audience]
-
 <div class="grid cards" markdown>
 
 -  **Get Started in 5 Minutes**
 
     ---
 
-    Install {{ project_name }} and [achieve first result]
-
-    Install → Initialize → Run → Done
+    Install {{ project_name }} and run your first example.
 
-    [Getting Started](pages/getting-started.md)
+    [Getting Started](pages/tutorials/getting-started.md)
 
 - **Need Help?**
 
     ---
 
-    Find answers to common questions and troubleshooting tips
+    Find answers to common questions and troubleshooting tips.
 
-    [FAQ & Troubleshooting](pages/user-guide.md#troubleshooting)
+    [Troubleshooting](pages/how-to/troubleshooting.md)
 
 - **Learn the Concepts**
 
     ---
 
-    Understand [core concepts or how components work together]
+    Understand the design and core ideas behind {{ project_name }}.
 
-    [Introduction](pages/user-guide.md) · [User guide](pages/user-guide.md)
+    [Concepts](pages/explanation/concepts.md)
 
 {% if include_examples %}
 - **See It In Action**
 
     ---
 
-    Explore a complete example [describe what the example demonstrates]
+    Explore interactive example notebooks.
 
-    [Example Project](pages/examples.md)
+    [Examples](pages/tutorials/examples.md)
 {% endif %}
 
 </div>
 
 ## Table of Contents
 
-### [Getting started](pages/getting-started.md)
-
-Step-by-step guide to installing and setting up {{ project_name }} in your project.
+### [Getting Started](pages/tutorials/getting-started.md)
 
-- [1. [First Setup Step]](pages/getting-started.md#step-1-import-and-initialize)
-- [2. [Installation or Configuration]](pages/getting-started.md#step-2-configure-your-setup)
-- [3. [Initialize/Configure Step]](pages/getting-started.md#step-3-use-the-main-functionality)
+Install and run your first example.
 
 {% if include_examples %}
-### [Example](pages/examples.md)
+### [Examples](pages/tutorials/examples.md)
 
-A practical example demonstrating how to use {{ project_name }} in a real project.
-
-- [Project overview](pages/examples.md#examples)
-- [Quick start](pages/examples.md#running-examples-locally)
+Interactive notebooks demonstrating {{ project_name }} in practice.
 {% endif %}
 
-### [User guide](pages/user-guide.md)
+### [Configuration](pages/how-to/configure.md)
+
+Set up and customize {{ project_name }} for your project.
 
-In-depth documentation on the design, architecture, and core concepts.
+### [API Reference](pages/reference/api.md)
 
-- [Core Concepts](pages/user-guide.md#core-concepts)
-- [Configuration](pages/user-guide.md#configuration)
-- [Best Practices](pages/user-guide.md#best-practices)
+Complete API reference - classes, functions, and options.
 
-### [Reference](pages/api-reference/)
+### [Concepts](pages/explanation/concepts.md)
 
-Detailed reference for the {{ project_name }} API, including classes, functions, and configuration options.
+Design, architecture, and core ideas.
 
 ## License
 
-{{ project_name }} is open source and licensed under the [{{ license }} License](https://opensource.org/licenses/{{ license }}). You are free to use, modify, and distribute this software under the terms of this license.
+{{ project_name }} is open source and licensed under the [{{ license }} License](https://opensource.org/licenses/{{ license }}).

template/docs/pages/explanation/concepts.md.jinja

@@ -0,0 +1,20 @@
+# About {{ project_name }}
+
+{{ description }}
+
+## Core Concepts
+
+Describe the key abstractions, terminology, and mental models for your package.
+
+## Architecture
+
+Explain how the package is structured and how the components fit together.
+
+## Limitations
+
+Document known constraints and trade-offs so users can make informed decisions.
+
+## See Also
+
+- [Getting Started](../tutorials/getting-started.md) - install and first example
+- [API Reference](../reference/api.md) - detailed API documentation