Skip to content

Authoring Documentation

Write effective documentation using Markdown and Zensical features. Follow Documentation Principles for consistency.

Current Docs Layout

The repository maintains docs under docs/ and docs/dev/.

  • docs/index.md - Documentation home
  • docs/dev/contributing/authoring-documentation.md - Authoring guidance
  • docs/dev/setup/index.md - Developer setup
  • docs/dev/contributing/naming-conventions.md - Naming conventions for code identifiers
  • docs/dev/contributing/documentation-principles/ - Standards and rules

Markdown Essentials

File structure:

  • One H1 per file (page title)
  • H2 for sections, H3 for subsections (don't go deeper)
  • Fenced code blocks with language identifiers

Links & References:

Type Format Use When
Internal docs [Link Text](path/to/file.md) Linking to other docs
Source code Full GitHub link to the target file Referencing code in passing
External [Link Text](https://url.com) Third-party resources

For complete Markdown syntax, see Zensical Reference.

Admonitions (Callouts)

Use ???+ for collapsible blocks (expanded by default):

???+ note "Optional Title"
    Block content here.

Core types: note, tip, info, warning, danger, question, success

When to use:

  • Use for prerequisites, warnings, best practices, and status labels
  • Avoid for regular content, minor points, and replacing structure

Example:

???+ warning "Destructive Action"
    This will delete data permanently.

For advanced admonitions, see Zensical Guide.

Tables

Use for structured data. Keep simple (3-5 columns ideal):

| Column A | Column B | Column C |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |

Style Guidelines

Guideline Good Avoid
Voice Direct, active: "Run this command" Passive: "Command should be run"
Clarity Define acronyms once Use undefined abbreviations
Code examples Show context: cd docs then run command Isolated commands without setup
Consistency Use same terms throughout Mix terminology
Characters Prefer keyboard-friendly punctuation for consistency; use em dashes (—), emojis, and other non-QWERTY symbols sparingly Overusing decorative symbols or mixing punctuation styles without purpose

Before Committing

mise run docs

Verify:

  • Broken links
  • Formatting correct
  • Code blocks render
  • Admonitions display
  • Tables aligned
  • No encoding artifacts (for example, replacement characters like �)
  • Follows documentation principles
  • Matches current code (no fiction)

See Also