fix: fix various docs issues

docs/authoring/code-blocks.md

@@ -217,7 +217,7 @@ Additional selectors can be set per-language:
 
     ``` toml
     [project.extra.annotate]
-    json: [".s2"] # (1)!
+    json = [".s2"] # (1)!
     ```
 
     1.  [`.s2`][s2] is the name of the lexeme that [Pygments] generates for

docs/authoring/images.md

@@ -118,7 +118,7 @@ but it's always possible to use the [Markdown in HTML] extension with literal
 
 <div class="result">
   <figure>
-    <img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa?text=–%20Image%20–" width="300" />
+    <img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa?text=–%20Image%20–" width="300" alt="placeholder image" />
     <figcaption>Image caption</figcaption>
   </figure>
 </div>
@@ -144,7 +144,7 @@ browsers without support:
 ```
 
 <div class="result" markdown>
-  <img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa?text=–%20Image%20–" width="300" />
+  <img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa?text=–%20Image%20–" width="300" alt="placeholder image" />
 </div>
 
   [lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr

docs/community/contribute/index.md

@@ -217,7 +217,7 @@ clarity, rather than automated outputs.
 ### LLM-generated issues
 
 We are seeing an increasing number of bug reports, change requests and pull
-requests generated with large language models (LLMs) that are not a carefully
+requests generated with large language models (LLMs) that are not carefully
 reviewed or edited before submitting.
 
 LLM-generated reports are often verbose, unfocused, and rarely adhere to our

docs/community/faqs.md

@@ -103,7 +103,7 @@ Markdown extensions work in Zensical as they do in MkDocs since we use the same
 Python Markdown parser. You just need to install the Markdown extension into
 your Python (virtual) environment and [configure it].
 
-  [configure it]: https://zensical.org/docs/setup/extensions/
+  [configure it]: https://zensical.org/docs/setup/extensions/about/
 
 ### Why can I not use absolute links with Zensical?
 

docs/community/how-we-work.md

@@ -151,26 +151,22 @@ sequenceDiagram
    complex requirements and workflows of professional users. While public
    discussions in Open Source projects often circle around specific features and
    implementation details, we use this space to have higher-level discussions
-   about the [opportunities] we need Zensical to address, on the unmet needs and
+   about the opportunities we need Zensical to address, on the unmet needs and
    pain points of people who work with it every day. We also offer private channels
    and NDAs to discuss confidential matters.
 
-  [opportunities]: https://zensical.org/spark/methodology/#stage-1-opportunities
-
 6. Once we have established a thorough understanding of the opportunity space,
    we will produce [proposals] for possible solutions. We explore different
    approaches together with our members in Zensical Spark, to ensure that all
    options and trade-offs have been considered.
 
-  [proposals]: https://zensical.org/spark/methodology/#stage-2-proposals
+  [proposals]: https://zensical.org/spark/proposals
 
-7. From the exploration proposals we distill a [design document] that provides a
+7. From the exploration proposals we distill a design document that provides a
    clear definition of the opportunities it addresses, alternative solutions
    that were considered, details of designs, scope, and key implementation
    decisions as well as identified risks and mitigation strategies.
 
-  [design document]: https://zensical.org/spark/methodology/#stage-3-design
-
 8. We elicit feedback from members in Zensical Spark and iterate over the
    process as needed.
 
@@ -222,5 +218,3 @@ sequenceDiagram
 
 * Discussions within Zensical Spark organized to elicit contributions from
   groups of users with complex requirements and workflows.
-
-

docs/create-your-site.md

@@ -13,13 +13,13 @@ your project to be located and enter:
 
 [installed]: get-started.md
 
-```
+``` sh
 zensical new .
 ```
 
 This creates the following structure:
 
-``` .sh
+``` text
 .
 ├─ .github/workflows
 │  └─ docs.yml

docs/customization.md

@@ -296,7 +296,7 @@ The `overrides` directory is also the place for adding a 404 error page, which
 can be configured as a fallback in your web server. If you set `custom_dir` to
 `overrides`, use the following layout:
 
-```
+``` text
 ├─ overrides/
 │  └─ 404.html
 └─ zensical.toml

docs/get-started.md

@@ -101,7 +101,7 @@ your `pyproject.toml`, use:
 
   [uv]: https://docs.astral.sh/uv/
 
-```
+``` sh
 uv init
 uv add --dev zensical
 uv run zensical

docs/setup/versioning.md

@@ -17,7 +17,7 @@ solution until we introduce [native versioning support].
 
 We provide a fork of [mike] that you can install with `pip`:
 
-```
+``` sh
 pip install git+https://github.com/squidfunk/mike.git
 ```