tpl(starter): add minimal Tailwind starter template

templates/starter/.github/workflows/build.yml

@@ -0,0 +1,138 @@
+name: Build
+
+env:
+  NODE_VERSION: '20'
+
+on:
+  # Standalone trigger for PR validation
+  pull_request:
+    branches: ['main']
+  # Reusable workflow trigger - called by deploy.yml
+  workflow_call:
+    outputs:
+      artifact-id:
+        description: 'The ID of the uploaded artifact'
+        value: ${{ jobs.build.outputs.artifact-id }}
+  # Allow manual trigger for testing
+  workflow_dispatch:
+
+# Read-only permissions for security
+permissions:
+  contents: read
+
+# Prevent duplicate builds for the same PR
+concurrency:
+  group: build-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    if: github.repository_owner != 'HugoBlox'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      artifact-id: ${{ steps.upload.outputs.artifact-id }}
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v6
+      with:
+        # Fetch history for Hugo's .GitInfo and .Lastmod
+        fetch-depth: 0
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v6
+      with:
+        node-version: ${{ env.NODE_VERSION }}
+
+    - name: Setup pnpm
+      if: hashFiles('package.json') != ''
+      uses: pnpm/action-setup@v4
+
+    - name: Get Hugo Version
+      id: hugo-version
+      run: |
+        # Install pinned yq version for robust YAML parsing
+        YQ_VERSION="v4.44.1"
+        if ! wget -q --tries=3 --waitretry=1 -O /tmp/yq \
+          "https://github.com/mikefarah/yq/releases/download/${YQ_VERSION}/yq_linux_amd64"; then
+          echo "::error::Failed to download yq"
+          exit 1
+        fi
+        sudo mv /tmp/yq /usr/local/bin/yq
+        sudo chmod +x /usr/local/bin/yq
+
+        # Read hugo_version from hugoblox.yaml
+        VERSION=$(yq '.build.hugo_version // ""' hugoblox.yaml 2>/dev/null | grep -v '^null$' || true)
+
+        # Fallback to a known stable version if not specified
+        DEFAULT_VERSION="0.154.5"
+        VERSION=${VERSION:-$DEFAULT_VERSION}
+
+        # Validate version format (basic check)
+        if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+          echo "::warning::Invalid hugo_version format '$VERSION', using default $DEFAULT_VERSION"
+          VERSION="$DEFAULT_VERSION"
+        fi
+
+        echo "HUGO_VERSION=$VERSION" >> $GITHUB_ENV
+        echo "Using Hugo version: $VERSION"
+
+    - name: Install dependencies
+      run: |
+        # Install Tailwind CLI if package.json exists
+        if [ -f "package.json" ]; then
+          echo "Installing Tailwind dependencies..."
+          pnpm install --no-frozen-lockfile || npm install
+        fi
+
+    - name: Setup Hugo
+      uses: peaceiris/actions-hugo@v3
+      with:
+        hugo-version: ${{ env.HUGO_VERSION }}
+        extended: true
+
+    # Cache dependencies (Go modules, node_modules) - stable, rarely changes
+    - uses: actions/cache@v5
+      with:
+        path: |
+          /tmp/hugo_cache_runner/
+          node_modules/
+          modules/*/node_modules/
+        key: ${{ runner.os }}-hugo-deps-${{ hashFiles('**/go.mod', '**/package-lock.json',
+          '**/pnpm-lock.yaml') }}
+        restore-keys: |
+          ${{ runner.os }}-hugo-deps-
+
+    # Cache Hugo resources (processed images, CSS) - invalidates only when assets/config change
+    - uses: actions/cache@v5
+      with:
+        path: resources/
+        key: ${{ runner.os }}-hugo-resources-${{ hashFiles('assets/**/*', 'config/**/*',
+          'hugo.yaml', 'package.json') }}
+        restore-keys: |
+          ${{ runner.os }}-hugo-resources-
+
+    - name: Setup Pages
+      id: pages
+      uses: actions/configure-pages@v5
+
+    - name: Build with Hugo
+      env:
+        HUGO_ENVIRONMENT: production
+        HUGO_BLOX_LICENSE: ${{ secrets.HUGO_BLOX_LICENSE }}
+      run: |
+        echo "Hugo Cache Dir: $(hugo config | grep cachedir)"
+        hugo --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
+
+    - name: Generate Pagefind search index (if applicable)
+      run: |
+        # Check if site uses Pagefind search
+        if [ -f "package.json" ] && grep -q "pagefind" package.json; then
+          pnpm run pagefind || npx pagefind --site "public" 2>/dev/null || true
+        fi
+
+    - name: Upload artifact
+      id: upload
+      uses: actions/upload-pages-artifact@v4
+      with:
+        path: ./public

templates/starter/.github/workflows/deploy.yml

@@ -0,0 +1,83 @@
+name: Deploy website to GitHub Pages
+
+on:
+  # Trigger the workflow every time you push to the `main` branch
+  push:
+    branches: ['main']
+  # Allows you to run this workflow manually from the Actions tab on GitHub
+  workflow_dispatch:
+
+# Provide permission to clone the repo and deploy it to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+
+jobs:
+  # Check deployment configuration
+  config:
+    if: github.repository_owner != 'HugoBlox'
+    runs-on: ubuntu-latest
+    outputs:
+      deploy-host: ${{ steps.check.outputs.host }}
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v6
+      with:
+        sparse-checkout: hugoblox.yaml
+        sparse-checkout-cone-mode: false
+
+    - name: Check deploy host
+      id: check
+      run: |
+        # Install pinned yq version for robust YAML parsing
+        YQ_VERSION="v4.44.1"
+        if ! wget -q --tries=3 --waitretry=1 -O /tmp/yq \
+          "https://github.com/mikefarah/yq/releases/download/${YQ_VERSION}/yq_linux_amd64"; then
+          echo "::error::Failed to download yq"
+          exit 1
+        fi
+        sudo mv /tmp/yq /usr/local/bin/yq
+        sudo chmod +x /usr/local/bin/yq
+
+        # Read deploy.host from hugoblox.yaml, default to github-pages
+        HOST=$(yq '.deploy.host // ""' hugoblox.yaml 2>/dev/null | grep -v '^null$' || true)
+        HOST=${HOST:-github-pages}
+
+        # Validate known hosts
+        if [[ ! "$HOST" =~ ^(github-pages|netlify|vercel|cloudflare|none)$ ]]; then
+          echo "::warning::Unknown deploy host '$HOST', defaulting to github-pages"
+          HOST="github-pages"
+        fi
+
+        echo "host=$HOST" >> $GITHUB_OUTPUT
+        echo "Deployment target: $HOST"
+
+  # Build website using reusable workflow (always runs for CI)
+  build:
+    needs: config
+    if: github.repository_owner != 'HugoBlox'
+    uses: ./.github/workflows/build.yml
+    secrets: inherit
+
+  # Deploy website to GitHub Pages hosting (only if configured)
+  deploy:
+    needs: [config, build]
+    if: needs.config.outputs.deploy-host == 'github-pages'
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

templates/starter/.github/workflows/upgrade.yml

@@ -0,0 +1,98 @@
+name: Upgrade HugoBlox
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_type:
+        description: 'Upgrade to version'
+        required: true
+        default: 'Stable'
+        type: choice
+        options:
+        - Stable
+        - Beta (Preview)
+  schedule:
+    # Run at 05:00 on Monday
+    - cron: '0 5 * * 1'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+# Prevent duplicate upgrade runs
+concurrency:
+  group: upgrade-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  upgrade:
+    name: Upgrade
+    if: github.repository_owner != 'HugoBlox'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          package_json_path: ./package.json
+          run_install: false
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.23'
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v3
+        with:
+          hugo-version: 'latest'
+          extended: true
+
+      - name: Run Upgrade CLI
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Use manual input or default to stable for scheduled runs
+          VERSION_TYPE: ${{ inputs.version_type || 'Stable' }}
+        run: |
+          FLAGS="--yes --ci"
+
+          if [ "$VERSION_TYPE" == "Beta (Preview)" ]; then
+            FLAGS="$FLAGS --canary"
+          fi
+
+          echo "Running upgrade with flags: $FLAGS"
+          pnpm dlx hugoblox@latest upgrade $FLAGS
+
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "chore(deps): upgrade hugoblox modules"
+          title: "Upgrade HugoBlox Modules"
+          body: |
+            This PR upgrades the [HugoBlox](https://hugoblox.com) modules to the latest version.
+
+            **Changes:**
+            - Updated Hugo Modules (go.mod/go.sum)
+            - Applied automatic migrations (if any)
+
+            **Verification:**
+            - [ ] Check the Deploy Preview to ensure everything looks correct.
+            - [ ] Merge this PR to apply the updates.
+          branch: "chore/upgrade-hugoblox-${{ github.run_id }}"
+          delete-branch: true
+          base: main
+          labels: |
+            dependencies
+            automated-pr