Building the Site Locally

Building the documentation site locally allows you to preview changes before deploying to Kubernetes.

Prerequisites

  • Node.js (v16 or later)

  • npm

  • Git credentials configured (for private repositories)

Quick Start

# Install dependencies
npm ci

# Build the site
npm run build

The generated site will be output to build/site/.

Previewing the Site

Option 1: Open Directly in Browser

Open build/site/index.html in your browser. This works for basic previewing, though some features (like search) require a web server.

Option 2: Use a Local Web Server

# Using npx (no install needed)
npx serve build/site

# Or with a specific port
npx serve build/site -l 8080

Then open http://localhost:3000 (or http://localhost:8080 if you specified a port).

Build and Serve in One Command

npm run build && npx serve build/site

Git Credentials Setup

The playbook in antora-playbook.yml pulls content from multiple Git repositories. For private repositories, you need to configure authentication.

Option 1: SSH Keys (Recommended)

SSH is the recommended approach for local development as it integrates with your existing Git setup.

Step 1: Update the Playbook URLs

Modify antora-playbook.yml to use SSH URLs instead of HTTPS:

content:
  sources:
    - url: ./
      branches: HEAD
      start_path: docs
    - url: [email protected]:christhonie/event-docs.git
      branches: [main]
    - url: [email protected]:christhonie/doc-java.git
      branches: [main]
    - url: [email protected]:christhonie/doc-software.git
      branches: [main]
    - url: [email protected]:christhonie/event-registration-ui.git
      branches: [feature/p2-security]
      start_path: docs

Step 2: Ensure SSH Agent Has Your Key

# Check if key is loaded
ssh-add -l

# Add key if needed
ssh-add ~/.ssh/id_ed25519   # or id_rsa

# Test connection
ssh -T [email protected]
On Windows, ensure the OpenSSH Authentication Agent service is running.

Option 2: Git Credential Store (HTTPS)

Use this if you prefer HTTPS URLs or cannot use SSH.

Step 1: Create a Personal Access Token (PAT)

  1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)

  2. Click "Generate new token (classic)"

  3. Set a name and expiration

  4. Select scope: repo (for private repos)

  5. Click "Generate token" and copy it immediately

Step 2: Configure Git Credential Store

Create a .git-credentials file in your home directory:

Operating System File Location

Windows

C:\Users\<username>\.git-credentials

Linux/Mac

~/.git-credentials

Add your credentials (one line per host):

https://<username>:<personal-access-token>@github.com

Configure Git to use the credential store:

git config --global credential.helper store

Step 3: Test the Credentials

git ls-remote https://github.com/christhonie/event-docs.git

Troubleshooting

Authentication Failures

SSH

Verify your key is loaded with ssh-add -l and test with ssh -T [email protected]
HTTPS

Ensure your PAT has repo scope and hasn’t expired

Build Errors

Check the Antora output for specific error messages. Common issues:

  • Repository not found - Verify the URL and your access permissions

  • Branch not found - Ensure the branch name in the playbook matches the remote

  • Invalid playbook - Validate YAML syntax in antora-playbook.yml

Clean Build

To start fresh, remove cached content:

npm run clean
npm run build

See Also