docs: add clearer pyproject configuration guidance (psf#5026)

mitre88 · pre-commit-ci[bot] · web-flow · commit 69705deb8776 · 2026-03-08T17:22:44.000-05:00
Co-authored-by: pre-commit-ci[bot] &lt;66853113+pre-commit-ci[bot]@users.noreply.github.com&gt;
diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
@@ -513,6 +513,11 @@ As the file extension suggests, `pyproject.toml` is a
 different tools. _Black_ is using the `[tool.black]` section. The option keys are the
 same as long names of options on the command line.
 
+Most command-line options can be configured in `[tool.black]` by using their long name
+without the leading `--` (for example, `--line-length` becomes `line-length`). Options
+that cannot be configured in `pyproject.toml` are called out explicitly in the option
+reference above.
+
 Note that you have to use single-quoted strings in TOML for regular expressions. It's
 the equivalent of r-strings in Python. Multiline strings are treated as verbose regular
 expressions by Black. Use `[ ]` to denote a significant space character.
@@ -538,6 +543,38 @@ extend-exclude = '''
 
 </details>
 
+<details>
+<summary>More complete <code>pyproject.toml</code> template</summary>
+
+```toml
+[tool.black]
+line-length = 88
+target-version = ["py311"]
+required-version = "26"
+include = '\.pyi?$'
+
+# Formatting behavior
+skip-string-normalization = false
+skip-magic-trailing-comma = false
+preview = false
+unstable = false
+
+# File collection
+extend-exclude = '''
+(
+  ^/foo.py
+  | .*_pb2.py
+)
+'''
+force-exclude = '''
+(
+  ^/generated/
+)
+'''
+```
+
+</details>
+
 ### Lookup hierarchy
 
 Command-line options have defaults that you can see in `--help`. A `pyproject.toml` can
