Documentation System Guide

CloudAlt Documentation System

CloudAlt uses a unified documentation architecture with three separate Astro + Starlight sites that work together seamlessly.

🏗️ Architecture Overview

Three Independent Sites, One Domain

Our documentation is organized into three specialized Astro sites, each deployed to Cloudflare Pages with its own subdomain:

Site	URL	Source Location	Purpose
Landing Page	docs.cloudalt.app	cloudalt-frontend/apps/docs-hub/	Entry point with navigation to all docs
Frontend Docs	frontend.docs.cloudalt.app	cloudalt-frontend/apps/docs/	React/React Native guides, component library
Backend Docs	backend.docs.cloudalt.app	cloudalt-backend/docs-site/	Django API reference, database schemas
Storybook	storybook.cloudalt.app	cloudalt-frontend/storybook-static/	Component library with live examples

Why This Architecture?

✅ Team Ownership - Each team maintains their own documentation independently
✅ Fast Deployments - Deploy docs without rebuilding unrelated sites
✅ Unified Search - Pagefind indexes all sites for cross-documentation search
✅ Single Sign-On - GitHub OAuth via Cloudflare Access, session shared across all *.docs.cloudalt.app
✅ Simple Scaling - Easy to add new documentation sites (mobile, architecture, etc.)

Architecture Decision: See ARCHITECTURE_DECISION_DOCS_SECURITY.md for the full technical breakdown.

---

🚀 Quick Start

Prerequisites

• Node.js: 20.19.5 or higher
• npm: Comes with Node.js
• Git: For version control

Backend Documentation (This Site)

# Navigate to backend docs
cd cloudalt-backend/docs-site

# Install dependencies
npm install --legacy-peer-deps

# Start development server
npm run dev
# Opens at http://localhost:4321

# Build for production
npm run build

# Preview production build
npm run preview

Frontend Documentation

# Navigate to frontend docs
cd cloudalt-frontend/apps/docs

# Install dependencies (if not already done)
yarn install

# Start development server
yarn dev
# Opens at http://localhost:4321

# Build for production
yarn build

---

📝 Writing Documentation

File Structure

All documentation uses Markdown (.md) or MDX (.mdx) files in the src/content/docs/ directory:

docs-site/
├── src/
│   └── content/
│       └── docs/
│           ├── index.mdx              # Homepage
│           ├── getting-started/       # Getting started guides
│           ├── architecture/          # Architecture docs
│           │   ├── overview.md
│           │   └── diagrams.md        # ← Architecture diagrams with zoom!
│           ├── api/                   # API reference
│           ├── deployment/            # Deployment guides
│           └── contributing/          # This file!

Creating a New Page

1. Create a Markdown file in the appropriate directory:

touch src/content/docs/api/new-endpoint.md

2. Add frontmatter at the top:

---
title: New Endpoint Guide
description: How to use the new API endpoint
---

# New Endpoint Guide

Your content here...

3. The page is automatically added to the sidebar (using autogenerate in astro.config.mjs)

Markdown Features

Headings

# H1 - Page Title (only one per page)
## H2 - Major Section
### H3 - Subsection
#### H4 - Sub-subsection

Code Blocks

```python
# Python code with syntax highlighting
def hello():
    return "Hello, CloudAlt!"
```

```bash
# Shell commands
npm install medium-zoom
```

Callouts/Asides

:::note
This is informational content.
:::

:::tip
Pro tip for users!
:::

:::caution
Be careful with this operation.
:::

:::danger
This could break things!
:::

Links

[Internal link](/api/stays/)
[External link](https://github.com/xavierdurant/cloudalt-backend)

Images

![Alt text](/diagrams/architecture.png)

Images automatically have zoom functionality! Click any image to view full-size.

---

🖼️ Image Zoom Feature

All images in the documentation have click-to-zoom functionality powered by medium-zoom.

How It Works

1. Hover over any image - cursor changes to zoom-in cursor
2. Click the image - it expands to full screen with dark overlay
3. Click again or press ESC - returns to normal view

Best Practices for Images

• Use high-resolution images - zoom makes them viewable in detail
• Architecture diagrams are perfect for this feature
• Small icons automatically excluded from zoom (< 32px width)
• PNG format recommended for diagrams (better quality than JPG)

Adding Images

1. Place images in the public/ directory:

cloudalt-backend/docs-site/public/diagrams/my-diagram.png

2. Reference in Markdown:

![My Diagram](/diagrams/my-diagram.png)

3. Image is automatically zoomable - no extra configuration needed!

Technical Implementation

The zoom feature uses:

• medium-zoom library (lightweight, ~2KB)
• Custom Head component (src/components/Head.astro) that initializes zoom
• Custom CSS for hover effects and zoom cursor
• Dark overlay background (95% black) for optimal viewing

---

🎨 Customization

Brand Colors

CloudAlt brand colors are defined in src/styles/custom.css:

:root {
  --sl-color-accent: #0ABAFF; /* CloudAlt Blue */
  --sl-color-gray-1: #94a3b8;  /* Medium Grey for headings */
}

Sidebar Configuration

Edit astro.config.mjs to customize the sidebar:

sidebar: [
  {
    label: 'Start Here',
    link: '/',
  },
  {
    label: 'Getting Started',
    autogenerate: { directory: 'getting-started' },
  },
  // Add more sections...
],

---

🚢 Deployment

Automatic Deployment

Documentation deploys automatically via GitHub Actions when you push to main:

Workflow: .github/workflows/deploy-backend-docs.yml

on:
  push:
    branches: [main]
    paths:
      - 'docs-site/**'

Manual Deployment

If you need to deploy manually:

# Build the site
npm run build

# The built site is in docs-site/dist/
# Upload to Cloudflare Pages via dashboard or wrangler

Deployment Checklist

Before pushing documentation changes:

• Test locally with npm run dev
• Build successfully with npm run build
• Preview build with npm run preview
• Check all links work
• Verify images load correctly
• Test image zoom functionality
• Review for typos and grammar

---

📚 Starlight Features

Our documentation uses Astro Starlight, which provides:

• ✅ Automatic sidebar generation from file structure
• ✅ Dark/light mode toggle (defaults to dark)
• ✅ Built-in search with Pagefind
• ✅ Mobile-responsive navigation
• ✅ Automatic table of contents for each page
• ✅ Syntax highlighting for code blocks
• ✅ SEO optimization with automatic meta tags
• ✅ Fast performance - static site generation

Starlight Documentation

• Starlight Docs
• Astro Docs
• Markdown Guide

---

� Search

Search is powered by Pagefind, which automatically indexes all content during the build process.

• Search indexes all three documentation sites
• Results show context snippets
• Keyboard shortcut: Cmd/Ctrl + K

---

🤝 Contributing

Workflow

1. Create a branch for your changes:

   git checkout -b docs/add-new-api-guide

2. Make your changes in docs-site/src/content/docs/

3. Test locally:

   npm run dev

4. Build to verify:

   npm run build

5. Commit and push:

   git add docs-site/
   git commit -m "docs: Add new API guide for stays endpoint"
   git push origin docs/add-new-api-guide

6. Open a Pull Request on GitHub

Style Guide

• Use clear, concise language
• Write in present tense (“Click the button” not “You will click”)
• Use active voice (“Configure the setting” not “The setting can be configured”)
• Include code examples wherever relevant
• Add screenshots for UI-heavy topics
• Use proper Markdown formatting

---

🛠️ Troubleshooting

Build Errors

Error: Cannot find module '@astrojs/starlight'

npm install --legacy-peer-deps

Error: peer dependency conflicts

# Use legacy peer deps flag
npm install --legacy-peer-deps

Development Server Issues

Port already in use:

# Kill the process on port 4321
lsof -ti:4321 | xargs kill -9

Images not loading:

• Check images are in public/ directory
• Use absolute paths starting with /
• Example: /diagrams/image.png

Image Zoom Not Working

1. Hard refresh the browser: Cmd+Shift+R (Mac) or Ctrl+Shift+F5 (Windows)
2. Check browser console for JavaScript errors
3. Verify medium-zoom is installed: npm list medium-zoom

---

📞 Contact

Questions or Issues?

Xavier Landeros Durant
Email: xavier@cloudalt.app

For documentation bugs, feature requests, or urgent issues, please reach out directly.

Helpful Resources

• Starlight Documentation
• Astro Documentation
• MDX Documentation
• Medium Zoom

---

Last Updated: November 6, 2025
Maintained By: Platform Team
Status: ✅ Active