# Publishing the docs site

The docs system now has two layers:

- `apps/docs-site/public/content/` is the **source of truth** for the markdown content.
- `apps/docs-site/scripts/` owns the generator, Mermaid export, and explorer graph data.
- `apps/docs-site/` is the **deployable frontend** that packages those assets behind a proper app shell built with `@crown/router` and `@crown/ui`.

The public docs image builds the latest generated docs directly inside the frontend app and serves the compiled site with nginx.

## What the image serves

The public docs image serves:

- `/` as the app-style docs frontend
- `/explorer/` as the interactive architecture explorer
- `/diagrams/generated/*` for the generated Mermaid, SVG, and PNG artifacts
- `/content/*` for the raw markdown source pages shipped from `apps/docs-site/public/content/`

That means the polished frontend and the raw underlying artifacts ship together in one image.

## Source locations

Use:

- `apps/docs-site/` for the frontend shell, routing, content, and generator scripts
- `docker/Dockerfile.docs` for the production image build
- `apps/docs-site/public/diagrams/generated/` for generated Mermaid, SVG, and PNG outputs

## Local workflow

Generate the latest content/data artifacts and build the frontend app locally:

```text
cd apps/docs-site
bun run build
```

Refresh Mermaid SVG/PNG diagram artifacts explicitly when diagram sources change:

```text
cd apps/docs-site
bun run generate
```

For local app development with the new UI:

```text
cd apps/docs-site
bun run dev
```

For a production-style local preview, use:

```text
cd apps/docs-site
bun run preview
```

## Building the image

Build the deployable docs image from the repo root:

```text
docker build -f docker/Dockerfile.docs -t crown-docs .
```

The Docker build now does the important bits itself:

1. installs workspace dependencies
2. regenerates the docs artifacts inside `apps/docs-site`
3. builds `apps/docs-site`
4. copies the compiled frontend into nginx

To run the image locally:

```text
docker run --rm -p 4000:80 crown-docs
```

Then open:

- `http://localhost:4000/` for the docs frontend
- `http://localhost:4000/explorer/` for the interactive explorer

## Deploying with Coolify

If you want to publish the docs through Coolify, point the application at:

- the repo root as build context
- `docker/Dockerfile.docs` as the Dockerfile

Recommended runtime settings:

- expose port `80`
- place it behind a domain such as `docs.<your-domain>`
- keep the deployment image registry-backed, just like the other frontend apps

## Suggested CI sequence

For public docs deploys, the sequence should usually be:

1. `bun run --cwd apps/docs-site generate`
2. `bun run --cwd apps/docs-site generate:check`
3. `bun run --cwd apps/docs-site build`
4. build the docs image
5. push the image to the target registry
6. let Coolify deploy the updated image

That keeps the published site deterministic, verifies the generated assets are current, and ensures the app shell matches the latest docs state.

## When to rebuild

Rebuild the docs image whenever you change:

- architecture markdown pages
- generated diagram scripts or outputs
- explorer code or graph data
- docs app routes, styling, or shell layout
- deployment references or operating guides