Fix build configuration and add PR preview workflow for volttron.org deployment

.github/workflows/pr-preview.yaml

@@ -0,0 +1,90 @@
+# Workflow for building and previewing Hugo site for pull requests
+name: PR Preview Build
+
+on:
+  pull_request:
+    branches:
+      - main
+
+# Default to bash
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  # Build job for PR preview
+  build-preview:
+    runs-on: ubuntu-latest
+    env:
+      HUGO_VERSION: 0.126.0
+    steps:
+      - name: Install Hugo CLI
+        run: |
+          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
+          && sudo dpkg -i ${{ runner.temp }}/hugo.deb          
+
+      - name: Install Dart Sass
+        run: sudo snap install dart-sass
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Install Node.js dependencies
+        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
+
+      - name: Build with Hugo (Preview)
+        env:
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+          TZ: America/Los_Angeles
+        run: |
+          hugo \
+            --gc \
+            --minify \
+            --baseURL "https://eclipse-volttron.github.io/"
+
+      - name: Upload preview artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: pr-preview-${{ github.event.pull_request.number }}
+          path: ./public
+          retention-days: 7
+
+      - name: Comment on PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const runId = context.runId;
+            const repo = context.repo;
+
+            const comment = `## 🔍 Preview Build Complete
+
+            The site has been built successfully for this PR!
+
+            ### How to preview:
+            1. Download the preview artifact from the [workflow run](https://github.com/${repo.owner}/${repo.repo}/actions/runs/${runId})
+            2. Extract the zip file
+            3. Open \`index.html\` in your browser to preview the site
+
+            ### Alternative preview methods:
+            - Use a local HTTP server: \`python -m http.server 8000\` or \`npx serve\`
+            - Or use VS Code's Live Server extension
+
+            **Note:** The preview uses the GitHub Pages URL (\`https://eclipse-volttron.github.io/\`) as the base URL. Links will work correctly when viewing locally.
+
+            ### Build Details:
+            - **PR:** #${prNumber}
+            - **Commit:** ${context.payload.pull_request.head.sha.substring(0, 7)}
+            - **Artifact:** pr-preview-${prNumber}
+            `;
+
+            github.rest.issues.createComment({
+              owner: repo.owner,
+              repo: repo.repo,
+              issue_number: prNumber,
+              body: comment
+            });

.gitignore

@@ -1 +1,4 @@
-*:Zone.Identifier
+*:Zone.Identifier
+public/
+resources/_gen/
+.hugo_build.lock

DEPLOYMENT.md

@@ -0,0 +1,107 @@
+# Deployment Guide
+
+## Overview
+This site is automatically deployed to https://volttron.org via GitHub Pages when changes are pushed to the `main` branch.
+
+## Build Process
+
+### GitHub Actions Workflows
+
+#### Production Deployment (`.github/workflows/hugo.yaml`)
+The production deployment workflow:
+1. Installs Hugo Extended 0.126.0 and Dart Sass
+2. Checks out the repository with submodules (to get the theme)
+3. Builds the site using `hugo --gc --minify` in production mode
+4. Deploys to GitHub Pages with the custom domain
+
+**Triggers:** Pushes to `main` branch
+
+#### PR Preview Build (`.github/workflows/pr-preview.yaml`)
+The PR preview workflow:
+1. Builds the site for pull requests before merging
+2. Creates a downloadable artifact with the built site
+3. Posts a comment on the PR with preview instructions
+4. Allows reviewers to test changes before merging to production
+
+**Triggers:** Pull requests targeting `main` branch
+
+**How to preview:**
+1. Go to the PR's "Checks" tab
+2. Click on "PR Preview Build" workflow run
+3. Download the artifact named `pr-preview-{PR-number}`
+4. Extract and open `index.html` in a browser, or use a local web server
+
+### Local Development
+
+#### Development Server (with live reload)
+```bash
+# Initialize theme submodule (first time only)
+git submodule update --init --recursive
+
+# Start development server
+hugo serve
+```
+Visit http://localhost:1313 to preview changes.
+
+**⚠️ IMPORTANT:** Never commit the `public/` directory that's generated by `hugo serve`! It contains localhost URLs and development scripts.
+
+#### Production Build (for testing)
+```bash
+# Build exactly as GitHub Actions does
+hugo --gc --minify
+
+# The output will be in the public/ directory
+# Verify it looks correct, then delete it (it should not be committed)
+rm -rf public/
+```
+
+## Important Files
+
+### Configuration
+- `hugo.toml` - Main Hugo configuration with baseURL
+- `config/_default/config.toml` - Extended configuration including languages
+- Both must have `baseURL = "https://volttron.org/"`
+
+### Deployment Files
+- `static/CNAME` - Contains "volttron.org" for custom domain
+- `static/.nojekyll` - Tells GitHub Pages not to use Jekyll
+- Files in `static/` are copied to the root of `public/` during build
+
+### Ignored Directories
+The following directories are **build artifacts** and should NEVER be committed:
+- `public/` - Generated site output
+- `resources/` - Hugo cache files
+- `.hugo_build.lock` - Hugo lock file
+
+These are listed in `.gitignore` to prevent accidental commits.
+
+## Troubleshooting
+
+### Site shows localhost URLs
+- Cause: The `public/` directory was built with `hugo serve` instead of `hugo`
+- Fix: Delete the `public/` directory and let GitHub Actions rebuild it
+
+### Theme not found error
+- Cause: The theme submodule wasn't initialized
+- Fix: Run `git submodule update --init --recursive`
+
+### Wrong domain in deployed site
+- Cause: CNAME file missing or in wrong location
+- Fix: Ensure `static/CNAME` exists and contains "volttron.org"
+
+## Deployment Checklist
+
+Before merging to `main`:
+- [ ] Verify `hugo --gc --minify` builds successfully
+- [ ] Check that `public/` and `resources/` are not being committed
+- [ ] Confirm baseURL in both config files is "https://volttron.org/"
+- [ ] Ensure `static/CNAME` exists with correct domain
+- [ ] Test that theme submodule is configured correctly
+- [ ] Review the PR preview build artifact to verify the site looks correct
+
+## Security Notes
+
+- The site uses HTTPS and is served via GitHub Pages
+- Custom domain is configured via CNAME
+- All builds are done in GitHub Actions with a clean environment
+- No sensitive data should be committed to the repository

README.md

@@ -1,16 +1,28 @@
 ## getting started
 Prerequisites:
-install windows terminal (I use ubuntu)
-install Git, command: $sudo apt install git-all
+- install windows terminal (I use ubuntu)
+- install Git, command: `sudo apt install git-all`
 
-installing hugo:
-install hugo, command: $sudo apt install hugo
-link for more info https://gohugo.io/installation/linux/#snap
+### Installing Hugo:
+Install hugo, command: `sudo apt install hugo`
+Link for more info: https://gohugo.io/installation/linux/#snap
 
- using hugo:
- enter the folder with the website
- run the command $hugo serve
- a link should appear to open the local web link
+### Using Hugo:
+
+#### For Local Development:
+1. Enter the folder with the website
+2. Initialize the theme submodule (first time only): `git submodule update --init --recursive`
+3. Run the command `hugo serve`
+4. A link should appear to open the local web link (typically http://localhost:1313)
+
+**Important:** The `hugo serve` command is for development only! It includes live reload and uses localhost URLs.
+
+#### For Production Build:
+To build the site for production (as done by GitHub Actions):
+1. Run `hugo --gc --minify`
+2. The production-ready site will be generated in the `public/` directory
+
+**Note:** The `public/` and `resources/` directories should NEVER be committed to git. They are build artifacts that are automatically generated during deployment by GitHub Actions.
 
  ## making changes
  Sidebar edits:

config/_default/config.toml

@@ -1,5 +1,4 @@
-baseURL = "https://example.org/"
-relativeURL = "true"
+baseURL = "https://volttron.org/"
 languageCode = "en-us"
 
 

hugo.toml

@@ -1,4 +1,4 @@
-baseURL = 'https://eclipse-volttron.github.io/'
+baseURL = 'https://volttron.org/'
 languageCode = 'en-us'
 title = 'VOLTTRON'
 theme = 'arcana'