[#111] Add development environment setup with direnv and Act Runner s…

.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+  "image": "mcr.microsoft.com/devcontainers/universal:2",
+  "features": {
+    "ghcr.io/devcontainers/features/nix:1": {
+      "multiUser": false,
+      "extraNixConfig": "experimental-features = nix-command flakes",
+      "version": "latest"
+    },
+    "ghcr.io/devcontainers-extra/features/direnv:1": {
+      "version": "latest"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "mkhl.direnv",
+        "jnoortheen.nix-ide"
+      ]
+    }
+  },
+  "postStartCommand": "echo 'eval \"$(direnv hook bash)\"' >> ~/.bashrc"
+}

.envrc

@@ -0,0 +1,11 @@
+# Load the development environment from flake.nix
+use flake
+
+# Uncomment the following line if you want to allow the use of unfree packages
+# export NIXPKGS_ALLOW_UNFREE=1
+
+# Uncomment if you need to specify a specific profile
+# export NIXOS_OZONE_WL=1
+
+# Print a message when the environment is loaded
+echo "DocumentationUI development environment activated via direnv"

.github/ACT_RUNNER_README.md

@@ -0,0 +1,67 @@
+# Act Runner Test for Antora UI Default
+
+This directory contains GitHub Actions workflow files that can be tested locally using [Act Runner](https://github.com/nektos/act).
+
+## What is Act Runner?
+
+Act Runner (nektos/act) is a tool that allows you to run GitHub Actions workflows locally. It uses Docker to run the workflows in an environment similar to GitHub Actions.
+
+## Prerequisites
+
+- [Docker](https://www.docker.com/) installed and running
+- [Act Runner](https://github.com/nektos/act) installed
+
+### Installing Act Runner
+
+#### On macOS (using Homebrew):
+```bash
+brew install act
+```
+
+#### On Linux:
+```bash
+curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+```
+
+#### On Windows (using Chocolatey):
+```bash
+choco install act-cli
+```
+
+For other installation methods, see the [Act Runner documentation](https://github.com/nektos/act#installation).
+
+## Running the Tests
+
+We've provided a script to run the tests:
+
+```bash
+./act-test.sh
+```
+
+This script will:
+1. Check if Act Runner is installed
+2. Run the GitHub Actions workflow defined in `.github/workflows/ci.yml`
+3. Report the results
+
+Alternatively, you can run Act Runner directly:
+
+```bash
+act --workflows .github/workflows/ci.yml --job build
+```
+
+## Workflow Details
+
+The workflow in `ci.yml` tests:
+- Node.js compatibility (versions 10.x, 12.x, 14.x)
+- Dependency installation
+- Code linting
+- UI bundle building
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. Make sure Docker is running
+2. Check that you have sufficient disk space for Docker images
+3. Try running with verbose output: `act -v --workflows .github/workflows/ci.yml`
+4. For memory issues, you can limit the resources: `act --workflows .github/workflows/ci.yml --job build -P ubuntu-latest=node:14-slim`

.github/workflows/ci.yml

@@ -1,95 +1,43 @@
 name: CI
 
 on:
-    pull_request:
-      types: [opened, synchronize]
-    workflow_dispatch:
+  push:
+    branches: [ develop ]
+  pull_request:
+    branches: [ develop ]
+  workflow_dispatch:
 
 jobs:
-  setup:
+  build:
     runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - name: Cache NPM
-        uses: actions/cache@v2
-        with:
-          path: .cache/npm
-          key: ${{ runner.os }}-npm-cache
-      - name: Install Dependencies
-        run: npm install --quiet --no-progress --cache=.cache/npm
 
-  lint:
-    runs-on: ubuntu-latest
-    needs: setup
-    steps:
-      - uses: actions/checkout@v2
-      - name: Cache NPM
-        uses: actions/cache@v2
-        with:
-          path: .cache/npm
-          key: ${{ runner.os }}-npm-cache
-      - name: Install Dependencies
-        run: npm install --quiet --no-progress --cache=.cache/npm
-      - name: Lint
-        run: node_modules/.bin/gulp lint
+    strategy:
+      matrix:
+        node-version: [10.x, 12.x, 14.x]
 
-  bundle-stable:
-    runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/develop'
-    needs: setup
     steps:
-      - uses: actions/checkout@v2
-      - name: Cache NPM
-        uses: actions/cache@v2
-        with:
-          path: .cache/npm
-          key: ${{ runner.os }}-npm-cache
-      - name: Install Dependencies
-        run: npm install --quiet --no-progress --cache=.cache/npm
-      - name: Bundle
-        run: node_modules/.bin/gulp bundle
-      - name: Upload Artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: ui-bundle
-          path: build/ui-bundle.zip
+    - uses: actions/checkout@v2
 
-  bundle-dev:
-    runs-on: ubuntu-latest
-    if: github.ref != 'refs/heads/master' && github.ref != 'refs/heads/develop'
-    needs: setup
-    steps:
-      - uses: actions/checkout@v2
-      - name: Cache NPM
-        uses: actions/cache@v2
-        with:
-          path: .cache/npm
-          key: ${{ runner.os }}-npm-cache
-      - name: Install Dependencies
-        run: npm install --quiet --no-progress --cache=.cache/npm
-      - name: Bundle
-        run: node_modules/.bin/gulp bundle
-      - name: Upload Artifact
-        uses: actions/upload-artifact@v2
-        with:
-          name: ui-bundle
-          path: ui-bundle.zip
-          retention-days: 1
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v2
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
 
-  upload:
-    name: Create release and upload artifacts
-    needs:
-      - bundle-stable
-    runs-on: ubuntu-latest
-    steps:
-      - name: Download artifacts
-        uses: actions/download-artifact@v4
-      - name: Inspect directory after downloading artifacts
-        run: ls -alFR
-      - name: Create release and upload artifacts
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-            wget -q https://github.com/TheAssassin/pyuploadtool/releases/download/continuous/pyuploadtool-x86_64.AppImage
-            chmod +x pyuploadtool-x86_64.AppImage
-            ./pyuploadtool-x86_64.AppImage **/ui-bundle.zip
+    - name: Install dependencies
+      run: npm install
+
+    - name: Lint
+      run: npx gulp lint
+
+    - name: Run CSS Format Tests
+      run: node tests/css-format-test.js
+
+    - name: Build UI bundle
+      run: npx gulp bundle
+
+    - name: Upload UI bundle
+      uses: actions/upload-artifact@v2
+      with:
+        name: ui-bundle
+        path: build/ui-bundle.zip

.gitignore

@@ -1,3 +1,4 @@
 /build/
 /node_modules/
 /public/
+.direnv/

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+    "recommendations": [
+        "asciidoctor.asciidoctor-vscode"
+    ]
+}

README.adoc

@@ -206,6 +206,66 @@ If you need to include source maps in the bundle, you can do so by setting the `
 
 In this case, the bundle will include the source maps, which can be used for debugging your production site.
 
+== Testing with Act Runner
+
+This project includes GitHub Actions workflow files that can be tested locally using https://github.com/nektos/act[Act Runner].
+
+Act Runner allows you to run GitHub Actions workflows locally, which is useful for testing changes before pushing them to GitHub.
+
+=== Prerequisites
+
+To use Act Runner, you need:
+
+* https://www.docker.com/[Docker] installed and running
+* https://github.com/nektos/act[Act Runner] installed
+
+=== Running Tests
+
+There are multiple ways to run tests in this project:
+
+==== Using npm
+
+The simplest way to run tests is using npm:
+
+[source,bash]
+----
+npm test
+----
+
+This will run all tests in the `tests/` directory.
+
+==== Using Act Runner
+
+We've also provided a script to run the GitHub Actions workflow locally using Act Runner:
+
+[source,bash]
+----
+npm run test:act
+# or directly:
+./act-test.sh
+----
+
+This script will:
+
+. Check if Act Runner is installed
+. Run the GitHub Actions workflow defined in `.github/workflows/ci.yml`
+. Report the results
+
+For more detailed information about using Act Runner with this project, see the `.github/ACT_RUNNER_README.md` file.
+
+==== Running Individual Tests
+
+You can also run individual tests directly:
+
+[source,bash]
+----
+# Run CSS format tests
+node tests/css-format-test.js
+
+# Run all tests with the test runner
+tests/run-tests.sh
+----
+
 == Copyright and License
 
 Copyright (C) 2017-present OpenDevise Inc. and the Antora Project.

act-test.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+# Script to run GitHub Actions workflow locally using Act Runner
+# https://github.com/nektos/act
+
+# Check if act is installed
+if ! command -v act &> /dev/null; then
+    echo "Error: Act Runner is not installed."
+    echo "Please install it following the instructions at: https://github.com/nektos/act#installation"
+    exit 1
+fi
+
+echo "Running GitHub Actions workflow using Act Runner..."
+echo "=================================================="
+
+# Run the workflow with act
+# Using --workflows flag to specify the workflow file
+# Using --job build to run only the build job
+act --workflows .github/workflows/ci.yml --job build
+
+# Check the exit status
+if [ $? -eq 0 ]; then
+    echo "=================================================="
+    echo "✅ Workflow completed successfully!"
+else
+    echo "=================================================="
+    echo "❌ Workflow failed. Please check the output above for errors."
+    exit 1
+fi