This website is built using Docusaurus, a modern static website generator.

npm i

npm start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

npm run build

This command generates static content into the build directory and can be served using any static contents hosting service.

graph TD;
  A[Root Directory]

  A --> E[overview/]
  E --> E1[getting-started.md]
  
  A --> C[codelabs/]
  C --> C1[codelabs.md]
  C --> C2[Codelab Contents goes here]
  C --> C3[intro.md]
  C --> C4[next-steps.md]
  
  A --> D[contributing/]
  D --> D1["..."]

  A --> B[changelog/]
  B --> B1[changelog.md]
  
  A --> F[showcase/]
  F --> F1[showcase.md]
  
  A --> G[static/]
  G --> G1[kdocs/]
  G --> H1[...]

The site includes an AI chat widget ("Ask AI") that lets developers ask questions about Multipaz and get answers grounded in the official documentation.

┌──────────────────────────────────┐
│  Docusaurus Site (Frontend)      │
│                                  │
│  src/components/AskAIWidget.js   │
│  └─ Chat UI, streams responses   │
│     via Server-Sent Events       │
│                                  │
│  src/theme/Root.js               │
│  └─ Mounts widget on every page  │
└──────────────┬───────────────────┘
               │ POST /api/chat
               ▼
┌──────────────────────────────────┐
│  Vercel Serverless (api/)        │
│                                  │
│  api/chat.js                     │
│  └─ Gemini 2.5 Flash            │
│     + full docs as system prompt │
│                                  │
│  docs-context.txt (bundled)      │
│  └─ Built by build-docs-context  │
└──────────────────────────────────┘

See api/README.md for API setup, environment variables, and endpoint documentation.

api/build-docs-context.js produces api/docs-context.txt, which is the knowledge base sent to Gemini as a system prompt. It aggregates content from two sources:

Local directories (from this repo):

Remote files (fetched from openwallet-foundation/multipaz at build time):

After adding or modifying documentation in any of the sources above, rebuild the context file:

cd api
npm run build-context

This fetches the latest remote files and re-aggregates everything into docs-context.txt. The file is bundled into the Vercel serverless function at deploy time via vercel.json.

To include a new local directory, add it to the DOCS_DIRS array in api/build-docs-context.js.

To include a new file from the multipaz repo, add its path to the MULTIPAZ_REPO_FILES array in the same file.

API server (set in Vercel):

Docusaurus build (set as GitHub repo variables under Settings → Secrets and variables → Actions → Variables):

cd api
npm install
npm run build-context   # rebuild docs-context.txt
vercel --prod           # deploy to production

On first deploy, Vercel will prompt you to link the project. After that, subsequent deploys with vercel --prod will update the production deployment.

This project uses two repositories with automated documentation integration:

Kotlin Repo: Source code with KDocs Docusaurus Repo: Documentation site that displays the generated API docs

┌─────────────────────┐     ┌──────────────────────┐
│  Kotlin Repository  │     │ Docusaurus Repository│
│                     │     │                      │
│  ┌───────────────┐  │     │  ┌───────────────┐   │
│  │  Source Code  │  │     │  │  Markdown     │   │
│  └───────┬───────┘  │     │  │  Documentation│   │
│          │          │     │  └───────────────┘   │
│  ┌───────▼───────┐  │     │                      │
│  │  Dokka Tool   │  │     │  ┌───────────────┐   │
│  └───────┬───────┘  │     │  │  Static Dir   │   │
│          │          │     │  │  ┌─────────┐  │   │
│  ┌───────▼───────┐  │     │  │  │ /api/   │◄─┼───┘
│  │ Generated     │  │     │  │  └─────────┘  │   │
│  │ API Docs      │──┼─────┼─►│               │   │
│  └───────────────┘  │     │  └───────────────┘   │
└─────────────────────┘     └──────────────────────┘

[Code Changes] → [Trigger Action] → [Build KDocs] → [Copy to Docusaurus] → [Deploy Site]

GitHub Actions Setup

1. In Multipaz Repository => .github/workflows/trigger-docusaurus-update.yml
2. In Multipaz Developer Website Repository => .github/workflows/docs.yml

To enable automatic documentation updates between repositories, you need to set up a Personal Access Token (PAT).

1. Go to GitHub Settings: Navigate to https://github.com/settings/personal-access-tokens/new
2. Select Token Type: Choose "Fine-grained personal access tokens"
3. Configure Token Settings:
   • Token name: DOCS_REPO_ACCESS_TOKEN
   • Description: Token for automated documentation updates between multipaz and developer website repo
   • Expiration: 366 days (or your preferred duration)
4. Set Repository Access:
   • Resource Owner: openwallet-foundation
   • Repository access: Selected repositories
   • Select repository: openwallet-foundation/multipaz-developer-website
5. Set Permissions:
   • Content: Read and write
   • Metadata: Read
6. Generate Token: Click "Generate token" and copy the token immediately (it won't be shown again)

1. Go to Multipaz Repository: Navigate to https://github.com/openwallet-foundation/multipaz/settings/secrets/actions
2. Add New Secret:
   • Click "New repository secret"
   • Name: DOCS_REPO_ACCESS_TOKEN
   • Secret: Paste the token you generated in Step 1
   • Click "Add secret"

This setup allows the Trigger Docs Update workflow to automatically update the developer website whenever changes are made to the multipaz repository.

Docusaurus can run in two modes depending on your deployment setup:

For custom domains like developer.multipaz.org:

1. Enable GitHub Pages: In Docusaurus repo, go to Settings → Pages and enable GitHub Pages with GitHub Actions as source
2. Set Custom Domain: Under Custom domain, enter:

   developer.multipaz.org
   

3. Save Changes: Click save to apply the custom domain
4. Verify DNS: Optionally, verify that DNS settings (CNAME or A records) are set properly for developer.multipaz.org pointing to GitHub Pages
5. Set Environment Variable: Configure WEBSITE_ENVIRONMENT GitHub repository variable as PRODUCTION

For github.io pages like openwallet-foundation.github.io/multipaz-developer-website:

1. Enable GitHub Pages: In Docusaurus repo, go to Settings → Pages and enable GitHub Pages with GitHub Actions as source
2. Set Environment Variable: Configure WEBSITE_ENVIRONMENT GitHub repository variable as DEVELOPMENT
3. No Custom Domain: Leave the custom domain field empty

After configuration:

• Trigger the Build and Deploy Docusaurus with KDocs workflow
• The baseUrl will automatically be set to:
  • / for custom domains (PRODUCTION mode)
  • /{repository_name} for github.io pages (DEVELOPMENT mode)

See GitHub's guide for more details: Configuring a custom domain for your GitHub Pages site