# STACKIT Docs Integration

This document describes how Professional Services Terraform examples are synced as `.mdx` asset cards to the STACKIT documentation assetcontainer.

## Overview

Each example in `examples/` declares metadata in `stackit.docs.yaml`. On merge to `main`, a GitHub Actions workflow generates `.mdx` asset files and opens a PR to the `stackitcloud/docs-content` repository under `docs/cloud-framework/architecture-framework/assetcontainer/professional-services/`.

## Directory Structure

```
professional-service/
├── examples/
│   ├── alb-tls-examples/
│   │   ├── README.md
│   │   ├── stackit.docs.yaml    # <-- metadata for docs card
│   │   └── ...
│   ├── ske-azure-arc-integration/
│   │   ├── README.md
│   │   ├── stackit.docs.yaml    # <-- metadata for docs card
│   │   └── ...
│   └── ...
├── ci-scripts/
│   ├── aggregate_docs.py        # generates .mdx files + _meta.yml
│   └── sync-stackit-docs.sh     # CI: clone docs, copy files, PR
└── STACKIT-DOCS.md              # this file
```

## stackit.docs.yaml Format

Each example must contain:

```yaml
headline: Example Title
description: Short description of what the example demonstrates.
tags:
  - ske
  - kubernetes
  - terraform
```

| Field         | Required | Description                               |
| ------------- | -------- | ----------------------------------------- |
| `headline`    | Yes      | Title displayed on the asset card         |
| `description` | Yes      | Brief summary (1-2 sentences) on the card |
| `tags`        | Yes      | Tags for filtering (shown on card, max 5) |

## Generated .mdx Format

Each `stackit.docs.yaml` is transformed into an `.mdx` file with `frameworkAsset` frontmatter:

```mdx
---
title: SKE Azure Arc Integration
description: Terraform and CLI steps to connect a STACKIT SKE cluster to Azure Arc.
hideBreadcrumbs: true
sidebar:
  hidden: true
frameworkAsset:
  owner: Professional Services
  managed: true
  category: guide
  external: true
  recommended: true
  tags:
    - ske
    - azure
    - terraform
---

import { Card } from "@astrojs/starlight/components";

# SKE Azure Arc Integration

...
```

## CI Process

```mermaid
flowchart TD
    A[Developer adds/updates<br>stackit.docs.yaml] --> B[PR to professional-services]
    B --> Merged{Merged to main?}
    Merged -->|Yes| C[GitHub Actions triggered]
    Merged -->|No| B
    C --> D[aggregate_docs.py<br>generates .mdx files + _meta.yml]
    D --> E[Clone docs-content repo]
    E --> F[Copy .mdx files to<br>assetcontainer/professional-services/]
    F --> G{Any file changes<br>vs current docs?}
    G -->|No| H[Exit: docs up to date]
    G -->|Yes| I[Create feature branch<br>autopr/sync-professional-service-examples]
    I --> J[Commit + push changes]
    J --> K[Create PR to docs-content]
    K --> L[Review and merge on<br>docs-content side]
```

## Adding a New Example

1. Create a new directory under `examples/`
2. Add your Terraform code and `README.md`
3. Create `stackit.docs.yaml` with the required fields:

```yaml
headline: My New Example
description: Demonstrates how to deploy X on STACKIT using Y.
tags:
  - ske
  - terraform
  - my-tag
```

4. Open a PR to this repository
5. Once merged, the CI will automatically:
   - Generate `.mdx` asset files from all `stackit.docs.yaml` files
   - Clone the `docs-content` repository
   - Copy files to `assetcontainer/professional-services/`
   - Open a PR if content has changed

## Scripts

### aggregate_docs.py

The Python script:

- Scans `examples/*/stackit.docs.yaml`
- Generates `.mdx` files with `frameworkAsset` frontmatter
- Generates `_meta.yml` for the assetcontainer

Run locally to preview:

```bash
python3 ci-scripts/aggregate_docs.py
ls .generated-mdx/professional-services/
cat .generated-mdx/professional-services/ps-my-example.mdx
```

### sync-stackit-docs.sh

The CI entrypoint:

- Calls `aggregate_docs.py` to generate `.mdx` files
- Clones `stackitcloud/docs-content`
- Copies generated files to `assetcontainer/professional-services/`
- Creates a PR if changes are detected

### Environment Variables

| Variable             | Required | Description                                             |
| -------------------- | -------- | ------------------------------------------------------- |
| `STACKIT_DOCS_TOKEN` | Yes      | GitHub PAT with repo write permissions                  |
| `STACKIT_DOCS_REPO`  | No       | Target docs repo (default: `stackitcloud/docs-content`) |

### Manual Execution

```bash
export STACKIT_DOCS_TOKEN=<your-github-pat>
bash ci-scripts/sync-stackit-docs.sh
```

## GitHub Actions Secret

To enable the CI workflow, add the following secret to the repository:

- **Secret name:** `STACKIT_DOCS_TOKEN`
- **Value:** GitHub Personal Access Token with `repo` scope

The workflow (`.github/workflows/sync-stackit-docs.yaml`) triggers on:

- Every push to `main` that modifies `examples/**/stackit.docs.yaml`
- Manual trigger via the GitHub Actions UI