Documentation Guide

This guide explains how documentation works in the TimeTiles project.

Documentation Structure

All documentation lives under /apps/docs/content/ as hand-written MDX files:

Overview (/overview/) - Core concepts, comparison with other tools
Quick Start (/quick-start) - Local installation
Guide (/guide/) - Features, use cases, tutorials
Self-Hosting (/self-hosting/) - Deployment, configuration, maintenance
Development (/development/) - Architecture, development guides, API docs
Reference (/reference/) - Glossary, changelog, roadmap
FAQ (/faq) - Frequently asked questions

API documentation is hand-written in apps/docs/content/development/api/. For implementation details beyond what the docs cover, read the source code in apps/web/app/api/.

Working with Documentation

Creating New Pages

Create an .mdx file in the appropriate directory:


apps/docs/content/development/contributing/my-new-guide.mdx

Write your content using MDX (Markdown + JSX):


# My Guide Title
 
import { Callout } from "nextra/components";
 
<Callout type="info">Important information here</Callout>
 
## Section with code
 
\`\`\`typescript
const example = "code here"
\`\`\`

Update the navigation by editing _meta.js in the same directory:


export default { "existing-page": "Existing Page", "my-new-guide": "My New Guide" };

Link to other pages with absolute paths (/self-hosting/deployment). Every page URL ends in a slash, so a relative ./sibling link from a non-index page resolves below the current page and 404s.

Best Practices for Manual Docs

Use clear, descriptive titles
Include practical examples
Add screenshots where helpful
Link to related documentation
Keep content up-to-date with code changes

Development Workflow

Edit .mdx files directly in apps/docs/content/
Preview with pnpm dev from the apps/docs directory
Commit the documentation changes

Troubleshooting

Common Issues

Edit the appropriate _meta.js file in the same directory

Broken links in documentation

Use relative paths for internal links
Check for typos in paths

Best Practices

User-focused: Write for your audience
Practical examples: Show real-world usage
Visual aids: Include diagrams/screenshots where helpful
Cross-reference: Link to related guides
Keep concise: Avoid unnecessary verbosity

Documentation Review Checklist

Guides updated if behavior changed
Navigation (_meta.js) updated if needed
Links verified and working