@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/guides/adding-documentation-sites.mdx

@@ -0,0 +1,1367 @@
+---
+title: Adding Documentation Sites
+description: Complete guide to creating and deploying documentation sites using the documentation-template within the Blue Alba Platform
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+import MermaidDiagram from '~/components/MermaidDiagram.astro';
+
+The Blue Alba Platform includes a powerful documentation feature that enables you to seamlessly integrate documentation sites with your applications. This feature leverages a reusable Docker image called `pae-documentation-template`, making it simple to deploy modern, performant documentation sites alongside your application code.
+
+## Overview
+
+The documentation system is built on a simple design philosophy: documentation files live with production code, ensuring documentation evolves alongside feature development and reducing the risk of outdated information.
+
+### Key Benefits
+
+<CardGrid stagger>
+  <Card title="Zero Configuration" icon="seti:config">
+    The template abstracts all complexity. Just add your markdown files and configuration - no build setup required.
+  </Card>
+
+  <Card title="Modern Framework" icon="rocket">
+    Built on Starlight and Astro, providing a fast, accessible, and beautiful documentation experience.
+  </Card>
+
+  <Card title="Platform Integration" icon="puzzle">
+    Automatic discovery and navigation links in the platform shell. No manual integration needed.
+  </Card>
+
+  <Card title="Access Control" icon="lock">
+    Built-in authorization support. Control who can access which documentation using platform operations.
+  </Card>
+</CardGrid>
+
+---
+
+## Architecture
+
+The documentation system uses a layered architecture built around the reusable `pae-documentation-template` Docker image.
+
+<MermaidDiagram
+  title="Documentation Architecture"
+  code={`graph LR
+    A[pae-documentation-template<br/>Docker Image]:::template --> B[app-documentation<br/>Application Layer]:::app
+    B --> C[app-documentation-site<br/>Generated Site]:::site
+    D[documentation<br/>files]:::content --> B
+    E[configuration<br/>config.json]:::content --> B
+
+    classDef template fill:#90EE90,color:#333
+    classDef app fill:#87CEEB,color:#333
+    classDef site fill:#FFB6C1,color:#333
+    classDef content fill:#FFD700,color:#333`}
+/>
+
+### Architecture Components
+
+- **pae-documentation-template**: Base Docker image containing Starlight/Astro framework, Nginx server, and build tooling
+- **app-documentation**: Your application layer combining the template with custom content and configuration
+- **app-documentation-site**: The resulting generated documentation website served via Nginx
+- **documentation files**: Your markdown (MDX) files containing the actual documentation content
+- **configuration**: `config.json` file defining site structure, theme, navigation, and behavior
+
+---
+
+## Quick Start
+
+Deploy a documentation site in three straightforward steps:
+
+### 1. Create the Documentation Application
+
+Create a new application directory structure with your content:
+
+```bash
+my-app-documentation/
+├── Dockerfile
+├── docs/                  # Your MDX documentation files
+│   ├── index.mdx
+│   ├── guides/
+│   │   ├── getting-started.mdx
+│   │   └── advanced-usage.mdx
+│   └── reference/
+│       └── api.mdx
+├── assets/                # Images, diagrams, etc.
+│   └── logo.svg
+└── config.json           # Site configuration
+```
+
+### 2. Register the Documentation Module
+
+Configure a new module in the Applications Catalog with type `documentation`:
+
+```json
+{
+  "name": "my-app-documentation",
+  "type": "documentation",
+  "displayName": "My App Documentation",
+  "description": "Complete documentation for My App",
+  "route": "/docs/my-app",
+  "application": "my-app"
+}
+```
+
+### 3. Configure Service Deployment
+
+Add the documentation service to your `docker-compose.yml`:
+
+```yaml
+services:
+  my-app-documentation:
+    image: my-app-documentation:latest
+    container_name: my-app-documentation
+    ports:
+      - "8080:80"
+    environment:
+      - NODE_ENV=production
+    networks:
+      - platform-network
+```
+
+That's it! Once deployed, the documentation site becomes immediately accessible through the platform.
+
+---
+
+## Creating Documentation Content
+
+### Step-by-Step Setup
+
+<Tabs>
+  <TabItem label="1. Create Dockerfile">
+
+Create a `Dockerfile` that extends the base template:
+
+```dockerfile
+# Use the base documentation template image
+FROM bluealba-ba-pae-releases-docker.jfrog.io/bluealba-pae-documentation-template:latest
+
+# Copy your documentation content
+COPY ./docs/ /app/src/content/docs/
+COPY ./assets/ /app/src/assets
+COPY ./config.json /app/src/config.json
+
+# Optional: Customize via environment variables
+ENV SITE_TITLE="My App Documentation"
+ENV SITE_DESCRIPTION="Complete documentation for My App including guides and API reference"
+
+# Optional: Add custom logo
+COPY ./logo.svg /app/src/assets/logo.svg
+ENV SITE_LOGO="./src/assets/logo.svg"
+
+# Optional: Add GitHub link
+ENV GITHUB_URL="https://github.com/myorg/my-app"
+```
+
+**Key Points:**
+- The base image contains all necessary build tools and frameworks
+- You only need to add your content files and configuration
+- Environment variables provide simple customization
+- The entrypoint is inherited from the base image (validates, builds, serves)
+
+</TabItem>
+
+  <TabItem label="2. Create config.json">
+
+Create a `config.json` file to configure your documentation site:
+
+```json
+{
+  "title": "My App Documentation",
+  "description": "Complete documentation for My App",
+  "logo": {
+    "src": "./src/assets/logo.svg",
+    "alt": "My App Logo"
+  },
+  "social": {
+    "github": "https://github.com/myorg/my-app"
+  },
+  "sidebar": [
+    {
+      "label": "Getting Started",
+      "items": [
+        { "label": "Introduction", "link": "/" },
+        { "label": "Installation", "link": "/guides/installation" },
+        { "label": "Quick Start", "link": "/guides/quick-start" }
+      ]
+    },
+    {
+      "label": "Guides",
+      "autogenerate": { "directory": "guides" }
+    },
+    {
+      "label": "API Reference",
+      "autogenerate": { "directory": "reference" }
+    }
+  ],
+  "customCss": [
+    "./src/styles/custom.css"
+  ],
+  "components": {
+    "Head": "./src/components/Head.astro"
+  }
+}
+```
+
+**Configuration Options:**
+
+| Option | Description | Required |
+|--------|-------------|----------|
+| `title` | Site title (appears in header and browser tab) | Yes |
+| `description` | Site description for SEO meta tags | Yes |
+| `logo` | Site logo configuration (src and alt text) | No |
+| `social` | Social media links (GitHub, Twitter, etc.) | No |
+| `sidebar` | Navigation sidebar structure | Yes |
+| `customCss` | Custom CSS files to apply | No |
+| `components` | Custom Astro components to override | No |
+
+</TabItem>
+
+  <TabItem label="3. Write Content">
+
+Create your documentation files using MDX (Markdown with JSX):
+
+```mdx
+---
+title: Getting Started
+description: Learn how to get started with My App in 5 minutes
+---
+
+import { Card, CardGrid, Aside } from '@astrojs/starlight/components';
+
+Welcome to My App! This guide will help you get started quickly.
+
+## Installation
+
+Install My App using npm:
+
+\`\`\`bash
+npm install my-app
+\`\`\`
+
+<Aside type="tip">
+For production deployments, consider using Docker for better isolation and consistency.
+</Aside>
+
+## Quick Example
+
+Here's a simple example to get you started:
+
+\`\`\`javascript
+import { MyApp } from 'my-app';
+
+const app = new MyApp({
+  apiKey: 'your-api-key',
+  environment: 'production'
+});
+
+await app.start();
+console.log('App started successfully!');
+\`\`\`
+
+## Next Steps
+
+<CardGrid>
+  <Card title="Configuration" icon="setting">
+    Learn about all available configuration options
+  </Card>
+  <Card title="API Reference" icon="document">
+    Explore the complete API documentation
+  </Card>
+</CardGrid>
+```
+
+**MDX Features Available:**
+- Full Markdown syntax (headings, lists, code blocks, tables)
+- Syntax highlighting for code blocks (100+ languages)
+- Starlight components (Card, Aside, Tabs, FileTree, etc.)
+- Custom React components
+- Mermaid diagrams for visualizations
+- Frontmatter for page metadata
+
+</TabItem>
+
+  <TabItem label="4. Build & Deploy">
+
+Build and deploy your documentation:
+
+```bash
+# Build the Docker image
+docker build -t my-app-documentation:latest .
+
+# Run locally for testing
+docker run -p 8080:80 my-app-documentation:latest
+
+# Access the documentation
+open http://localhost:8080
+
+# Check health endpoint
+curl http://localhost:8080/health
+
+# Push to registry
+docker tag my-app-documentation:latest registry.example.com/my-app-documentation:latest
+docker push registry.example.com/my-app-documentation:latest
+
+# Deploy via docker-compose or orchestrator
+docker-compose up -d my-app-documentation
+```
+
+**Build Process:**
+1. Docker copies your content into the image
+2. Entrypoint validates content exists
+3. Astro builds the static site (optimized HTML, CSS, JS)
+4. Nginx serves the built site
+5. Health check endpoint available at `/health`
+
+</TabItem>
+</Tabs>
+
+---
+
+## Platform Integration
+
+The Blue Alba Platform provides seamless integration for documentation modules, making them instantly discoverable and accessible.
+
+### Automatic Navigation Links
+
+<MermaidDiagram
+  title="Documentation Discovery Flow"
+  code={`sequenceDiagram
+    participant User
+    participant Shell as Platform Shell
+    participant Catalog as Application Catalog
+    participant Docs as Documentation Module
+
+    User->>Shell: Load Application
+    Shell->>Catalog: Query modules for application
+    Catalog-->>Shell: Return all modules
+    Shell->>Shell: Filter modules by type="documentation"
+    Shell->>Shell: Generate navigation links
+    Shell-->>User: Display app with doc links
+    User->>Docs: Click documentation link
+    Docs-->>User: Open docs in new tab`}
+/>
+
+The platform shell automatically:
+1. Detects documentation modules associated with each application
+2. Generates navigation links at the bottom of the application's navigation bar
+3. Opens documentation in a new tab for convenient reference
+4. Supports multiple documentation modules per application
+
+**Multiple Documentation Modules:**
+
+You can configure multiple documentation modules per application for logical separation:
+
+```json
+// Technical documentation (developers only)
+{
+  "name": "my-app-technical-docs",
+  "type": "documentation",
+  "displayName": "Technical Documentation",
+  "route": "/docs/my-app/technical",
+  "application": "my-app",
+  "operations": ["my-app::documentation::technical"]
+}
+
+// User documentation (all users)
+{
+  "name": "my-app-user-docs",
+  "type": "documentation",
+  "displayName": "User Guide",
+  "route": "/docs/my-app/user-guide",
+  "application": "my-app",
+  "operations": ["my-app::documentation::user-guide"]
+}
+
+// Admin documentation (administrators only)
+{
+  "name": "my-app-admin-docs",
+  "type": "documentation",
+  "displayName": "Admin Documentation",
+  "route": "/docs/my-app/admin",
+  "application": "my-app",
+  "operations": ["my-app::documentation::admin"]
+}
+```
+
+### Authorization and Access Control
+
+Documentation modules support the platform's built-in authorization system through operations.
+
+<Aside type="tip" title="Operations-Based Access">
+Assign operations to documentation modules to control visibility. Only users with the required operation will see the documentation link in the navigation.
+</Aside>
+
+**Access Control Flow:**
+
+<MermaidDiagram
+  title="Documentation Authorization"
+  code={`graph TD
+    A[User loads application] --> B{Check user operations}
+    B --> C{Has doc operation?}
+    C -->|Yes| D[Show documentation link]
+    C -->|No| E[Hide documentation link]
+    D --> F[User clicks link]
+    F --> G{Gateway authorization check}
+    G -->|Authorized| H[Serve documentation]
+    G -->|Not authorized| I[Return 403 Forbidden]
+
+    style H fill:#90EE90,color:#333
+    style I fill:#FFB6C1,color:#333`}
+/>
+
+**Example Use Cases:**
+
+<CardGrid>
+  <Card title="Public Documentation" icon="open-book">
+    No operations required - visible to all application users. Perfect for general user guides.
+  </Card>
+
+  <Card title="Technical Documentation" icon="seti:config">
+    Assign `app::documentation::technical` - visible only to developers and technical staff.
+  </Card>
+
+  <Card title="Admin Documentation" icon="lock">
+    Assign `app::documentation::admin` - restricted to system administrators only.
+  </Card>
+
+  <Card title="Partner Documentation" icon="document">
+    Assign `app::documentation::partner` - accessible to partner organizations only.
+  </Card>
+</CardGrid>
+
+---
+
+## Catalog Registration
+
+Register your documentation module in the Application Catalog to integrate with the platform.
+
+### Via Admin UI
+
+1. Navigate to **Admin UI** → **Applications** → **Catalog**
+2. Click **Add Module**
+3. Fill in the form:
+   - **Name**: `my-app-documentation` (unique identifier)
+   - **Type**: Select `documentation`
+   - **Display Name**: `My App Documentation` (shown in navigation)
+   - **Description**: Brief description of the documentation
+   - **Route**: `/docs/my-app` (URL path to access documentation)
+   - **Application**: Select your application from dropdown
+   - **Operations**: Add operations for access control (optional)
+4. Click **Save**
+
+### Via API
+
+```bash
+POST /api/catalog/modules
+Content-Type: application/json
+Authorization: Bearer <admin-jwt>
+
+{
+  "name": "my-app-documentation",
+  "type": "documentation",
+  "displayName": "My App Documentation",
+  "description": "Complete documentation for My App including guides and API reference",
+  "route": "/docs/my-app",
+  "application": "my-app-id",
+  "operations": ["my-app::documentation::access"],
+  "metadata": {
+    "version": "1.0.0",
+    "tags": ["documentation", "guides", "api"]
+  },
+  "active": true
+}
+```
+
+### Via Bootstrap Configuration
+
+For automated deployments, include in your bootstrap configuration:
+
+```json
+{
+  "modules": [
+    {
+      "name": "my-app-documentation",
+      "type": "documentation",
+      "displayName": "My App Documentation",
+      "description": "Complete documentation for My App",
+      "route": "/docs/my-app",
+      "application": "my-app",
+      "operations": ["my-app::documentation::access"],
+      "active": true
+    }
+  ]
+}
+```
+
+---
+
+## Configuration Reference
+
+### Environment Variables
+
+The base template supports configuration via environment variables:
+
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `SITE_TITLE` | Site title (browser tab and header) | - | `"My App Documentation"` |
+| `SITE_DESCRIPTION` | Site description for SEO | - | `"Complete documentation..."` |
+| `SITE_URL` | Full site URL for sitemap | - | `"https://docs.example.com"` |
+| `SITE_LOGO` | Path to custom logo | - | `"./src/assets/logo.svg"` |
+| `GITHUB_URL` | GitHub repository URL | - | `"https://github.com/org/repo"` |
+| `NODE_ENV` | Environment mode | `production` | `development` or `production` |
+
+**Example Usage in Dockerfile:**
+
+```dockerfile
+ENV SITE_TITLE="My App Documentation"
+ENV SITE_DESCRIPTION="Complete documentation for My App"
+ENV SITE_URL="https://docs.myapp.com"
+ENV GITHUB_URL="https://github.com/myorg/my-app"
+```
+
+### Config.json Schema
+
+The `config.json` file provides comprehensive site configuration:
+
+```typescript
+interface DocumentationConfig {
+  // Required
+  title: string;
+  description: string;
+  sidebar: SidebarItem[];
+
+  // Optional
+  logo?: {
+    src: string;
+    alt?: string;
+    replacesTitle?: boolean;
+  };
+  social?: {
+    github?: string;
+    twitter?: string;
+    discord?: string;
+    linkedin?: string;
+  };
+  editLink?: {
+    baseUrl: string;
+  };
+  head?: Array<{
+    tag: string;
+    attrs: Record<string, string | boolean | undefined>;
+    content?: string;
+  }>;
+  customCss?: string[];
+  components?: Record<string, string>;
+  locales?: Record<string, LocaleConfig>;
+}
+
+interface SidebarItem {
+  label: string;
+  link?: string;
+  items?: SidebarItem[];
+  autogenerate?: {
+    directory: string;
+    collapsed?: boolean;
+  };
+  collapsed?: boolean;
+  badge?: string | { text: string; variant: 'note' | 'danger' | 'success' | 'caution' };
+}
+```
+
+### Sidebar Configuration Examples
+
+<Tabs>
+  <TabItem label="Manual Structure">
+```json
+{
+  "sidebar": [
+    {
+      "label": "Getting Started",
+      "items": [
+        { "label": "Introduction", "link": "/" },
+        { "label": "Installation", "link": "/getting-started/installation" },
+        { "label": "Quick Start", "link": "/getting-started/quick-start" }
+      ]
+    },
+    {
+      "label": "Guides",
+      "items": [
+        { "label": "Authentication", "link": "/guides/authentication" },
+        { "label": "Authorization", "link": "/guides/authorization" },
+        { "label": "Configuration", "link": "/guides/configuration" }
+      ]
+    }
+  ]
+}
+```
+</TabItem>
+
+  <TabItem label="Auto-generated">
+```json
+{
+  "sidebar": [
+    {
+      "label": "Getting Started",
+      "link": "/"
+    },
+    {
+      "label": "Guides",
+      "autogenerate": {
+        "directory": "guides",
+        "collapsed": false
+      }
+    },
+    {
+      "label": "API Reference",
+      "autogenerate": {
+        "directory": "reference",
+        "collapsed": true
+      }
+    }
+  ]
+}
+```
+
+**Auto-generation:**
+- Automatically generates sidebar items from files in the directory
+- Respects file/folder structure
+- Uses frontmatter `title` for labels
+- Supports nesting based on folder hierarchy
+</TabItem>
+
+  <TabItem label="With Badges">
+```json
+{
+  "sidebar": [
+    {
+      "label": "Guides",
+      "items": [
+        {
+          "label": "Getting Started",
+          "link": "/guides/getting-started"
+        },
+        {
+          "label": "Advanced Features",
+          "link": "/guides/advanced",
+          "badge": "New"
+        },
+        {
+          "label": "Experimental API",
+          "link": "/guides/experimental",
+          "badge": {
+            "text": "Experimental",
+            "variant": "caution"
+          }
+        },
+        {
+          "label": "Deprecated Methods",
+          "link": "/guides/deprecated",
+          "badge": {
+            "text": "Deprecated",
+            "variant": "danger"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Badge Variants:**
+- `note` (blue) - General information
+- `success` (green) - New features
+- `caution` (yellow) - Experimental/beta
+- `danger` (red) - Deprecated/removed
+</TabItem>
+
+  <TabItem label="Collapsible Sections">
+```json
+{
+  "sidebar": [
+    {
+      "label": "Getting Started",
+      "collapsed": false,
+      "items": [
+        { "label": "Introduction", "link": "/" },
+        { "label": "Installation", "link": "/installation" }
+      ]
+    },
+    {
+      "label": "Advanced Topics",
+      "collapsed": true,
+      "items": [
+        { "label": "Performance", "link": "/advanced/performance" },
+        { "label": "Security", "link": "/advanced/security" }
+      ]
+    }
+  ]
+}
+```
+
+**Collapsed Sections:**
+- `collapsed: false` - Section expanded by default
+- `collapsed: true` - Section collapsed by default
+- Users can expand/collapse sections interactively
+</TabItem>
+</Tabs>
+
+---
+
+## Advanced Customization
+
+### Custom Components
+
+Add custom Astro or React components to enhance your documentation:
+
+```dockerfile
+# In your Dockerfile
+COPY ./components/ /app/src/components/
+```
+
+**Example Custom Component:**
+
+```astro
+---
+// src/components/ApiEndpoint.astro
+interface Props {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  path: string;
+  description: string;
+}
+
+const { method, path, description } = Astro.props;
+---
+
+<div class="api-endpoint">
+  <div class="method method-{method.toLowerCase()}">{method}</div>
+  <code class="path">{path}</code>
+  <p class="description">{description}</p>
+</div>
+
+<style>
+  .api-endpoint {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    padding: 1rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.5rem;
+    margin: 1rem 0;
+  }
+
+  .method {
+    padding: 0.25rem 0.5rem;
+    border-radius: 0.25rem;
+    font-weight: bold;
+    font-size: 0.875rem;
+  }
+
+  .method-get { background: #4CAF50; color: white; }
+  .method-post { background: #2196F3; color: white; }
+  .method-put { background: #FF9800; color: white; }
+  .method-delete { background: #F44336; color: white; }
+</style>
+```
+
+**Use in MDX:**
+
+```mdx
+import ApiEndpoint from '~/components/ApiEndpoint.astro';
+
+<ApiEndpoint
+  method="GET"
+  path="/api/users/:id"
+  description="Retrieve a user by ID"
+/>
+```
+
+### Custom CSS Styling
+
+Customize the appearance with custom CSS:
+
+```dockerfile
+# In your Dockerfile
+COPY ./styles/ /app/src/styles/
+```
+
+**Example Custom CSS:**
+
+```css
+/* src/styles/custom.css */
+
+/* Custom color scheme */
+:root {
+  --sl-color-accent: #00a8ff;
+  --sl-color-accent-high: #0095e6;
+  --sl-color-text-accent: #00a8ff;
+}
+
+/* Custom font */
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap');
+
+:root {
+  --sl-font: 'Inter', sans-serif;
+}
+
+/* Custom code block styling */
+pre {
+  border-radius: 8px;
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+}
+
+/* Custom card styling */
+.sl-card {
+  border: 2px solid var(--sl-color-accent);
+  transition: transform 0.2s;
+}
+
+.sl-card:hover {
+  transform: translateY(-4px);
+}
+```
+
+**Reference in config.json:**
+
+```json
+{
+  "customCss": [
+    "./src/styles/custom.css"
+  ]
+}
+```
+
+### Advanced Astro Configuration
+
+For complete control, override the Astro configuration:
+
+```dockerfile
+# In your Dockerfile
+COPY ./astro.config.mjs /app/astro.config.mjs
+COPY ./package.json /app/package.json
+RUN npm install
+```
+
+**Example astro.config.mjs:**
+
+```javascript
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import remarkMermaid from 'remark-mermaid';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: 'My App Documentation',
+      social: {
+        github: 'https://github.com/myorg/my-app',
+      },
+      sidebar: [
+        { label: 'Home', link: '/' },
+        { label: 'Guides', autogenerate: { directory: 'guides' } },
+      ],
+      customCss: ['./src/styles/custom.css'],
+      components: {
+        Head: './src/components/Head.astro',
+        Hero: './src/components/Hero.astro',
+      },
+    }),
+  ],
+  markdown: {
+    remarkPlugins: [remarkMermaid],
+    rehypePlugins: [rehypeAutolinkHeadings],
+  },
+});
+```
+
+<Aside type="caution">
+Advanced configuration requires understanding Astro and Starlight. Start with environment variables and config.json before attempting custom Astro configuration.
+</Aside>
+
+---
+
+## Platform Documentation Example
+
+The Blue Alba Platform's own documentation is built using the same `pae-documentation-template`, demonstrating the feature in production.
+
+### Configuration
+
+**Catalog Module:**
+```json
+{
+  "name": "platform-documentation",
+  "type": "documentation",
+  "displayName": "Platform Documentation",
+  "description": "Complete Blue Alba Platform documentation",
+  "route": "/_/docs",
+  "application": "platform",
+  "operations": ["documentation::access"]
+}
+```
+
+**Access Control:**
+- Operation: `documentation::access`
+- Automatically assigned to administrators
+- Can be granted to additional users via Admin UI
+
+**Content Structure:**
+```
+docs/
+├── index.mdx                    # Home page
+├── getting-started/
+│   ├── installation.mdx
+│   └── quick-start.mdx
+├── guides/
+│   ├── identity-providers.mdx
+│   ├── creating-services.mdx
+│   ├── creating-ui-modules.mdx
+│   └── adding-documentation-sites.mdx
+├── architecture/
+│   ├── overview.mdx
+│   ├── gateway.mdx
+│   └── microservices.mdx
+└── reference/
+    ├── api/
+    └── configuration/
+```
+
+**Continuous Updates:**
+The platform documentation is continuously updated as new features are released, serving as both:
+- **Reference documentation** for platform users
+- **Working example** of the documentation system's capabilities
+
+---
+
+## Best Practices
+
+### Content Organization
+
+<CardGrid stagger>
+  <Card title="Logical Structure" icon="document">
+    Organize content into clear sections: Getting Started, Guides, API Reference, Architecture.
+  </Card>
+
+  <Card title="Progressive Disclosure" icon="forward">
+    Start with simple concepts, gradually introduce complexity. Use collapsible sections for advanced topics.
+  </Card>
+
+  <Card title="Consistent Naming" icon="setting">
+    Use consistent file naming: lowercase, hyphen-separated (e.g., `getting-started.mdx`, not `GettingStarted.mdx`).
+  </Card>
+
+  <Card title="Single Responsibility" icon="document">
+    One topic per page. Break large topics into multiple pages with clear navigation.
+  </Card>
+</CardGrid>
+
+### Writing Style
+
+**Clear and Concise:**
+- Use simple language, avoid jargon
+- Short paragraphs (3-4 sentences)
+- Active voice over passive
+- Present tense for current features
+
+**Code Examples:**
+- Always provide working code examples
+- Include comments explaining key concepts
+- Show complete examples, not just snippets
+- Use syntax highlighting with language tags
+
+**Visual Aids:**
+- Use Mermaid diagrams for flows and architecture
+- Include screenshots for UI-heavy topics
+- Use tables for structured information
+- Add callouts (Aside component) for important notes
+
+### Maintenance
+
+**Keep Documentation Fresh:**
+```bash
+# Update documentation alongside code changes
+git checkout -b feature/new-api-endpoint
+# ... make code changes ...
+# ... update documentation ...
+git add .
+git commit -m "feat: add new API endpoint with documentation"
+```
+
+**Version Documentation:**
+- Use badges to mark new, experimental, or deprecated features
+- Consider version-specific documentation for major changes
+- Include changelog or release notes section
+
+**Review Process:**
+- Treat documentation like code (code review, testing)
+- Check all links and code examples
+- Verify consistency with actual implementation
+- Test builds locally before deploying
+
+### Performance
+
+**Optimize Images:**
+```bash
+# Compress images before adding to documentation
+imagemagick convert logo.png -quality 85 logo-optimized.png
+
+# Use appropriate formats
+# - SVG for logos and diagrams
+# - WebP for photos
+# - PNG for screenshots with text
+```
+
+**Lazy Load Heavy Content:**
+- Use code splitting for large examples
+- Lazy load images below the fold
+- Consider pagination for very long pages
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+<Tabs>
+  <TabItem label="Build Failures">
+**Problem: Docker build fails with "Content not found"**
+
+```bash
+ERROR: Content directory not found: /app/src/content/docs/
+```
+
+**Solution:**
+Ensure your `COPY` commands in Dockerfile are correct:
+
+```dockerfile
+# Correct - relative to build context
+COPY ./docs/ /app/src/content/docs/
+
+# Incorrect - absolute path won't work
+COPY /docs/ /app/src/content/docs/
+```
+
+---
+
+**Problem: Astro build fails during Docker build**
+
+```bash
+ERROR: Cannot find module '@astrojs/starlight'
+```
+
+**Solution:**
+Don't override `package.json` unless you know what you're doing. The base image has all dependencies. If you must override:
+
+```dockerfile
+COPY ./package.json /app/package.json
+RUN npm install  # Ensure this runs after copying package.json
+```
+</TabItem>
+
+  <TabItem label="Content Issues">
+**Problem: Sidebar not showing**
+
+**Causes and Solutions:**
+
+1. **Invalid JSON in config.json:**
+   ```bash
+   # Validate JSON
+   cat config.json | jq .
+   ```
+
+2. **Missing files referenced in sidebar:**
+   ```json
+   // If you reference /guides/getting-started
+   // The file must exist at docs/guides/getting-started.mdx
+   ```
+
+3. **Incorrect autogenerate directory:**
+   ```json
+   {
+     "sidebar": [
+       {
+         "label": "Guides",
+         "autogenerate": {
+           "directory": "guides"  // Must match actual directory name
+         }
+       }
+     ]
+   }
+   ```
+
+---
+
+**Problem: Images not displaying**
+
+**Solution:**
+Ensure images are copied and referenced correctly:
+
+```dockerfile
+# Copy assets
+COPY ./assets/ /app/src/assets
+```
+
+```mdx
+<!-- In your MDX file -->
+![My Image](/src/assets/my-image.png)
+
+<!-- Or using import -->
+import myImage from '~/assets/my-image.png';
+
+<img src={myImage.src} alt="My Image" />
+```
+</TabItem>
+
+  <TabItem label="Navigation Issues">
+**Problem: Documentation link not appearing in platform**
+
+**Checklist:**
+1. **Module registered in catalog?**
+   - Check Admin UI → Catalog → Modules
+   - Verify type is set to `documentation`
+
+2. **Module associated with correct application?**
+   - Verify `application` field matches your app
+
+3. **User has required operation?**
+   - Check user's operations in Admin UI
+   - Verify operation matches module's operations
+
+4. **Module is active?**
+   - Check `active` field is `true` in catalog
+
+**Debugging:**
+```bash
+# Check catalog API
+curl -H "Authorization: Bearer $TOKEN" \
+  https://your-platform.com/api/catalog/modules | jq '.[] | select(.type=="documentation")'
+
+# Check user operations
+curl -H "Authorization: Bearer $TOKEN" \
+  https://your-platform.com/api/users/me | jq '.operations'
+```
+
+---
+
+**Problem: Documentation link redirects to wrong URL**
+
+**Solution:**
+Verify the `route` field in catalog module:
+
+```json
+{
+  "route": "/docs/my-app"  // Must match your deployment path
+}
+```
+
+And ensure your service is accessible at that path through the gateway.
+</TabItem>
+
+  <TabItem label="Access Control">
+**Problem: Users can't access documentation (403 Forbidden)**
+
+**Causes and Solutions:**
+
+1. **Missing operation:**
+   ```bash
+   # Grant operation to user
+   # Via Admin UI: Users → [User] → Operations → Add Operation
+
+   # Via API:
+   POST /api/users/{userId}/operations
+   { "operation": "my-app::documentation::access" }
+   ```
+
+2. **Operation mismatch:**
+   ```json
+   // Ensure module operation matches what users have
+   {
+     "operations": ["my-app::documentation::access"]  // Must match exactly
+   }
+   ```
+
+3. **Module not active:**
+   ```json
+   {
+     "active": true  // Must be true
+   }
+   ```
+
+---
+
+**Problem: Everyone can access documentation (should be restricted)**
+
+**Solution:**
+Add operations to the module:
+
+```json
+{
+  "operations": ["my-app::documentation::access"]
+}
+```
+
+Without operations, documentation is public to all application users.
+</TabItem>
+
+  <TabItem label="Performance">
+**Problem: Documentation site loads slowly**
+
+**Solutions:**
+
+1. **Optimize images:**
+   ```bash
+   # Compress images
+   npm install -g sharp-cli
+   sharp -i input.jpg -o output.jpg -q 80
+   ```
+
+2. **Enable caching:**
+   ```nginx
+   # If using custom nginx config
+   location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
+       expires 1y;
+       add_header Cache-Control "public, immutable";
+   }
+   ```
+
+3. **Reduce page size:**
+   - Split large pages into smaller ones
+   - Use code splitting
+   - Lazy load images
+
+4. **Check network:**
+   ```bash
+   # Test documentation response time
+   curl -w "@curl-format.txt" -o /dev/null -s https://your-platform.com/docs/my-app
+   ```
+
+</TabItem>
+</Tabs>
+
+### Health Check
+
+The documentation container includes a health check endpoint:
+
+```bash
+# Check if documentation service is healthy
+curl http://localhost:8080/health
+
+# Expected response:
+{
+  "status": "healthy",
+  "timestamp": "2024-01-09T10:30:00Z"
+}
+```
+
+### Debug Mode
+
+Enable debug logging for troubleshooting:
+
+```dockerfile
+ENV NODE_ENV=development
+ENV DEBUG=*
+```
+
+Or at runtime:
+
+```bash
+docker run -e NODE_ENV=development -e DEBUG=* -p 8080:80 my-app-documentation
+```
+
+---
+
+## Deployment Considerations
+
+### Container Resources
+
+Set appropriate resource limits:
+
+```yaml
+# docker-compose.yml
+services:
+  my-app-documentation:
+    image: my-app-documentation:latest
+    deploy:
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 256M
+        reservations:
+          cpus: '0.25'
+          memory: 128M
+```
+
+### High Availability
+
+For production deployments:
+
+```yaml
+services:
+  my-app-documentation:
+    image: my-app-documentation:latest
+    deploy:
+      replicas: 2
+      update_config:
+        parallelism: 1
+        delay: 10s
+      restart_policy:
+        condition: on-failure
+        delay: 5s
+        max_attempts: 3
+```
+
+### Monitoring
+
+Monitor documentation health:
+
+```yaml
+services:
+  my-app-documentation:
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:80/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+```
+
+---
+
+## Related Documentation
+
+- **[Creating Services](./creating-services)** - Learn to create backend services
+- **[Creating UI Modules](./creating-ui-modules)** - Build React micro-frontends
+- **[Identity Providers](./identity-providers)** - Configure authentication
+- **[Using Mermaid Diagrams](./mermaid-diagrams)** - Create interactive diagrams
+
+---
+
+## Support and Resources
+
+**Starlight Documentation:**
+- [Starlight Official Docs](https://starlight.astro.build/)
+- [Astro Documentation](https://docs.astro.build/)
+
+**Platform Resources:**
+- Platform Documentation (this site) for reference examples
+- Admin UI for catalog management
+- Gateway API for programmatic access
+
+**Getting Help:**
+1. Check this guide and platform documentation
+2. Review example implementations (platform docs, other services)
+3. Inspect container logs for detailed error messages
+4. Test locally before deploying to production
+
+---
+
+## Summary
+
+You've learned how to create and deploy documentation sites on the Blue Alba Platform:
+
+✅ **Understanding** - Documentation architecture and integration
+✅ **Creating** - Dockerfile, content, and configuration
+✅ **Deploying** - Building, registering, and deploying
+✅ **Integrating** - Automatic navigation and access control
+✅ **Customizing** - Advanced configuration and styling
+✅ **Troubleshooting** - Common issues and solutions
+
+Start by creating a simple documentation site with a few pages, then expand with more content, custom components, and advanced features as needed.