Welcome to the Cloud 66 documentation! This guide will help you write, format, and structure documentation for our products using MDX.

1. Create MDX files in appropriate product directories: rails/, deploy/, sites/, node/, or common/
2. Add proper frontmatter with title, description, lead, and products
3. Use available components to enhance your content
4. Test locally with yarn dev
5. Validate with yarn validate:mdx before submitting

/src/docs/
├── rails/              # Rails-specific documentation
├── deploy/             # Deploy-specific documentation 
│   ├── 1/             # Deploy v1 legacy content
│   └── 2/             # Deploy v2 content (v3 uses base folder)
├── sites/              # Sites-specific documentation
├── node/               # Node-specific documentation (legacy product)
├── common/             # Shared documentation across all products
└── partials/           # Reusable content snippets (not directly accessible)

• Use lowercase kebab-case: building-your-service.mdx
• Be descriptive and specific: connecting-between-containerized-services.mdx
• Avoid abbreviations unless well-known: api-keys.mdx not api-keys.mdx

Use _order.yaml files to control the order of documents within categories:

# /src/docs/getting-started/_order.yaml
- quick-start
- deploy-your-first-app
- migrate-from-heroku
- migrate-from-forge

Rules:

• Place _order.yaml in each category directory
• List file names (without .mdx extension) in desired order
• Files not listed in _order.yaml will appear after ordered files
• Categories themselves are ordered by the sequence field in /src/config/products.ts

Every MDX file must include frontmatter metadata at the top:

---
title: "Your Page Title"
description: "Brief description for SEO (150-160 characters ideal)"
lead: "Extended description shown at top of page (optional)"
products: ['rails', 'deploy']
---

Specific products:

products: ['rails', 'deploy']  # Only accessible on Rails and Deploy

All products:

products: 'all'  # Accessible from all product routes

Common (no products field):

# No products field = accessible on all products + /common/ routes

Hide from specific versions:

excludeVersions: ['2']  # Hide from Deploy v2, show on v1 and v3

Show only in specific versions:

includeVersions: ['1']  # Only show in Deploy v1

Important: excludeVersions and includeVersions are mutually exclusive.

For Deploy product, you can create version-specific content:

/src/docs/category/
  └── page.mdx           # Default/latest version (v3)
  └── 1/
      └── page.mdx       # Version 1 specific content
  └── 2/
      └── page.mdx       # Version 2 specific content (optional)

The system will automatically serve the appropriate version based on the URL.

Show/hide content based on the active product:

<PerProduct includes={["rails"]}>
This content only shows for Rails users.
</PerProduct>

<PerProduct includes={["deploy"]}>
This content shows for Deploy users.
</PerProduct>

<PerProduct excludes={["sites"]}>
This content shows for all products except Sites.
</PerProduct>

<PerProduct includeVersions={["1"]}>
This content only shows for Deploy v1 users.
</PerProduct>

<PerProduct excludeVersions={["2"]}>
This content shows for all Deploy versions except v2.
</PerProduct>

Create tabbed content for different scenarios:

<Tabs defaultValue="rails">
  <TabsList>
    <TabsTrigger value="rails">Rails</TabsTrigger>
    <TabsTrigger value="express">Express</TabsTrigger>
    <TabsTrigger value="django">Django</TabsTrigger>
  </TabsList>
  
  <TabsContent value="rails">
    Rails-specific content here.
  </TabsContent>
  
  <TabsContent value="express">
    Express-specific content here.
  </TabsContent>
  
  <TabsContent value="django">
    Django-specific content here.
  </TabsContent>
</Tabs>

Create content with a dropdown filter:

<FilteredContentBox labels={["AWS", "GCP", "Azure"]} defaultFilter="AWS">
  <FilteredContent filter="AWS">
    AWS-specific instructions here.
  </FilteredContent>
  
  <FilteredContent filter="GCP">
    Google Cloud specific instructions here.
  </FilteredContent>
  
  <FilteredContent filter="Azure">
    Azure-specific instructions here.
  </FilteredContent>
</FilteredContentBox>

Highlight important information:

<Callout type="info" title="Information">
General information or tips.
</Callout>

<Callout type="warning" title="Important">
Something users should be careful about.
</Callout>

<Callout type="error" title="Warning">
Critical information or potential issues.
</Callout>

Basic alert component:

<Alert>
  <AlertTitle>Notice</AlertTitle>
  <AlertDescription>
    Basic alert with optional title and description.
  </AlertDescription>
</Alert>

Expandable content sections:

<Collapsible title="Advanced Configuration">
  This content is hidden by default and can be expanded by clicking the title.
  
  You can include any markdown or components here.
</Collapsible>

Tooltips for additional context:

<Hint caption="hover me">
  Additional information shown on hover.
</Hint>

Images with captions:

<Figure 
  src="/path/to/image.png" 
  alt="Descriptive alt text"
  caption="Optional caption explaining the image" 
/>

Small status indicators:

<Badge variant="default">New</Badge>
<Badge variant="secondary">Beta</Badge>
<Badge variant="destructive">Deprecated</Badge>
<Badge variant="outline">Optional</Badge>

Rounded status indicators:

<Pill>Status</Pill>

Interactive buttons (use sparingly):

<Button variant="default">Primary Action</Button>
<Button variant="outline">Secondary Action</Button>
<Button variant="ghost">Subtle Action</Button>

Display version-specific information:

<ComponentVersion version="2.1.0" />

Display Cloud 66 IP addresses:

<IpList />

Special typography elements:

<Glyph>Special symbol or icon</Glyph>

Enhanced code blocks with syntax highlighting:

<CodeBlock language="bash" title="Installation">
npm install @cloud66/cli
</CodeBlock>

Wraps imported MDX partials to ensure proper SmartLink functionality:

import MyPartial from '../partials/_my_partial.mdx';

<PartialWrapper partial={MyPartial} />

Required for all partials - without this wrapper, SmartLink placeholders (:product, :version?) won't be converted properly.

Links automatically adapt to the current product and version context:

[Getting Started](/:product/:version?/getting-started/quick-start)
[API Reference](/:product/api/overview)
[Common Guide](/common/shared-guide)

Placeholders:

• :product - Current product (rails, deploy, sites, node)
• :version - Current version (includes version in path if set)
• :version? - Optional version (includes version only if viewing a specific version)

All GitHub Flavored Markdown is supported:

• Bold and italic text
• inline code
• Links
• Lists (ordered and unordered)
• Headers (H1-H6)
• Tables
• Blockquotes
• Horizontal rules

Fenced code blocks with syntax highlighting:

# This is a bash command
kubectl get pods

# YAML configuration
apiVersion: v1
kind: Service
metadata:
  name: my-service

// JavaScript code
const config = {
  apiKey: process.env.API_KEY,
  timeout: 5000
};

Standard Markdown tables with enhanced styling:

Reuse content across multiple pages by importing partials. IMPORTANT: All partials must be wrapped with PartialWrapper for proper SmartLink functionality.

import GitPartial from '../partials/_git.mdx';
import SshKeysPartial from '../partials/_ssh_keys.mdx';

<PartialWrapper partial={GitPartial} />

## Next Steps

<PartialWrapper partial={SshKeysPartial} />

MDX partials imported as components don't inherit the component overrides from the parent page. Without PartialWrapper, SmartLink placeholders like :product and :version? won't be converted properly.

❌ Incorrect (will break SmartLink conversion):

<GitPartial />  <!-- Links with :product/:version won't work -->

✅ Correct (SmartLinks work properly):

<PartialWrapper partial={GitPartial} />

Partials that import other partials work automatically when using PartialWrapper:

<!-- /src/docs/partials/_cloud_providers.mdx -->
import AwsPartial from './_aws.mdx';

<FilteredContentBox labels={["AWS", "GCP"]}>
  <FilteredContent filter="AWS">
    <PartialWrapper partial={AwsPartial} />
  </FilteredContent>
</FilteredContentBox>

Partial naming: Always prefix with underscore (_git.mdx, _ssh_keys.mdx)

1. Start with context: Explain what the reader will learn
2. Use clear headings: Structure content hierarchically
3. Include prerequisites: List what readers need before starting
4. Provide examples: Show real code and configurations
5. End with next steps: Guide readers to related content

• Be concise: Get to the point quickly
• Use active voice: "Click the button" not "The button should be clicked"
• Write for your audience: Assume technical competency but explain Cloud 66-specific concepts
• Be consistent: Use the same terminology throughout

• Test all code: Ensure examples work as documented
• Use realistic examples: Avoid foo, bar, example.com
• Include error handling: Show what can go wrong and how to fix it
• Update regularly: Remove outdated information

• Alt text: Always include descriptive alt text for images
• Link text: Use descriptive link text, not "click here"
• Headings: Use proper heading hierarchy (don't skip levels)
• Lists: Use proper list markup for sequential steps

---
title: "Specific, descriptive title (50-60 chars)"
description: "Clear description with target keywords (150-160 chars)"
lead: "Engaging lead paragraph that expands on the description"
---

• Use headers: Structure content with H2, H3, etc.
• Internal linking: Link to related Cloud 66 documentation
• Keywords naturally: Use relevant terms without keyword stuffing
• Meta descriptions: Write compelling descriptions for search results

1. Test locally: Run yarn dev and verify your content renders correctly
2. Validate MDX: Run yarn validate:mdx to check for syntax errors
3. Check links: Run yarn validate:links to verify internal links
4. Test components: Ensure all components render and function properly
5. Review product targeting: Verify content appears on correct products

• Missing frontmatter: Every file needs title and description
• Broken imports: Check partial paths are correct
• Component props: Ensure all required props are provided
• Link validation: Use correct paths for internal links
• Version conflicts: Don't use both includeVersions and excludeVersions

• Technical issues: Check the main project README for development commands
• Component questions: Refer to component source code in /src/components/
• Style guide: Follow existing documentation patterns
• Questions: Ask the development team for clarification

Happy writing! 🚀