formatting

docs/skills/zensical-docs/SKILL.md

@@ -24,38 +24,38 @@ Use this as a compact reference for Zensical mechanics and as the place to recor
 
 Open only what you need:
 
-- Official docs and source map: [./references/index.md](./references/index.md)
-- Zensical feature catalog and setup links: [./references/zensical-features.md](./references/zensical-features.md)
-- Theme, icons, and visual customization: [./references/theme-customization-and-icons.md](./references/theme-customization-and-icons.md)
-- Writing quality and review criteria: [./references/documentation-quality.md](./references/documentation-quality.md)
-- Navigation and discoverability patterns: [./references/discoverability-and-ia.md](./references/discoverability-and-ia.md)
-- Code-heavy docs and API reference patterns: [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md)
+- Official docs and source map: [source map](./references/index.md)
+- Zensical feature catalog and setup links: [feature catalog](./references/zensical-features.md)
+- Theme, icons, and visual customization: [theme customization](./references/theme-customization-and-icons.md)
+- Writing quality and review criteria: [documentation quality](./references/documentation-quality.md)
+- Navigation and discoverability patterns: [discoverability and IA](./references/discoverability-and-ia.md)
+- Code-heavy docs and API reference patterns: [code-heavy docs](./references/code-heavy-docs-and-mkdocstrings.md)
 
 ## Common Cases
 
 ### New docs project
 
 - Start with `uv run zensical new`.
-- Then review [./references/index.md](./references/index.md) and [./references/zensical-features.md](./references/zensical-features.md).
+- Then review the [source map](./references/index.md) and [feature catalog](./references/zensical-features.md).
 
 ### Restructuring docs or navigation
 
-- Review [./references/discoverability-and-ia.md](./references/discoverability-and-ia.md).
+- Review [discoverability and IA](./references/discoverability-and-ia.md).
 - Use it to decide overview pages, section structure, and cross-linking.
 
 ### Improving writing quality
 
-- Review [./references/documentation-quality.md](./references/documentation-quality.md).
+- Review [documentation quality](./references/documentation-quality.md).
 - Use it for page quality gates, trust signals, and review criteria.
 
 ### Adjusting theme or UI mechanics
 
-- Review [./references/theme-customization-and-icons.md](./references/theme-customization-and-icons.md).
+- Review [theme customization](./references/theme-customization-and-icons.md).
 - Use it for icons, color, theme extensions, and presentation choices.
 
 ### Documenting APIs or code-heavy systems
 
-- Review [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md).
+- Review [code-heavy docs](./references/code-heavy-docs-and-mkdocstrings.md).
 - Use it when generated API reference belongs alongside hand-authored docs.
 
 ## Preferences To Maintain Here

docs/skills/zensical-docs/references/code-heavy-docs-and-mkdocstrings.md

@@ -6,10 +6,10 @@ Use this reference when your docs include API surfaces, function/class documenta
 
 mkdocstrings helps generate and maintain API reference pages directly from code and docstrings, reducing drift between implementation and docs.
 
-Primary docs:
-- mkdocstrings home: https://mkdocstrings.github.io/
-- mkdocstrings Python handler: https://mkdocstrings.github.io/python/
-- Griffe (Python parsing engine): https://mkdocstrings.github.io/griffe/
+!!! info "Primary docs"
+   - [mkdocstrings home](https://mkdocstrings.github.io/)
+   - [mkdocstrings Python handler](https://mkdocstrings.github.io/python/)
+   - [Griffe Python parsing engine](https://mkdocstrings.github.io/griffe/)
 
 ## When to Use It
 
@@ -32,13 +32,13 @@ Primary docs:
 3. Create one API index page per package/domain.
 4. Expand coverage gradually from high-value modules first.
 
-General reference examples:
-- Zensical docs home and setup entry point: https://zensical.org/docs/
-- Zensical code blocks and authoring patterns: https://zensical.org/docs/authoring/code-blocks/
-- Zensical customization overview: https://zensical.org/docs/customization/
+!!! info "General reference examples"
+    - [Zensical docs home and setup entry point](https://zensical.org/docs/)
+    - [Zensical code blocks and authoring patterns](https://zensical.org/docs/authoring/code-blocks/)
+    - [Zensical customization overview](https://zensical.org/docs/customization/)
 
-Compatibility note:
-- Zensical is generally expected to remain compatible with MkDocs-style configuration patterns, but prefer Zensical-native documentation and examples when they cover the same behavior.
+!!! note "Compatibility"
+    Zensical is generally expected to remain compatible with MkDocs-style configuration patterns, but prefer Zensical-native documentation and examples when they cover the same behavior.
 
 ## Authoring Guidance for Docstrings
 

docs/skills/zensical-docs/references/discoverability-and-ia.md

@@ -13,9 +13,9 @@ Recommended top-level model:
 3. Reference (API, config, command catalog)
 4. Troubleshoot (symptoms, diagnostics, fixes)
 
-References:
-- Diataxis framework: https://diataxis.fr/
-- Divio documentation system: https://documentation.divio.com/
+!!! info "IA references"
+    - [Diataxis framework](https://diataxis.fr/)
+    - [Divio documentation system](https://documentation.divio.com/)
 
 ## Progressive Discoverability Pattern
 
@@ -47,11 +47,11 @@ Keep deep details in dedicated reference pages and link to them from task pages
 3. Place high-frequency tasks near the top.
 4. Keep section depth shallow where possible.
 
-Relevant Zensical configuration docs:
-- Navigation: https://zensical.org/docs/setup/navigation/
-- Search: https://zensical.org/docs/setup/search/
-- Header: https://zensical.org/docs/setup/header/
-- Footer: https://zensical.org/docs/setup/footer/
+!!! info "Relevant Zensical configuration docs"
+    - [Navigation setup](https://zensical.org/docs/setup/navigation/)
+    - [Search setup](https://zensical.org/docs/setup/search/)
+    - [Header setup](https://zensical.org/docs/setup/header/)
+    - [Footer setup](https://zensical.org/docs/setup/footer/)
 
 ## Link Strategy
 

docs/skills/zensical-docs/references/documentation-quality.md

@@ -10,10 +10,10 @@ Use this reference when writing or reviewing docs for clarity, correctness, and
 4. Make examples executable and verifiable.
 5. Prefer precise language over marketing language.
 
-Primary references:
-- Diataxis: https://diataxis.fr/
-- Divio documentation system: https://documentation.divio.com/
-- Write the Docs guide: https://www.writethedocs.org/guide/
+!!! info "Primary references"
+    - [Diataxis](https://diataxis.fr/)
+    - [Divio documentation system](https://documentation.divio.com/)
+    - [Write the Docs guide](https://www.writethedocs.org/guide/)
 
 ## Style and Readability
 
@@ -22,10 +22,10 @@ Primary references:
 - Prefer active voice and imperative instructions for task pages.
 - Add notes/warnings only for high-impact caveats.
 
-Source links:
-- Google developer style: https://developers.google.com/style
-- Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/welcome/
-- MDN writing guidelines: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines
+!!! info "Style sources"
+    - [Google developer style](https://developers.google.com/style)
+    - [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/)
+    - [MDN writing guidelines](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines)
 
 ## Task Page Quality Pattern
 

docs/skills/zensical-docs/references/index.md

@@ -4,40 +4,43 @@ Use this index to load only the source references needed for the current task.
 
 ## Zensical Official Docs
 
-- New project scaffolding (`uv run zensical new`): https://zensical.org/docs/
-- Home: https://zensical.org/docs/
-- Setup basics: https://zensical.org/docs/setup/basics/
-- Navigation setup: https://zensical.org/docs/setup/navigation/
-- Header setup and announcement bar: https://zensical.org/docs/setup/header/
-- Footer setup: https://zensical.org/docs/setup/footer/
-- Repository and content actions: https://zensical.org/docs/setup/repository/
-- Search setup: https://zensical.org/docs/setup/search/
-- Customization overview: https://zensical.org/docs/customization/
-- Additional CSS: https://zensical.org/docs/customization/#additional-css
-- Additional JavaScript: https://zensical.org/docs/customization/#additional-javascript
-- Theme extension and overrides: https://zensical.org/docs/customization/#extending-the-theme
-- Language setup: https://zensical.org/docs/setup/language/
-- Logo and icons: https://zensical.org/docs/setup/logo-and-icons/
-- Code blocks and annotations: https://zensical.org/docs/authoring/code-blocks/
-- Content tabs: https://zensical.org/docs/authoring/content-tabs/
-- Footnotes: https://zensical.org/docs/authoring/footnotes/
-- Tooltips: https://zensical.org/docs/authoring/tooltips/
+!!! info "Zensical official docs"
+    - [New project scaffolding](https://zensical.org/docs/) for `uv run zensical new`.
+    - [Home](https://zensical.org/docs/)
+    - [Setup basics](https://zensical.org/docs/setup/basics/)
+    - [Navigation setup](https://zensical.org/docs/setup/navigation/)
+    - [Header setup and announcement bar](https://zensical.org/docs/setup/header/)
+    - [Footer setup](https://zensical.org/docs/setup/footer/)
+    - [Repository and content actions](https://zensical.org/docs/setup/repository/)
+    - [Search setup](https://zensical.org/docs/setup/search/)
+    - [Customization overview](https://zensical.org/docs/customization/)
+    - [Additional CSS](https://zensical.org/docs/customization/#additional-css)
+    - [Additional JavaScript](https://zensical.org/docs/customization/#additional-javascript)
+    - [Theme extension and overrides](https://zensical.org/docs/customization/#extending-the-theme)
+    - [Language setup](https://zensical.org/docs/setup/language/)
+    - [Logo and icons](https://zensical.org/docs/setup/logo-and-icons/)
+    - [Code blocks and annotations](https://zensical.org/docs/authoring/code-blocks/)
+    - [Content tabs](https://zensical.org/docs/authoring/content-tabs/)
+    - [Footnotes](https://zensical.org/docs/authoring/footnotes/)
+    - [Tooltips](https://zensical.org/docs/authoring/tooltips/)
 
 ## Adjacent Documentation Quality Sources
 
-- Divio documentation system: https://documentation.divio.com/
-- Write the Docs guide: https://www.writethedocs.org/guide/
-- Google developer documentation style guide: https://developers.google.com/style
-- Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/welcome/
-- MDN writing guidelines: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines
-- Diataxis framework: https://diataxis.fr/
+!!! info "Documentation quality sources"
+    - [Divio documentation system](https://documentation.divio.com/)
+    - [Write the Docs guide](https://www.writethedocs.org/guide/)
+    - [Google developer documentation style guide](https://developers.google.com/style)
+    - [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/)
+    - [MDN writing guidelines](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines)
+    - [Diataxis framework](https://diataxis.fr/)
 
 ## Related Tooling References
 
-- Markdown guide: https://www.markdownguide.org/
-- Zensical setup and configuration entry point: https://zensical.org/docs/
-- Zensical customization reference: https://zensical.org/docs/customization/
-- mkdocstrings: https://mkdocstrings.github.io/
+!!! info "Related tooling"
+    - [Markdown guide](https://www.markdownguide.org/)
+    - [Zensical setup and configuration entry point](https://zensical.org/docs/)
+    - [Zensical customization reference](https://zensical.org/docs/customization/)
+    - [mkdocstrings](https://mkdocstrings.github.io/)
 
 ## Skill-Specific Deep Dives
 

docs/skills/zensical-docs/references/theme-customization-and-icons.md

@@ -15,11 +15,12 @@ Always start new projects with `uv run zensical new` so the baseline theme/confi
 
 ## Key Zensical Customization Surfaces
 
-- Customization overview: https://zensical.org/docs/customization/
-- Additional CSS: https://zensical.org/docs/customization/#additional-css
-- Additional JavaScript: https://zensical.org/docs/customization/#additional-javascript
-- Extending the theme: https://zensical.org/docs/customization/#extending-the-theme
-- Logo and icons setup: https://zensical.org/docs/setup/logo-and-icons/
+!!! info "Zensical sources"
+    - [Customization overview](https://zensical.org/docs/customization/)
+    - [Additional CSS](https://zensical.org/docs/customization/#additional-css)
+    - [Additional JavaScript](https://zensical.org/docs/customization/#additional-javascript)
+    - [Extending the theme](https://zensical.org/docs/customization/#extending-the-theme)
+    - [Logo and icons setup](https://zensical.org/docs/setup/logo-and-icons/)
 
 ## Colors and Accessibility
 
@@ -27,21 +28,22 @@ Always start new projects with `uv run zensical new` so the baseline theme/confi
 - Keep contrast high for body text, code blocks, and nav labels.
 - Test color changes on mobile and desktop, including search highlights and active nav states.
 
-General references:
-- Material design color guidance: https://m3.material.io/styles/color
-- WCAG overview: https://www.w3.org/WAI/standards-guidelines/wcag/
+!!! info "General references"
+    - [Material Design color guidance](https://m3.material.io/styles/color)
+    - [WCAG overview](https://www.w3.org/WAI/standards-guidelines/wcag/)
 
 ## Icons: Selection and Search Landing Pages
 
 If your theme supports icon sets through your docs stack, these search portals are useful:
 
-- Material Symbols search: https://fonts.google.com/icons
-- Font Awesome icons search: https://fontawesome.com/search
-- Simple Icons search: https://simpleicons.org/
-- Iconify icon set search: https://icon-sets.iconify.design/
-- Lucide icons: https://lucide.dev/icons/
+- [Material Symbols search](https://fonts.google.com/icons)
+- [Font Awesome icons search](https://fontawesome.com/search)
+- [Simple Icons search](https://simpleicons.org/)
+- [Iconify icon set search](https://icon-sets.iconify.design/)
+- [Lucide icons](https://lucide.dev/icons/)
 
-Tip: pick one primary icon family for navigation and status icons, then document naming conventions.
+!!! tip "Icon family consistency"
+    Pick one primary icon family for navigation and status icons, then document naming conventions.
 
 ## Extending the Theme Safely
 

docs/skills/zensical-docs/references/zensical-features.md

@@ -21,8 +21,8 @@ Always start a new docs project with `uv run zensical new`.
 - `navigation.top`: shows a back-to-top affordance.
 - `navigation.tracking`: keeps URL anchors in sync with active section.
 
-Source links:
-- https://zensical.org/docs/setup/navigation/
+!!! info "Source links"
+    - [Zensical navigation setup](https://zensical.org/docs/setup/navigation/)
 
 ### Code-Heavy Documentation
 
@@ -32,9 +32,9 @@ Source links:
 - Prefer mkdocstrings for generated API reference pages when documenting Python code.
 - Keep generated API pages linked from hand-authored task and concept docs.
 
-Source links:
-- https://zensical.org/docs/authoring/code-blocks/
-- https://mkdocstrings.github.io/
+!!! info "Source links"
+    - [Zensical code blocks](https://zensical.org/docs/authoring/code-blocks/)
+    - [mkdocstrings](https://mkdocstrings.github.io/)
 
 ### Cross-Page UX Consistency
 
@@ -42,19 +42,19 @@ Source links:
 - `content.tooltips`: improves tooltip behavior for links.
 - `content.footnote.tooltips`: inline footnote previews.
 
-Source links:
-- https://zensical.org/docs/authoring/content-tabs/
-- https://zensical.org/docs/authoring/tooltips/
-- https://zensical.org/docs/authoring/footnotes/
+!!! info "Source links"
+    - [Zensical content tabs](https://zensical.org/docs/authoring/content-tabs/)
+    - [Zensical tooltips](https://zensical.org/docs/authoring/tooltips/)
+    - [Zensical footnotes](https://zensical.org/docs/authoring/footnotes/)
 
 ### Search and Content Actions
 
 - `search.highlight`: highlights matches after search navigation.
 - `content.action.edit` and `content.action.view` (if repository integration is configured).
 
-Source links:
-- https://zensical.org/docs/setup/search/
-- https://zensical.org/docs/setup/repository/
+!!! info "Source links"
+    - [Zensical search setup](https://zensical.org/docs/setup/search/)
+    - [Zensical repository setup](https://zensical.org/docs/setup/repository/)
 
 ## Styling and Extensibility
 
@@ -64,11 +64,11 @@ Use site-level customization when docs need stronger visual affordances.
 - `extra_javascript`: add behavior enhancements.
 - Theme override directory (`custom_dir`) for template-level changes.
 
-Source links:
-- https://zensical.org/docs/customization/
-- https://zensical.org/docs/customization/#additional-css
-- https://zensical.org/docs/customization/#additional-javascript
-- https://zensical.org/docs/customization/#extending-the-theme
+!!! info "Source links"
+    - [Zensical customization overview](https://zensical.org/docs/customization/)
+    - [Additional CSS](https://zensical.org/docs/customization/#additional-css)
+    - [Additional JavaScript](https://zensical.org/docs/customization/#additional-javascript)
+    - [Extending the theme](https://zensical.org/docs/customization/#extending-the-theme)
 
 ## Practical Feature Selection Rules