john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

swapped docs symlink

Browse Source
This commit is contained in:
John Lancaster
2026-08-07 21:07:23 -05:00
parent 5005cd7001
commit f240486a7e
92 changed files with 69 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/personal_mcp/docs/skills/zensical-docs/references/code-heavy-docs-and-mkdocstrings.md
+63
View File
@@ -0,0 +1,63 @@
# Code-Heavy Documentation with mkdocstrings
Use this reference when your docs include API surfaces, function/class documentation, and source-driven technical reference.
## Why mkdocstrings
mkdocstrings helps generate and maintain API reference pages directly from code and docstrings, reducing drift between implementation and docs.
!!! 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
- You maintain Python modules/classes/functions that need searchable reference docs.
- You want hand-written concept/task docs plus generated API reference pages.
- You need consistent signatures, type hints, and docstring rendering.
## Recommended Documentation Split
1. Hand-authored docs for concepts, architecture, and tasks.
2. Generated docs (mkdocstrings) for API details.
3. Cross-links in both directions:
- task pages link to specific API entries
- API pages link to practical guides and examples
## Minimal Integration Pattern
1. Add mkdocstrings and a Python handler package to project dependencies.
2. Configure the Zensical docs toolchain to enable mkdocstrings within the site build.
3. Create one API index page per package/domain.
4. Expand coverage gradually from high-value modules first.
!!! 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/)
!!! 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
- Begin with a one-line summary in imperative or descriptive form.
- Document parameters, return values, raised exceptions, and side effects.
- Include short examples for non-obvious usage.
- Keep terminology aligned with task docs and architecture pages.
## Quality Gates for Code-Heavy Docs
- API pages build cleanly and include expected modules.
- Symbols are grouped by domain, not dumped in one long page.
- Public APIs have meaningful docstrings before publishing.
- Generated reference pages are linked from user-facing docs.
- Search can find both conceptual guides and concrete API entries.
## Common Pitfalls
- Treating generated API docs as a replacement for task documentation.
- Publishing API pages without module-level context.
- Letting undocumented public APIs accumulate.
- Not reviewing generated pages after refactors.
src/personal_mcp/docs/skills/zensical-docs/references/discoverability-and-ia.md
+74
View File
@@ -0,0 +1,74 @@
# Discoverability and Information Architecture
Use this reference to design docs that are progressively discoverable from overview to implementation detail.
## IA Model
Organize by user intent, then by product area.
Recommended top-level model:
1. Learn (concepts, architecture, mental models)
2. Do (task/how-to paths)
3. Reference (API, config, command catalog)
4. Troubleshoot (symptoms, diagnostics, fixes)
!!! info "IA references"
- [Diataxis framework](https://diataxis.fr/)
- [Divio documentation system](https://documentation.divio.com/)
## Progressive Discoverability Pattern
### Layer 1: Section Overview
Each section starts with an index page containing:
- What this section is for
- Who should read it
- Common journeys
- Links to key tasks and references
### Layer 2: Task or Concept Pages
Each page includes:
- 1-2 sentence purpose
- prerequisites
- internal links to references and next steps
### Layer 3: Deep Reference
Keep deep details in dedicated reference pages and link to them from task pages when needed.
## Navigation Design Rules
1. Keep navigation labels user-facing and action-oriented.
2. Avoid duplicate labels in separate branches.
3. Place high-frequency tasks near the top.
4. Keep section depth shallow where possible.
!!! 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
- Every deep page should have at least one inbound link from a higher-level index page.
- Add "See also" blocks for neighboring tasks.
- Link to source-of-truth reference pages instead of duplicating config tables.
## Search Optimization for Docs
- Put key terms in title and first paragraph.
- Use specific H2/H3 headings that match user query language.
- Keep repeated boilerplate minimal so snippets stay informative.
## Review Heuristics
A documentation journey is healthy when:
- users can identify their path within 10 seconds on a section index page
- users can complete primary tasks without opening more than 2-3 tabs
- users can recover from common errors without external support tickets
src/personal_mcp/docs/skills/zensical-docs/references/documentation-quality.md
+54
View File
@@ -0,0 +1,54 @@
# Documentation Quality Best Practices
Use this reference when writing or reviewing docs for clarity, correctness, and trust.
## Core Writing Principles
1. Write for a specific audience and task.
2. Lead with outcomes, not internal implementation details.
3. Keep concepts, tasks, and references distinct.
4. Make examples executable and verifiable.
5. Prefer precise language over marketing language.
!!! 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
- Use consistent terminology and avoid synonym drift.
- Use short paragraphs and meaningful headings.
- Prefer active voice and imperative instructions for task pages.
- Add notes/warnings only for high-impact caveats.
!!! 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
Each task page should include:
1. Goal and scope.
2. Prerequisites (permissions, versions, environment).
3. Step-by-step procedure.
4. Expected result and verification command/output.
5. Common failure modes and recovery path.
6. Related links (concept, reference, troubleshooting).
## Quality Gates Before Publish
- Accuracy: commands and code examples are validated.
- Completeness: no critical missing steps.
- Discoverability: page is linked from at least one overview page.
- Freshness: version-specific notes and dates are present where needed.
- Accessibility: heading structure and link text are clear.
## Anti-Patterns
- Mixing conceptual explanation and long procedural flow in the same section without structure.
- Hiding prerequisites mid-page.
- Using screenshots as the only source of truth for commands.
- Publishing pages with no owner and no review cadence.
src/personal_mcp/docs/skills/zensical-docs/references/index.md
+48
View File
@@ -0,0 +1,48 @@
# Zensical Docs Skill References
Use this index to load only the source references needed for the current task.
## Zensical Official Docs
!!! 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
!!! 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
!!! 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
- Theme customization, colors, icons: [./theme-customization-and-icons.md](./theme-customization-and-icons.md)
- Code-heavy docs with mkdocstrings: [./code-heavy-docs-and-mkdocstrings.md](./code-heavy-docs-and-mkdocstrings.md)
src/personal_mcp/docs/skills/zensical-docs/references/theme-customization-and-icons.md
+62
View File
@@ -0,0 +1,62 @@
# Theme Customization, Colors, and Icons
Use this reference when you want documentation that feels intentional and brand-aligned while preserving readability and accessibility.
## Start from the Scaffold
Always start new projects with `uv run zensical new` so the baseline theme/config scaffolding is in place before customization.
## Customization Strategy
1. Configure theme and feature flags in the project config first.
2. Apply visual tokens (colors, spacing, typography) in a shared CSS layer.
3. Add icons and logo assets with consistent naming.
4. Use template overrides only when config/CSS cannot solve the requirement.
## Key Zensical Customization Surfaces
!!! 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
- Define color variables once and reuse them for semantic roles (primary, surface, muted, success, warning).
- 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.
!!! 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/)
!!! tip "Icon family consistency"
Pick one primary icon family for navigation and status icons, then document naming conventions.
## Extending the Theme Safely
Use overrides as a last step, not the first.
1. Confirm the requirement cannot be solved by config and CSS.
2. Keep override templates minimal and focused.
3. Track upstream changes if you override partials.
4. Add a visual regression checklist for common pages.
## Review Checklist
- Theme changes preserve readability for long-form docs.
- Icons are consistent in weight/style and meaningful in context.
- Color changes do not break code-block syntax highlighting or search visibility.
- Overrides are documented with rationale and owner.
src/personal_mcp/docs/skills/zensical-docs/references/zensical-features.md
+78
View File
@@ -0,0 +1,78 @@
# Zensical Features and Configuration Patterns
Use this reference when deciding which Zensical features to enable and why.
## Project Bootstrap
Always start a new docs project with `uv run zensical new`.
- It creates the baseline scaffolding for configuration, docs structure, and theme integration.
- Treat this as the default starting point rather than manually assembling files.
## High-Value Feature Groups
### Navigation and Discoverability
- `navigation.indexes`: lets sections have index pages for overview content.
- `navigation.path`: adds breadcrumb-like context.
- `navigation.sections`: groups top-level sections for large doc sets.
- `navigation.instant`: enables instant internal navigation.
- `navigation.instant.prefetch`: prefetches likely next pages.
- `navigation.top`: shows a back-to-top affordance.
- `navigation.tracking`: keeps URL anchors in sync with active section.
!!! info "Source links"
- [Zensical navigation setup](https://zensical.org/docs/setup/navigation/)
### Code-Heavy Documentation
- `content.code.copy`: copy button in code blocks.
- `content.code.select`: line range selection support.
- `content.code.annotate`: inline code annotations.
- Prefer mkdocstrings for generated API reference pages when documenting Python code.
- Keep generated API pages linked from hand-authored task and concept docs.
!!! info "Source links"
- [Zensical code blocks](https://zensical.org/docs/authoring/code-blocks/)
- [mkdocstrings](https://mkdocstrings.github.io/)
### Cross-Page UX Consistency
- `content.tabs.link`: keeps same-named tabs synchronized.
- `content.tooltips`: improves tooltip behavior for links.
- `content.footnote.tooltips`: inline footnote previews.
!!! 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).
!!! info "Source links"
- [Zensical search setup](https://zensical.org/docs/setup/search/)
- [Zensical repository setup](https://zensical.org/docs/setup/repository/)
## Styling and Extensibility
Use site-level customization when docs need stronger visual affordances.
- `extra_css`: add targeted style overrides.
- `extra_javascript`: add behavior enhancements.
- Theme override directory (`custom_dir`) for template-level changes.
!!! 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
1. Start with discoverability and clarity features first.
2. For code-heavy docs, add copy/select/annotate first, then define mkdocstrings coverage for API reference.
3. Avoid enabling many features at once without measurement.
4. Track user success metrics (search success, time-to-answer, support deflection) after each change.