Embedding as a docs subfolder

You can drop demolab into another project as a self-contained docs/wiki site — e.g. a wiki/ folder inside a business repo — and publish it to that repo’s GitHub Pages. Run it with a coding agent: say “embed demolab as a docs site” and point it at the host project. It can also be done by hand.

The core machinery is already portable: every CLI and notebook resolves its paths relative to its own file location, not the current directory or the git root, so the tree works wherever it sits. The only things that need attention are serving (a base path) and deploying (a workflow in the host repo).

1. Place it

Copy demolab (degitted — without its .git) into the host project, e.g.:

your-project/
├── .github/workflows/        ← host repo's workflows live here
├── wiki/                      ← demolab clone
│   ├── pyproject.toml
│   └── src/{clis,notebooks,artifacts,docs}
└── … the rest of your project

Delete demolab’s bundled .github/workflows/deploy.yml from the copy — it assumes demolab is the repo root and won’t run when nested. The host repo deploys the wiki instead (step 3).

2. Run from inside the subfolder

Always invoke the toolchain from within the wiki/ folder, so uv and bun resolve demolab’s manifests and not the host project’s:

cd wiki
uv sync
cd src/docs && bun install && bun run dev

3. Configure how it’s served (env vars)

Serve config and branding are environment-driven, so embedding never requires editing source. All have demolab defaults; override what you need:

For local dev, put them in wiki/src/docs/.env. For deploys, set them in the workflow (below). For a project Pages site served at https://<user>.github.io/<repo>/, PUBLIC_BASE_PATH is /<repo>.

4. Deploy to the host repo’s GitHub Pages

Add this workflow to the host project at .github/workflows/deploy-wiki.yml (not inside wiki/), adjust the three env values, and enable Pages on the host repo (Settings → Pages → Source: GitHub Actions):

name: Deploy wiki to GitHub Pages
on:
  push:
    branches: [main]
    paths: ['wiki/**']          # only rebuild when the wiki changes
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

env:
  WIKI_DOCS: wiki/src/docs                          # path to demolab's docs from the repo root
  PUBLIC_SITE_URL: https://your-username.github.io  # your Pages origin
  PUBLIC_BASE_PATH: /your-repo-name                 # your project Pages path

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Install dependencies
        working-directory: ${{ env.WIKI_DOCS }}
        run: bun install --frozen-lockfile
      - uses: actions/configure-pages@v5
      - name: Build site
        working-directory: ${{ env.WIKI_DOCS }}
        run: bun run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ${{ env.WIKI_DOCS }}/dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

Push to the host repo’s main and the wiki publishes at https://your-username.github.io/your-repo-name/.

Notes

• One Pages site per repo. A project Pages site serves a single tree, so this publishes the wiki at the host repo’s Pages root. If the host already uses Pages for something else, deploy the wiki from a dedicated repo instead.
• Updating still works. The Adopting features from upstream flow (ar007.md) uses git fetch <upstream> + read-as-reference, which works fine from inside the host repo.
• Page <title>s still say “demolab” (they’re literal per-page strings). Change them if the browser-tab title matters for your wiki.