🍃 Tellia / 🥷🏿 Engineering

Appearance

📄 Contributing to the Documentation ​

Welcome! This guide will help you contribute to the Tellia documentation. Our docs are built with VitePress, making it easy to write and maintain high-quality documentation.

Quick Start ​

Prerequisites ​

  • Node.js 24+ installed (we recommend using NVM)
  • Basic knowledge of Markdown
  • The repository cloned locally

Running the Documentation Locally ​

  1. Install dependencies from the repo root (if not already done):

    bash
    pnpm install

  2. Start the VitePress dev server:

    bash
    pnpm docs

    Or equivalently from anywhere in the repo:

    bash
    pnpm --filter docs dev

  3. Open your browser to http://localhost:5174

The documentation will hot-reload as you make changes!

NOTE

pnpm dev from the repo root launches the frontend + backend dev servers, not the docs. Always use pnpm docs to work on documentation.

Documentation Structure ​

Our documentation is organized in the /docs folder:

docs/
├── .vitepress/          # VitePress configuration
│   └── config.mts       # Site config, navigation, and sidebar
├── getting-started/     # Onboarding guides
├── infrastructure/      # Deployment and infrastructure docs
├── observability/       # Logging, APM, and monitoring
├── coding-guides/       # Development best practices
├── skills/              # Shared Claude Code skills (copy into .claude/)
└── index.md             # Documentation homepage

Writing Documentation ​

Creating a New Page ​

  1. Create a new .md file in the appropriate folder:

    bash
    # Example: Adding a new coding guide
touch docs/coding-guides/my-new-guide.md

  2. Add frontmatter and content:

    markdown
    # My New Guide

Brief introduction to what this guide covers.

## Section 1

Content here...

  3. Add the page to the sidebar in docs/.vitepress/config.mts:

    typescript
    {
  text: '🥷🏿 Coding Guides',
  items: [
    { text: 'My New Guide', link: '/coding-guides/my-new-guide' },
    // ... other guides
  ]
}

Markdown Features ​

VitePress supports extended Markdown features — read their documentation.

Shared Skills ​

Reusable Claude Code skills (e.g. worktree, review-issue) are version-controlled under docs/skills/, one folder per skill holding the complete skill (SKILL.md + any scripts). Because .claude/ is gitignored, this folder is the shared source of truth — teammates install a skill into their own .claude/ by asking Claude to "add the <name> skill" or copying the folder (cp -R apps/docs/skills/<name> .claude/skills/<name>).

The raw skill files are excluded from the rendered site (srcExclude: ['skills/*/**'] in config.mts); only skills/README.md renders. To add a new shared skill, drop it in docs/skills/<name>/ and list it in that README.

Deploying changes ​

bash
pnpm --filter docs build && pnpm --filter docs deploy

Configuration ​

The main configuration file is docs/.vitepress/config.mts. This controls:

  • Site metadata (title, description)
  • Navigation (top nav bar)
  • Sidebar (left sidebar structure)
  • Theme customization
  • Plugins (we use Mermaid for diagrams)

Tips and Best Practices ​

  • Preview your changes before submitting a PR
  • Check for broken links - VitePress will warn you about dead links
  • Use consistent formatting - follow the style of existing docs
  • Keep it maintainable - documentation should be easy to update
  • Cross-reference related documentation pages
  • Version-specific info - note if a feature is version-specific

Getting Help ​