This file provides comprehensive information for AI agents, contributors, and team members working with the Ona documentation repository.

​
🎯 Repository Overview

This repository contains the complete documentation for Ona (formerly Gitpod), including:
  • Ona - The new cloud development environment platform
  • Gitpod Classic - Legacy documentation for the original Gitpod platform
  • Examples - AI agent use cases and getting started examples
  • Release Notes - Product updates and changelog

​
📁 Repository Structure

/docs/
├── ona/                    # Ona platform documentation
├── classic/               # Gitpod Classic documentation  
├── examples/              # Code examples and use cases
├── release-notes/         # Product changelog
├── images/                # 🆕 Centralized image directory
├── docs.json              # Mintlify configuration
└── README.md

​
🖼️ Image Management Guidelines

​
Standard Assets (< 20MB)

  • Location: /images/ directory
  • Path in MDX: /images/filename.ext
  • Supported formats: PNG, JPG, JPEG, WebP, SVG, GIF, WebM, MP4

​
Large Assets (≥ 20MB)

  • Repository: gitpod-io/ona.com
  • Directory: public/docs-large-assets/
  • Path in MDX: https://www.ona.com/docs-large-assets/filename.ext

​
Migration Status

✅ All existing images moved to /images/ directory
✅ All MDX references updated automatically
✅ No broken links or missing assets

​
🛠️ Development Workflow

​
Getting Started

# Clone the new docs repo
git clone https://github.com/gitpod-io/docs.git
cd docs

# Install Mintlify (if not already installed)
npm install -g mintlify

# Start local development server
mintlify dev

​
Making Changes

  1. Create/edit MDX files in the appropriate directory (ona/, classic/, examples/)
  2. Add images to /images/ directory (or large assets repo if >20MB)
  3. Update docs.json for navigation changes
  4. Test locally with mintlify dev
  5. Commit and push to main branch

​
File Locations

  • Ona docs: /workspaces/docs/ona/
  • Classic docs: /workspaces/docs/classic/
  • Examples: /workspaces/docs/examples/
  • Images: /workspaces/docs/images/
  • Configuration: /workspaces/docs/docs.json

​
📝 Documentation Standards

​
Image References

<!-- ✅ Correct - use /images/ path -->
![Alt text](/images/screenshot.png)
<img src="/images/diagram.svg" alt="Diagram" />

<!-- ✅ Large assets - use full URL -->
![Large video](/images/large-demo.webm) <!-- if < 20MB -->
![Large video](https://www.ona.com/docs-large-assets/large-demo.webm) <!-- if > 20MB -->

​
File Naming

  • Use kebab-case for files: getting-started.mdx
  • Use descriptive names for images: vscode-integration-screenshot.png
  • Avoid spaces and special characters

​
🔄 Handling Redirects

Redirects are managed in the Mintlify configuration file:
  • File: /workspaces/docs/docs.json
  • Purpose: Handle URL redirects and navigation
  • Format: JSON configuration with redirect rules
  • Updates: Modify this file when changing page URLs or adding redirects

​
🚀 Deployment

  • Automatic deployment on push to main branch
  • Live site: ona.com/docs
  • Preview: Available via Mintlify’s preview system

​
❓ Support Information

  • Repository: gitpod-io/docs
  • Issues: Use GitHub issues in the docs repo
  • Mintlify docs: mintlify.com/docs
  • Team contact: #team-website Slack channel