Build and Deployment

This page documents how to build and deploy the maven-mcps documentation site.

Prerequisites

  • Node.js (for npx/Antora)

  • netlify-cli (npm install -g netlify-cli) - for deployment only

Makefile Targets

The project includes a Makefile in the repository root for common tasks:

Target Description

make build-local

Build for local development (no edit URLs) [default]

make build-remote

Build for remote deployment (with GitHub edit URLs)

make clean

Remove build artifacts (./build/ directory)

make deploy

Build and deploy to Netlify (production)

make deploy-preview

Build and deploy a draft preview to Netlify (unique URL per deploy)

make deploy-branch

Build and deploy a branch preview (stable URL based on the branch name)

make serve

Build and serve with live reload (manual rebuild)

make dev

Development mode: watch sources, rebuild automatically, live reload

make help

Show available targets

Building the Site

Local Development

To build the documentation site for local development:

make build-local

This runs Antora with antora-local-playbook.yml and generates the site in ./build/local-site/. Edit URLs are disabled in local builds.

Remote Deployment

To build for remote deployment (Netlify, GitHub Pages):

make build-remote

This runs Antora with antora-playbook.yml and generates the site in ./build/remote-site/. Edit URLs point to GitHub with the current branch.

Running Antora Directly

You can also run Antora directly:

# Local build
npx antora antora-local-playbook.yml

# Remote build (CI=true required for GitHub edit URLs)
CI=true npx antora --url https://maven-mcps.netlify.app antora-playbook.yml
The CI=true environment variable is required for remote builds. When Antora reads from local worktrees, it defaults to file:// edit URLs. Setting CI=true forces Antora to use the configured edit_url pointing to GitHub. In most CI environments (GitHub Actions, Netlify, etc.), this variable is already set.

Deploying to Netlify

Environment Variables

Deployment requires two environment variables:

NETLIFY_AUTH_TOKEN

Your Netlify personal access token. Generate one at Netlify User Settings.

NETLIFY_PROJECT_ID

The Netlify site ID. Find this in your site’s settings under "Site information".

Production Deployment

Deploy to production (publishes to the live site URL):

export NETLIFY_AUTH_TOKEN="your-token"
export NETLIFY_PROJECT_ID="your-site-id"
make deploy

Preview Deployment

Deploy a draft preview (generates a unique preview URL):

make deploy-preview

This is useful for one-off reviews before publishing to production.

Branch Preview Deployment

Deploy a branch preview with a stable URL based on the current branch name:

make deploy-branch

The branch name is determined automatically from git branch --show-current. Slashes are replaced with dashes to form a valid URL alias.

This creates a predictable URL like https://<branch-name>--maven-mcps.netlify.app. Subsequent deploys from the same branch update the same URL, making it ideal for ongoing review during feature development.

Example: If you’re on branch feature/my-feature, the deployment URL becomes https://feature-my-feature—​maven-mcps.netlify.app.

Local Development Server

Development Mode (Recommended)

For the best development experience with automatic rebuilds and live reload:

make dev

This starts a development server that:

  • Watches all .adoc source files for changes

  • Automatically rebuilds the site when sources change

  • Refreshes the browser automatically

Open http://localhost:58000 in your browser. Press Ctrl+C to stop.

To use a different port:

DEV_PORT=9000 make dev

Serve Mode

If you prefer manual rebuilds with live reload on build output:

make serve

This serves the site with live reload but requires manual make build-local in another terminal to rebuild.

Simple HTTP Server

Alternatively, use a simple HTTP server without a live reload:

make build-local
cd build/local-site
python -m http.server 8000

Then open http://localhost:8000 in your browser.

Playbook Configuration

The project uses two Antora playbooks:

antora-local-playbook.yml

For local development. Disables edit URLs. Outputs to ./build/local-site/.

antora-playbook.yml

For remote deployment. Edit URLs point to GitHub using {refname} for the current branch. Outputs to ./build/remote-site/.

Both playbooks:

  • Read from the working directory (via worktrees: true)

  • Include both the umbrella docs and mail-mcp component

  • Use supplemental UI files for custom header styling

Related Documentation