From 2d4c8e8b4310d9ff06519623361e4fc4effcf1ed Mon Sep 17 00:00:00 2001
From: squidfunk <martin.donath@squidfunk.com>
Date: Sun, 2 Nov 2025 20:56:47 +0100
Subject: [PATCH] workspace:refactor - improve new project files

---
 python/zensical/bootstrap/docs/index.md    | 102 +++++++++---------
 python/zensical/bootstrap/docs/markdown.md | 115 +++++++++++++++------
 python/zensical/bootstrap/zensical.toml    |  90 ++++++++--------
 3 files changed, 172 insertions(+), 135 deletions(-)

diff --git a/python/zensical/bootstrap/docs/index.md b/python/zensical/bootstrap/docs/index.md
index e61fc8e..3b76a8a 100644
--- a/python/zensical/bootstrap/docs/index.md
+++ b/python/zensical/bootstrap/docs/index.md
@@ -1,82 +1,81 @@
 ---
-icon: lucide/hand
+icon: lucide/rocket
 ---
 
-# Welcome to Zensical!
+# Get started
 
-With Zensical, you can author professional documentation with minimal
-fuss thanks to the *batteries included* approach.
+For full documentation visit [zensical.org](https://zensical.org/docs/).
 
-These generated pages serve to showcase some of what you can do with Zensical
-and to show you examples of using the various elements available to you as an
-author. Links to the relevant documentation let you explore further.
+## Commands
 
-The configuration file generated by `zensical new` can serve as a basis for your
-own configuration. It contains plenty comments and links to the documentation.
+* [`zensical new`][new] - Create a new project
+* [`zensical serve`][serve] - Start local web server
+* [`zensical build`][build] - Build your site
 
-## Admonitions
+  [new]: https://zensical.org/docs/usage/new/
+  [serve]: https://zensical.org/docs/usage/preview/
+  [build]: https://zensical.org/docs/usage/build/
+
+## Examples
+
+### Admonitions
+
+> Go to [documentation](https://zensical.org/docs/authoring/admonitions/)
 
 !!! note
+
     This is a **note** admonition. Use it to provide helpful information.
 
 !!! warning
+
     This is a **warning** admonition. Be careful!
 
-[Documentation ->](https://zensical.org/docs/authoring/admonitions)
+### Details
 
-### Collapsible Sections (Details)
+> Go to [documentation](https://zensical.org/docs/authoring/admonitions/#collapsible-blocks)
 
 ??? info "Click to expand for more info"
+    
     This content is hidden until you click to expand it.
     Great for FAQs or long explanations.
 
-[Documentation ->](https://zensical.org/docs/authoring/admonitions/#collapsible-blocks)
-
-## Buttons
-
-[Subscribe to our newsletter](#buttons){ .md-button .md-button--primary }
-
-[Documentation ->](https://zensical.org/docs/authoring/buttons)
-
-
 ## Code Blocks
 
-Zensical uses [Pygments] to highlight code blocks.
+> Go to [documentation](https://zensical.org/docs/authoring/code-blocks/)
 
-[Pygments]: https://pygments.org/
-
-```python linenums="1" hl_lines="2" title="Code blocks"
+``` python hl_lines="2" title="Code blocks"
 def greet(name):
     print(f"Hello, {name}!") # (1)!
 
-greet("Zensical")
+greet("Python")
 ```
 
-1.  :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
-    text__, images, ... basically anything that can be written in Markdown.
+1.  > Go to [documentation](https://zensical.org/docs/authoring/code-blocks/#code-annotations)
 
-Code can also be highlighted inline: `#!python print("Hello from Python!")`.
+    Code annotations allow to attach notes to lines of code.
 
-[Documentation ->](http://localhost:8000/docs/authoring/code-blocks)
+Code can also be highlighted inline: `#!python print("Hello, Python!")`.
 
 ## Content tabs
 
+> Go to [documentation](https://zensical.org/docs/authoring/content-tabs/)
+
 === "Python"
 
-    ```python
+    ``` python
     print("Hello from Python!")
     ```
 
-=== "JavaScript"
+=== "Rust"
 
-    ```javascript
-    console.log("Hello from JavaScript!");
+    ``` rs
+    println!("Hello from Rust!");
     ```
 
-[Documentation ->](https:///docs/authoring/content-tabs/)
-
 ## Diagrams
 
+> Go to [documentation](https://zensical.org/docs/authoring/diagrams/)
+
 ``` mermaid
 graph LR
   A[Start] --> B{Error?};
@@ -86,19 +85,21 @@ graph LR
   B ---->|No| E[Yay!];
 ```
 
-[Read the documentation](https://zensical.org/docs/authoring/diagrams)
-
 ## Footnotes
 
-Here's a sentence with a footnote.[^1] Footnote tooltips are turned on,
-so you can just hover over the footnote to see it.
+> Go to [documentation](https://zensical.org/docs/authoring/footnotes/)
+
+Here's a sentence with a footnote.[^1]
+
+Hover it, to see a tooltip.
 
 [^1]: This is the footnote.
 
-[Documentation ->](https://zensical.org/docs/authoring/footnotes)
 
 ## Formatting
 
+> Go to [documentation](https://zensical.org/docs/authoring/formatting/)
+
 - ==This was marked (highlight)==
 - ^^This was inserted (underline)^^
 - ~~This was deleted (strikethrough)~~
@@ -106,11 +107,9 @@ so you can just hover over the footnote to see it.
 - A^T^A
 - ++ctrl+alt+del++
 
-[Documentation ->](https://zensical.org/docs/authoring/formatting)
-
 ## Icons, Emojis
 
-Zenscial supports GitHub-style emoji shortcodes:
+> Go to [documentation](https://zensical.org/docs/authoring/icons-emojis/)
 
 * :sparkles: `:sparkles:`
 * :rocket: `:rocket:`
@@ -118,12 +117,9 @@ Zenscial supports GitHub-style emoji shortcodes:
 * :memo: `:memo:`
 * :eyes: `:eyes:`
 
-[Documentation ->](https://zensical.org/docs/authoring/icons-emojis/)
-
 ## Maths
 
-Mathematical formulae can be written using LaTeX syntax and rendered using
-MathJax.
+> Go to [documentation](https://zensical.org/docs/authoring/math/)
 
 $$
 \cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
@@ -136,8 +132,6 @@ $$
     to configure it on all your pages if they are more Maths-heavy than these
     simple starter pages.
 
-[Read the documentation](https://zensical.org/docs/authoring/math)
-
 <script id="MathJax-script" async src="https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"></script>
 <script>
   window.MathJax = {
@@ -156,17 +150,17 @@ $$
 
 ## Task Lists
 
+> Go to [documentation](https://zensical.org/docs/authoring/lists/#using-task-lists)
+
 * [x] Install Zensical
 * [x] Configure `zensical.toml`
 * [x] Write amazing documentation
 * [ ] Deploy anywhere
 
-[Documentation ->](https://zensical.org/docs/authoring/lists/#using-task-lists)
-
 ## Tooltips
 
+> Go to [documentation](https://zensical.org/docs/authoring/tooltips/)
+
 [Hover me][example]
 
   [example]: https://example.com "I'm a tooltip!"
-
-[Documentation ->](https://zensical.org/docs/authoring/tooltips)
diff --git a/python/zensical/bootstrap/docs/markdown.md b/python/zensical/bootstrap/docs/markdown.md
index 9d27ae0..7ea6d1e 100644
--- a/python/zensical/bootstrap/docs/markdown.md
+++ b/python/zensical/bootstrap/docs/markdown.md
@@ -2,48 +2,97 @@
 icon: simple/markdown
 ---
 
-# Intro to Markdown
+# Markdown in 5min
 
-!!! warning ""
-    Zensical uses [Python Markdown] to be compatible with [Material for MkDocs].
-    In the medium term, we are considering adding support or CommonMark and
-    providing tools for existing projects to migrate. Check out our [roadmap].
+## Headers
+```
+# H1 Header
+## H2 Header
+### H3 Header
+#### H4 Header
+##### H5 Header
+###### H6 Header
+```
 
-[Python Markdown]: https://python-markdown.github.io/
-[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/
-[CommonMark]: https://commonmark.org/
-[roadmap]: https://zensical.org/about/roadmap/
+## Text formatting
+```
+**bold text**
+*italic text*
+***bold and italic***
+~~strikethrough~~
+`inline code`
+```
 
-Text in Markdown can be _italicized_, __bold face__.
+## Links and images
+```
+[Link text](https://example.com)
+[Link with title](https://example.com "Hover title")
+![Alt text](image.jpg)
+![Image with title](image.jpg "Image title")
+```
 
-Markdown allows you to produce bullet point lists:
+## Lists
+```
+Unordered:
+- Item 1
+- Item 2
+  - Nested item
 
-* bullet
-* point
-* list
-    * nested
-    * list
+Ordered:
+1. First item
+2. Second item
+3. Third item
+```
 
-as well as numbered lists:
+## Blockquotes
+```
+> This is a blockquote
+> Multiple lines
+>> Nested quote
+```
 
-1. numbered
-2. list
-    1. nested
-    2. list
+## Code blocks
+````
+```javascript
+function hello() {
+  console.log("Hello, world!");
+}
+```
+````
 
-> If you can't explain it to a six year old, you don't understand it
-> yourself.<br> (Albert Einstein)
+## Tables
+```
+| Header 1 | Header 2 | Header 3 |
+|----------|----------|----------|
+| Row 1    | Data     | Data     |
+| Row 2    | Data     | Data     |
+```
 
+## Horizontal rule
+```
+---
+or
+***
+or
+___
+```
 
-| Feature        | Supported | Notes                      |
-| -------------- | --------- | -------------------------- |
-| Admonitions    | ✅         | Native support            |
-| Code Highlight | ✅         | Pygments & Superfences    |
-| Task Lists     | ✅         | Pymdown extensions        |
-| Emojis         | ✅         | GitHub-style emoji        |
+## Task lists
+```
+- [x] Completed task
+- [ ] Incomplete task
+- [ ] Another task
+```
 
+## Escaping characters
+```
+Use backslash to escape: \* \_ \# \`
+```
 
-<figure markdown="span">
-  ![Image title](https://dummyimage.com/600x400/){ width="300" }
-  <figcaption>Image caption</figcaption>
-</figure>
+## Line breaks
+```
+End a line with two spaces  
+to create a line break.
+
+Or use a blank line for a new paragraph.
+```
\ No newline at end of file
diff --git a/python/zensical/bootstrap/zensical.toml b/python/zensical/bootstrap/zensical.toml
index ae24204..ac28559 100644
--- a/python/zensical/bootstrap/zensical.toml
+++ b/python/zensical/bootstrap/zensical.toml
@@ -10,31 +10,31 @@
 
 # The site_name is shown in the page header and the browser window title
 #
-# Read more: https://zensical.org/docs/setup/basics#site_name
-site_name = "My Zensical project"
+# Read more: https://zensical.org/docs/setup/basics/#site_name
+site_name = "Documentation"
 
 # The site_description is included in the HTML head and should contain a
 # meaningful description of the site content for use by search engines.
 #
-# Read more: https://zensical.org/docs/setup/basics#site_description
+# Read more: https://zensical.org/docs/setup/basics/#site_description
 site_description = "A new project generated from the default template project."
 
 # The site_author attribute. This is used in the HTML head element.
 #
-# Read more: https://zensical.org/docs/setup/basics#site_author
+# Read more: https://zensical.org/docs/setup/basics/#site_author
 site_author = "<your name here>"
 
 # The site_url is the canonical URL for your site. When building online
 # documentation you should set this.
-# Read more: https://zensical.org/docs/setup/basics#site_url
+# Read more: https://zensical.org/docs/setup/basics/#site_url
 #site_url = "https://www.example.com/"
 
 # The copyright notice appears in the page footer and can contain an HTML
 # fragment.
 #
-# Read more: https://zensical.org/docs/setup/basics#copyright
+# Read more: https://zensical.org/docs/setup/basics/#copyright
 copyright = """
-(c) 2025 your name here
+Copyright &copy; 2025 The authors
 """
 
 # Zensical supports both implicit navigation and explicitly defined navigation.
@@ -43,11 +43,11 @@ copyright = """
 # "docs_dir". The definition below demonstrates how a navigation structure
 # can be defined using TOML syntax.
 #
-# Read more: https://zensical.org/docs/setup/setting-up-navigation
-nav = [
-  {"Welcome" = "index.md"},
-  {"Intro to Markdown" = "markdown.md"},
-]
+# Read more: https://zensical.org/docs/setup/navigation/
+# nav = [
+#   { "Get started" = "index.md" },
+#   { "Markdown in 5min" = "markdown.md" },
+# ]
 
 # ----------------------------------------------------------------------------
 # Section for configuring theme options
@@ -55,9 +55,7 @@ nav = [
 [project.theme]
 
 # change this to "classic" to use the traditional Material for MkDocs look.
-#
-# TODO: add link to docs
-variant = "modern"
+#variant = "classic"
 
 # Zensical allows you to override specific blocks, partials, or whole
 # templates as well as to define your own templates. To do this, uncomment
@@ -74,7 +72,7 @@ variant = "modern"
 # must be relative to the "docs_dir".
 #
 # Read more:
-# - https://zensical.org/docs/setup/changing-the-logo-and-icons/#favicon
+# - https://zensical.org/docs/setup/logo-and-icons/#favicon
 # - https://developer.mozilla.org/en-US/docs/Glossary/Favicon
 #
 #favicon = "assets/images/favicon.png"
@@ -90,7 +88,7 @@ variant = "modern"
 # the documentation for details.
 #
 # Read more:
-# - https://zensical.org/docs/docs/setup/changing-the-language/
+# - https://zensical.org/docs/setup/language/
 #
 language = "en"
 
@@ -99,19 +97,19 @@ language = "en"
 features = [
     # Zensical includes an announcement bar. This feature allows users to
     # dismiss it then they have read the announcement.
-    # https://zensical.org/docs/setup/setting-up-the-header/#announcement-bar
+    # https://zensical.org/docs/setup/header/#announcement-bar
     "announce.dismiss",
 
     # If you have a repository configured and turn feature this on, Zensical
     # will generate an edit button for the page. This works for common
     # repository hosting services.
-    # https://zensical.org/docs/setup/adding-a-git-repository/#code-actions
+    # https://zensical.org/docs/setup/repository/#code-actions
     #"content.action.edit",
 
     # If you have a repository configured and turn feature this on, Zensical
     # will generate a button that allows the user to view the Markdown
     # code for the current page.
-    # https://zensical.org/docs/setup/adding-a-git-repository/#code-actions
+    # https://zensical.org/docs/setup/repository/#code-actions
     #"content.action.view",
 
     # Code annotations allow you to add an icon with a tooltip to your
@@ -146,89 +144,89 @@ features = [
 
     # With this feature enabled, Zensical will automatically hide parts
     # of the header when the user scrolls past a certain point.
-    # https://zensical.org/docs/setup/setting-up-the-header/#automatic-hiding
-    "header.autohide",
+    # https://zensical.org/docs/setup/header/#automatic-hiding
+    # "header.autohide",
 
     # Turn on this feature to expand all collapsible sections in the
     # navigation sidebar by default.
-    # https://zensical.org/docs/setup/setting-up-navigation/#navigation-expansion
+    # https://zensical.org/docs/setup/navigation/#navigation-expansion
     # "navigation.expand",
 
     # This feature turns on navigation elements in the footer that allow the
     # user to navigate to a next or previous page.
-    # http://zensical.org/docs/setup/setting-up-the-footer/#navigation
+    # https://zensical.org/docs/setup/footer/#navigation
     "navigation.footer",
 
     # When section index pages are enabled, documents can be directly attached
     # to sections, which is particularly useful for providing overview pages.
-    # http://zensical.org/docs/setup/setting-up-navigation/#section-index-pages
+    # https://zensical.org/docs/setup/navigation/#section-index-pages
     "navigation.indexes",
 
-    # When instant loading is enabled, clicks on all internal links will be
+    # When instant navigation is enabled, clicks on all internal links will be
     # intercepted and dispatched via XHR without fully reloading the page.
-    # http://zensical.org/docs/setup/setting-up-navigation/#instant-loading
+    # https://zensical.org/docs/setup/navigation/#instant-navigation
     "navigation.instant",
 
     # With instant prefetching, your site will start to fetch a page once the
     # user hovers over a link. This will reduce the perceived loading time
     # for the user.
-    # http://zensical.org/docs/setup/setting-up-navigation/#instant-prefetching
+    # https://zensical.org/docs/setup/navigation/#instant-prefetching
     "navigation.instant.prefetch",
 
     # In order to provide a better user experience on slow connections when
     # using instant navigation, a progress indicator can be enabled.
-    # http://zensical.org/docs/setup/setting-up-navigation/#progress-indicator
+    # https://zensical.org/docs/setup/navigation/#progress-indicator
     #"navigation.instant.progress"
 
     # When navigation paths are activated, a breadcrumb navigation is rendered
     # above the title of each page
-    # http://zensical.org/docs/setup/setting-up-navigation/#navigation-path
+    # https://zensical.org/docs/setup/navigation/#navigation-path
     "navigation.path",
 
     # When pruning is enabled, only the visible navigation items are included
     # in the rendered HTML, reducing the size of the built site by 33% or more.
-    # http://zensical.org/docs/setup/setting-up-navigation/#navigation-pruning
+    # https://zensical.org/docs/setup/navigation/#navigation-pruning
     #"navigation.prune",
 
     # When sections are enabled, top-level sections are rendered as groups in
     # the sidebar for viewports above 1220px, but remain as-is on mobile.
-    # http://zensical.org/docs/setup/setting-up-navigation/#navigation-sections
+    # https://zensical.org/docs/setup/navigation/#navigation-sections
     "navigation.sections",
 
     # When tabs are enabled, top-level sections are rendered in a menu layer
     # below the header for viewports above 1220px, but remain as-is on mobile.
-    # http://zensical.org/docs/setup/setting-up-navigation/#navigation-tabs
+    # https://zensical.org/docs/setup/navigation/#navigation-tabs
     #"navigation.tabs",
 
     # When sticky tabs are enabled, navigation tabs will lock below the header
     # and always remain visible when scrolling down.
-    # http://zensical.org/docs/setup/setting-up-navigation/#sticky-navigation-tabs
+    # https://zensical.org/docs/setup/navigation/#sticky-navigation-tabs
     #"navigation.tabs.sticky",
 
     # A back-to-top button can be shown when the user, after scrolling down,
     # starts to scroll up again.
-    # http://zensical.org/docs/setup/setting-up-navigation/#back-to-top-button
+    # https://zensical.org/docs/setup/navigation/#back-to-top-button
     "navigation.top",
 
     # When anchor tracking is enabled, the URL in the address bar is
     # automatically updated with the active anchor as highlighted in the table
     # of contents.
-    # http://zensical.org/docs/setup/setting-up-navigation/#anchor-tracking
+    # https://zensical.org/docs/setup/navigation/#anchor-tracking
     "navigation.tracking",
 
     # When search highlighting is enabled and a user clicks on a search result,
     # Zensical will highlight all occurrences after following the link.
-    # https://zensical.org/docs/setup/setting-up-site-search/#search-highlighting
+    # https://zensical.org/docs/setup/search/#search-highlighting
     "search.highlight",
 
     # When anchor following for the table of contents is enabled, the sidebar
     # is automatically scrolled so that the active anchor is always visible.
-    # https://zensical.org/docs/setup/setting-up-navigation/#anchor-following
+    # https://zensical.org/docs/setup/navigation/#anchor-following
     # "toc.follow"
 
     # When navigation integration for the table of contents is enabled, it is
     # always rendered as part of the navigation sidebar on the left.
-    # https://zensical.org/docs/setup/setting-up-navigation/#navigation-integration
+    # https://zensical.org/docs/setup/navigation/#navigation-integration
     #"toc.integrate"
 ]
 
@@ -238,7 +236,7 @@ features = [
 #
 # The path provided should be relative to the "docs_dir".
 #
-# Read more: http://zensical.org/docs/customization/#additional-css
+# Read more: https://zensical.org/docs/customization/#additional-css
 #
 #extra_css = ["assets/stylesheets/extra.css"]
 
@@ -247,7 +245,7 @@ features = [
 #
 # The path provided should be relative to the "docs_dir".
 #
-# Read more: http://zensical.org/docs/customization/#additional-javascript
+# Read more: https://zensical.org/docs/customization/#additional-javascript
 #extra_javascript = ["assets/javascript/extra.js"]
 
 # ----------------------------------------------------------------------------
@@ -257,10 +255,8 @@ features = [
 # customized.
 #
 # Read more:
-# - https://zensical.org/docs/setup/changing-the-colors
+# - https://zensical.org/docs/setup/colors/
 # ----------------------------------------------------------------------------
-
-# TODO: use the version from "web"
 [[project.theme.palette]]
 scheme = "default"
 toggle.icon = "lucide/sun"
@@ -277,7 +273,6 @@ toggle.name = "Switch to light mode"
 # of suitably licensed fonts. There are options for a normal text font and for
 # a monospaced font used in code blocks.
 # ----------------------------------------------------------------------------
-# These are the defaults
 #[project.theme.font]
 #text = "Inter"
 #code = "Jetbrains Mono"
@@ -294,14 +289,13 @@ toggle.name = "Switch to light mode"
 # There are other icons you can customize. See the documentation for details.
 #
 # Read more:
-# - https://zensical.org/docs/setup/changing-the-logo-and-icons
-# - http://zensical.org/docs/authoring/icons-emojis/#search
+# - https://zensical.org/docs/setup/logo-and-icons
+# - https://zensical.org/docs/authoring/icons-emojis/#search
 # ----------------------------------------------------------------------------
 #[project.theme.icon]
 #logo = "lucide/smile"
 #repo = "lucide/smile"
 
-
 # ----------------------------------------------------------------------------
 # The "extra" section contains miscellaneous settings.
 # ----------------------------------------------------------------------------