stream-docs

This repo hosts all STREAM documentation — both the internal developer docs (this site) and the external customer-facing docs — as two separate MkDocs projects living side-by-side.

stream-docs/
├── internal/   # MkDocs site you are reading right now
└── external/   # Public customer docs (DE + EN)

Running locally

Both sites are served via Docker Compose. Start everything with:

just up

Both servers watch for file changes and reload automatically, so you can edit Markdown and see the result in the browser immediately.

Adding a page

Internal docs

1. Create a .md file under internal/docs/.
2. Add it to the nav section in internal/mkdocs.yml.

External docs

External docs are bilingual (German default, English secondary). The folder structure mirrors the locale:

external/docs/
├── de/   # German content (default)
└── en/   # English content

1. Create the .md file in both de/ and en/ at the same relative path.
2. Add the page to the nav in external/mkdocs.yml.
3. If the nav label is new, add a German translation under plugins.i18n.languages[de].nav_translations in external/mkdocs.yml.

Diagrams

Both sites support Mermaid (fenced code blocks with ```mermaid), PlantUML (via the plantuml_markdown extension), and Kroki-backed diagram blocks such as kroki-d2 in the external docs. The local Compose stack includes both renderers:

• PlantUML at http://plantuml:8080
• Kroki at http://kroki:8000

Both endpoints are available inside the container network, so no extra local setup is required beyond just up.

Mermaid

Use a fenced code block with the language tag mermaid:

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant DB

    Client->>API: POST /products
    API->>DB: INSERT product
    DB-->>API: ok
    API-->>Client: 201 Created
```

sequenceDiagram
    participant Client
    participant API
    participant DB

    Client->>API: POST /products
    API->>DB: INSERT product
    DB-->>API: ok
    API-->>Client: 201 Created

PlantUML

Use a fenced code block with the language tag plantuml:

```plantuml
@startuml
actor User
User -> API : request
API -> Cache : lookup
alt cache hit
    Cache --> API : data
else cache miss
    API -> DB : query
    DB --> API : data
    API -> Cache : store
end
API --> User : response
@enduml
```

Publishing

Both sites are built in GitHub Actions and then uploaded to Cloudflare Pages as prebuilt static assets. CI runs each docs build in its own Python container and attaches local Kroki and PlantUML service containers for diagram rendering.

1. Make your changes.
2. Create a conventional commit following the pattern used in this repo:
   • chore(internal): <description> for changes to the internal docs
   • chore(external): <description> for changes to the external docs
3. Push to main directly, or open a PR and merge it.

The workflows in .github/workflows/external-docs.yml and .github/workflows/internal-docs.yml build and deploy each site independently through the shared .github/workflows/docs-reusable.yml workflow. Repository configuration must provide:

• GitHub secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
• GitHub repository variables: CLOUDFLARE_PAGES_PROJECT_EXTERNAL, CLOUDFLARE_PAGES_PROJECT_INTERNAL

Cloudflare Pages should be configured for direct upload from CI rather than source builds from the Pages Git integration.