docs: add notes at top of page, update REAMDE

README.md

@@ -15,17 +15,18 @@ templates for Python packages?
 
 - Lives with the [Scientific-Python Development Guide][]: Every decision is
   clearly documented and every tool described, and everything is kept in sync.
-- Nine different backends to choose from for building packages.
+- Ten different backends to choose from for building packages.
 - Optional VCS versioning for most backends.
+- Selection for your preferred documentation engine (Sphinx or MkDocs).
 - Template generation tested in GitHub Actions using nox.
 - Supports generation with [copier][], [cookiecutter][], and [cruft][].
 - Supports GitHub Actions if targeting a `github.com` url (the default), and
   adds experimental GitLab CI support otherwise.
 - Includes several compiled backends using [pybind11][], with wheels produced
   for all platforms using [cibuildwheel][].
 - Provides [`sp-repo-review`][pypi-link] to evaluate existing repos against the
-  guidelines, with a WebAssembly version integrated with the guide. All checks
-  cross-linked.
+  guidelines, with a WebAssembly version integrated with the guide. Checks are
+  hyperlinked back to the guide.
 - Follows [PyPA][] best practices and regularly updated. Recent additions:
   - [PEP 639](https://peps.python.org/pep-0639): SPDX licenses
   - [PEP 735](https://peps.python.org/pep-0735): Dependency groups
@@ -134,22 +135,28 @@ backports structure with a small typing example.
 - GitHub Actions runs testing for the generation itself
   - Uses nox so cookie development can be checked locally
   - Uses uv for high performance CI
-- GitHub actions deploy
+- GitHub actions deployment
   - C++ backends include cibuildwheel for wheel builds
   - Uses PyPI trusted publisher deployment
+- A GitHub release configuration that skips common bot commits when
+  auto-generating release notes
 - Dependabot keeps actions up to date periodically, through useful pull requests
-- Formatting handled by pre-commit
+- A contributing guide
+- Formatting handled by pre-commit or prek
   - No reason not to be strict on a new project; remove what you don't want.
   - Includes MyPy - static typing
   - Includes Ruff - standard formatting, linting and autofixes
     - Replaces Flake8, isort, pyupgrade, yesqa, pycln, and dozens of plugins
   - Includes spell checking
+- One of several popular licenses
 - An pylint nox target can be used to run pylint, which integrated GHA
   annotations
-- A ReadTheDocs-ready Sphinx docs folder and `docs` dependency-group
-- A test folder and pytest `test` dependency-group
+- A ReadTheDocs-ready Sphinx or MkDocs `docs/` folder and `docs`
+  dependency-group
+- A `tests/` folder and pytest `test` dependency-group
 - A dev group for `uv run` integration
 - A noxfile is included with a few common targets
+- A README
 
 #### For developers:
 

docs/pages/guides/packaging_compiled.md

@@ -26,6 +26,14 @@ with render_cookie(backend="maturin", vcs=False) as maturin:
 ]]] -->
 <!-- [[[end]]] -->
 
+{: .highlight-title }
+
+> Quick start
+>
+> Once you've done this at least once, feel free to use
+> [our cookiecutter/copier template](https://github.com/scientific-python/cookie),
+> or `uv init` to get started quickly on new packages!
+
 # Packaging Compiled Projects
 
 There are a variety of ways to package compiled projects. In the past, the only
@@ -53,15 +61,18 @@ There are also classic setuptools plugins:
 - [scikit-build][]: Builds C/C++/Fortran using CMake.
 - [setuptools-rust][]: Builds Rust using Cargo.
 
-{: .important }
-
-Selecting a backend: If you are using Rust, use maturin. If you are using CUDA,
-use scikit-build-core. If you are using a classic language (C, C++, Fortran),
-then you can use either scikit-build-core or meson-python, depending on whether
-you prefer writing CMake or Meson. Meson is a lot more opinionated; it requires
-you use version control, it requires a README.md and LICENSE file. It requires
-your compiler be properly set up. Etc. While CMake can be as elegant as Meson,
-there are a lot of historical examples of poorly written CMake.
+{: .highlight-title }
+
+> Selecting a backend
+>
+> Selecting a backend: If you are using Rust, use maturin. If you are using
+> CUDA, use scikit-build-core. If you are using a classic language (C, C++,
+> Fortran), then you can use either scikit-build-core or meson-python, depending
+> on whether you prefer writing CMake or Meson. Meson is a lot more opinionated;
+> it requires you use version control, it requires a README.md and LICENSE file.
+> It requires your compiler be properly set up. Etc. While CMake can be as
+> elegant as Meson, there are a lot of historical examples of poorly written
+> CMake.
 
 ## pyproject.toml: build-system
 

docs/pages/guides/packaging_simple.md

@@ -8,6 +8,14 @@ parent: Topical Guides
 
 {% include toc.html %}
 
+{: .highlight-title }
+
+> Quick start
+>
+> Once you've done this at least once, feel free to use
+> [our cookiecutter/copier template](https://github.com/scientific-python/cookie),
+> or `uv init` to get started quickly on new packages!
+
 # Simple packaging
 
 Python packages can now use a modern build system instead of the classic but
@@ -32,7 +40,7 @@ tutorial][].
 > `pipx run hatch new --init` or with
 > [ini2toml](https://ini2toml.readthedocs.io/en/latest/).
 
-{: .highlight-title }
+{: .important-title }
 
 > Selecting a backend
 >
@@ -113,9 +121,8 @@ If you don't match your package name and import name (which you should except
 for very special cases), you will likely need extra configuration here.
 
 You should have a `README` {% rr PY002 %} and a `LICENSE` {% rr PY003 %} file.
-You should have a `docs/` folder {%
-rr PY004 %}. You should have a `/tests` folder {%
-rr PY005 %} (recommended) and/or a `src/<package>/tests` folder.
+You should have a `docs/` folder {% rr PY004 %}. You should have a `/tests`
+folder {% rr PY005 %} (recommended) and/or a `src/<package>/tests` folder.
 
 ## Versioning