Nychthemeron/docs/superpowers/plans/2026-06-11-docs-site-and-docker.md

Docs Site Docker Image + Install Page Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add an Installation page to the Storybook playground, package the playground's static build as a nychthemeron-docs Docker image served by nginx, and wire up CI to build/push that image on version tags.

Architecture: A new MDX docs page (packages/playground/stories/Install.mdx) documents installing @nychthemeron/library via npm/pnpm/yarn/bun from the private Forgejo npm registry. A new multi-stage packages/playground/Dockerfile builds the library and Storybook static output with oven/bun:1, then copies storybook-static into nginx:alpine. A root .dockerignore keeps the build context lean. A new publish-docs job in .forgejo/workflows/ci.yml, parallel to publish, builds and pushes the image on v* tags.

Tech Stack: Storybook 10 (@storybook/addon-docs), Vue 3, Bun, Docker (multi-stage, nginx:alpine), Forgejo Actions.

---

Task 1: Add Installation MDX page

Files:

• Create: packages/playground/stories/Install.mdx

• Step 1: Create the MDX file

import { Meta } from '@storybook/addon-docs/blocks'

<Meta title="Get Started/Installation" />

# Installation

`@nychthemeron/library` is published to a private npm registry hosted on
Forgejo. Configure your package manager for the `@nychthemeron` scope, then
install the package.

## Configure the registry

Add the following to your project's `.npmrc`:

@nychthemeron:registry=https://git.mcpeakdev.com/api/packages/mcpeakdev/npm/

## npm

```bash
npm install @nychthemeron/library

pnpm

pnpm add @nychthemeron/library

yarn

yarn add @nychthemeron/library

bun

bun add @nychthemeron/library

- [ ] **Step 2: Build Storybook and verify the page is included**

Run: `cd packages/playground && bun run build`

Expected: Build succeeds with output ending in something like
`Output directory: storybook-static`. Then run:

`grep -o '"title":"Get Started/Installation"' packages/playground/storybook-static/index.json`

Expected: prints `"title":"Get Started/Installation"`.

- [ ] **Step 3: Commit**

```bash
git add packages/playground/stories/Install.mdx
git commit -m "Add installation docs page to playground"

---

Task 2: Add root .dockerignore

Files:

• Create: .dockerignore

• Step 1: Create .dockerignore

node_modules
**/node_modules
**/dist
**/storybook-static
**/.storybook-static
.git
docs
.tmp
.bun-cache
.pw-browsers
.pw-libs
.shots
*.log

• Step 2: Commit

git add .dockerignore
git commit -m "Add .dockerignore for docs Docker build"

---

Task 3: Add Dockerfile for the docs site

Files:

• Create: packages/playground/Dockerfile

• Step 1: Create the Dockerfile

# syntax=docker/dockerfile:1

FROM oven/bun:1 AS build
WORKDIR /app
COPY . .
RUN bun install --frozen-lockfile
RUN cd packages/library && bun run build
RUN cd packages/playground && bun run build

FROM nginx:alpine AS runtime
COPY --from=build /app/packages/playground/storybook-static /usr/share/nginx/html
EXPOSE 80

• Step 2: Build and run the image locally

Run (from repo root):

docker build -t nychthemeron-docs:test -f packages/playground/Dockerfile .
docker run -d --rm --name nychthemeron-docs-test -p 8080:80 nychthemeron-docs:test
sleep 2
curl -sf http://localhost:8080/ | grep -i storybook
docker stop nychthemeron-docs-test

Expected: docker build completes successfully, the container starts, and the curl output contains a reference to storybook (from storybook-static/index.html).

If the Docker CLI/daemon isn't available in the current environment (e.g. sandboxed dev container), skip running this step here and ask the user to run it locally before merging.

• Step 3: Commit

git add packages/playground/Dockerfile
git commit -m "Add Dockerfile for nychthemeron-docs static site"

---

Task 4: Add publish-docs CI job

Files:

• Modify: .forgejo/workflows/ci.yml

• Step 1: Add the publish-docs job

Add this job after the existing publish job (same indentation level, i.e. as a sibling under jobs:):

    publish-docs:
        needs: build
        if: startsWith(github.ref, 'refs/tags/v')
        runs-on: docker
        steps:
            - name: Checkout
              uses: actions/checkout@v4

            - name: Log in to registry
              uses: docker/login-action@v3
              with:
                  registry: git.mcpeakdev.com
                  username: ${{ github.actor }}
                  password: ${{ secrets.FORGEJO_TOKEN }}

            - name: Extract image tag
              id: meta
              run: echo "tag=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"

            - name: Build and push docs image
              uses: docker/build-push-action@v6
              with:
                  context: .
                  file: packages/playground/Dockerfile
                  push: true
                  tags: |
                      git.mcpeakdev.com/mcpeakdev/nychthemeron-docs:${{ steps.meta.outputs.tag }}
                      git.mcpeakdev.com/mcpeakdev/nychthemeron-docs:latest                      

• Step 2: Verify YAML structure

Run: bun run --eval "console.log('ok')" is not a YAML check — instead, visually confirm in the file that publish-docs: is indented exactly like publish: (4 spaces under jobs:), and that all of its child keys (needs, if, runs-on, steps, and each - name: step) match the indentation pattern used by the publish job. Confirm there are exactly three top-level jobs: build, publish, publish-docs.

• Step 3: Commit

git add .forgejo/workflows/ci.yml
git commit -m "Add publish-docs job to build and push nychthemeron-docs image"