Merge pull request #23 from davidjpeacock/main

dev: add automated build process

Author: davidjpeacock

.github/workflows/build-and-deploy.yml

@@ -0,0 +1,56 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Build documentation
+        run: make html
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./build
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -4,3 +4,7 @@
 # Ruby
 Gemfile.lock
 .bundle/
+
+# Build output
+build/
+docs/

CLAUDE.md

@@ -30,8 +30,8 @@ make help
 ```
 
 Output locations:
-- **HTML**: `docs/index.html`
-- **Images**: `docs/images/` (SVG files automatically copied during build)
+- **HTML**: `build/index.html`
+- **Images**: `build/images/` (SVG files automatically copied during build)
 
 ## Documentation Structure
 
@@ -52,7 +52,7 @@ The documentation uses AsciiDoc format with the following structure:
   - `reference-role-*.adoc` - Ansible role reference documentation
 - `images/` - Static SVG workflow diagrams
   - `*.svg` - VMware migration workflow diagrams
-- `docs/` - Build output directory (generated, not in source control)
+- `build/` - Build output directory (generated, not in source control)
 
 ### Key Documentation Features
 - Single-page HTML generation
@@ -70,19 +70,29 @@ The build process is straightforward:
 ### HTML Build
 - Uses `index.adoc` as the source document
 - Builds single-page HTML with all content
-- Output: `docs/index.html`
-- Automatically copies SVG images from `images/` to `docs/images/`
+- Output: `build/index.html`
+- Automatically copies SVG images from `images/` to `build/images/`
 
 ## Development Workflow
 
 When working with documentation:
 
 1. Source files use AsciiDoc format (.adoc)
-2. Build output goes to the `docs/` directory
+2. Build output goes to the `build/` directory
 3. Static SVG images are automatically copied during build
 4. Use `make clean` to reset build state
 5. Edit `index.adoc` to control what content is included
 
+### CI/CD Pipeline
+
+Documentation is automatically built and deployed to GitHub Pages when changes are pushed to the `main` branch:
+
+- **Workflow**: `.github/workflows/build-and-deploy.yml`
+- **Trigger**: Push to `main` branch or manual workflow dispatch
+- **Build**: Uses Ruby 3.2, installs dependencies via Bundler, runs `make html`
+- **Deploy**: Uploads build artifacts from `build/` directory to GitHub Pages
+- **URL**: Deployed to the repository's GitHub Pages URL
+
 ## Important Notes for Code Assistance
 
 ### File Path Patterns

Makefile

@@ -5,7 +5,7 @@ ASCIIDOCTOR = asciidoctor
 
 # Source and output directories
 SRC_DIR = .
-HTML_OUTPUT_DIR = docs
+HTML_OUTPUT_DIR = build
 IMAGE_SRC_DIR = images
 
 # Main document