Update ci.yml

- Added docker hub to the login.
- Removed some cache BS.

.dockerignore

@@ -0,0 +1,68 @@
+# Git
+.git
+.gitignore
+.gitattributes
+
+# CI/CD
+.github
+.codecov.yml
+
+# Documentation
+README.md
+*.md
+docs/
+
+# Build artifacts
+build/
+dist/
+*.exe
+*.tar.gz
+*.zip
+
+# Test files
+*_test.go
+test_*.go
+test/
+coverage.out
+coverage.html
+*.log
+
+# Development
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS specific
+.DS_Store
+Thumbs.db
+
+# Output and temporary files
+output/
+tmp/
+temp/
+
+# Node.js (if any)
+node_modules/
+npm-debug.log
+yarn-error.log
+
+# Python (if any)
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+
+# Scripts (build scripts not needed in container)
+scripts/
+
+# Sample files
+articulate-sample.json
+test_input.json
+
+# License
+LICENSE

.github/dependabot.yml

@@ -11,11 +11,57 @@ updates:
     open-pull-requests-limit: 10
     labels:
       - 'dependencies'
-      - 'github-actions'
+      - 'dependencies/github-actions'
     commit-message:
       prefix: 'ci'
       include: 'scope'
 
+  # Check for updates to Docker
+  - package-ecosystem: 'docker'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+      day: 'monday'
+      time: '07:00'
+      timezone: 'Europe/Amsterdam'
+    open-pull-requests-limit: 10
+    labels:
+      - 'dependencies'
+      - 'dependencies/docker'
+    commit-message:
+      prefix: 'docker'
+      include: 'scope'
+    groups:
+      docker-images:
+        patterns:
+          - '*'
+        update-types:
+          - 'minor'
+          - 'patch'
+
+  # Check for updates to Docker Compose
+  - package-ecosystem: 'docker-compose'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+      day: 'monday'
+      time: '07:00'
+      timezone: 'Europe/Amsterdam'
+    open-pull-requests-limit: 10
+    labels:
+      - 'dependencies'
+      - 'dependencies/docker-compose'
+    commit-message:
+      prefix: 'docker'
+      include: 'scope'
+    groups:
+      docker-compose:
+        patterns:
+          - '*'
+        update-types:
+          - 'minor'
+          - 'patch'
+
   # Check for updates to Go modules
   - package-ecosystem: 'gomod'
     directory: '/'
@@ -27,7 +73,7 @@ updates:
     open-pull-requests-limit: 10
     labels:
       - 'dependencies'
-      - 'go'
+      - 'dependencies/go'
     commit-message:
       prefix: 'deps'
       include: 'scope'

.github/workflows/ci.yml

@@ -2,11 +2,19 @@ name: CI
 
 on:
   push:
-    branches: [ "master", "develop" ]
+    branches: ['master', 'develop']
     tags:
-      - "v*.*.*"
+      - 'v*.*.*'
   pull_request:
-    branches: [ "master", "develop" ]
+    branches: ['master', 'develop', 'feature/*']
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   test:
@@ -30,13 +38,45 @@ jobs:
         with:
           go-version: ${{ matrix.go }}
           check-latest: true
-          cache-dependency-path: "**/*.sum"
 
-      - name: Download dependencies
+      - name: Download dependencies with retry
-        run: go mod download && echo "Download successful" || go mod tidy && echo "Tidy successful" || return 1
+        run: |
+          set -e
+          echo "Downloading Go dependencies..."
 
-      - name: Verify dependencies
+          # Function to download with retry
-        run: go mod verify
+          download_with_retry() {
+            local attempt=1
+            local max_attempts=3
+
+            while [ $attempt -le $max_attempts ]; do
+              echo "Attempt $attempt of $max_attempts"
+
+              if go mod download; then
+                echo "Download successful on attempt $attempt"
+                return 0
+              else
+                echo "Download failed on attempt $attempt"
+                if [ $attempt -lt $max_attempts ]; then
+                  echo "Cleaning cache and retrying..."
+                  go clean -modcache
+                  go clean -cache
+                  sleep 2
+                fi
+                attempt=$((attempt + 1))
+              fi
+            done
+
+            echo "All download attempts failed"
+            return 1
+          }
+
+          # Try download with retry logic
+          download_with_retry
+
+          echo "Verifying module dependencies..."
+          go mod verify
+          echo "Dependencies verified successfully"
 
       - name: Build
         run: go build -v ./...
@@ -49,17 +89,17 @@ jobs:
           echo "- **OS:** ubuntu-latest" >> $GITHUB_STEP_SUMMARY
           echo "- **Timestamp:** $(date -u)" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          
+
           echo "Running tests with coverage..."
           go test -v -race -coverprofile=coverage.out ./... 2>&1 | tee test-output.log
-          
+
           # Extract test results for summary
           TEST_STATUS=$?
           TOTAL_TESTS=$(grep -c "=== RUN" test-output.log || echo "0")
           PASSED_TESTS=$(grep -c "--- PASS:" test-output.log || echo "0")
           FAILED_TESTS=$(grep -c "--- FAIL:" test-output.log || echo "0")
           SKIPPED_TESTS=$(grep -c "--- SKIP:" test-output.log || echo "0")
-          
+
           # Generate test summary
           echo "## 🧪 Test Results (Go ${{ matrix.go }})" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
@@ -71,13 +111,13 @@ jobs:
           echo "| Skipped | ⏭️ $SKIPPED_TESTS |" >> $GITHUB_STEP_SUMMARY
           echo "| Status | $([ $TEST_STATUS -eq 0 ] && echo "✅ PASSED" || echo "❌ FAILED") |" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          
+
           # Add package breakdown
           echo "### 📦 Package Test Results" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "| Package | Status |" >> $GITHUB_STEP_SUMMARY
           echo "|---------|--------|" >> $GITHUB_STEP_SUMMARY
-          
+
           # Extract package results
           grep "^ok\|^FAIL" test-output.log | while read line; do
             if [[ $line == ok* ]]; then
@@ -88,9 +128,9 @@ jobs:
               echo "| $pkg | ❌ FAIL |" >> $GITHUB_STEP_SUMMARY
             fi
           done
-          
+
           echo "" >> $GITHUB_STEP_SUMMARY
-          
+
           # Add detailed results if tests failed
           if [ $TEST_STATUS -ne 0 ]; then
             echo "### ❌ Failed Tests Details" >> $GITHUB_STEP_SUMMARY
@@ -100,13 +140,13 @@ jobs:
             echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
           fi
-          
+
           # Set outputs for other steps
           echo "test-status=$TEST_STATUS" >> $GITHUB_OUTPUT
           echo "total-tests=$TOTAL_TESTS" >> $GITHUB_OUTPUT
           echo "passed-tests=$PASSED_TESTS" >> $GITHUB_OUTPUT
           echo "failed-tests=$FAILED_TESTS" >> $GITHUB_OUTPUT
-          
+
           # Exit with the original test status
           exit $TEST_STATUS
 
@@ -116,26 +156,55 @@ jobs:
           if [ -f coverage.out ]; then
             go tool cover -html=coverage.out -o coverage.html
             COVERAGE=$(go tool cover -func=coverage.out | grep total | awk '{print $3}')
-            
+
             echo "## 📊 Code Coverage (Go ${{ matrix.go }})" >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "**Total Coverage: $COVERAGE**" >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
-            
+
             # Add coverage by package
-            echo "### 📋 Coverage by Package" >> $GITHUB_STEP_SUMMARY
+            echo "<details>" >> $GITHUB_STEP_SUMMARY
+            echo "<summary>Click to expand 📋 Coverage by Package details</summary>" >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "| Package | Coverage |" >> $GITHUB_STEP_SUMMARY
             echo "|---------|----------|" >> $GITHUB_STEP_SUMMARY
-            
+
+            # Create temporary file for package coverage aggregation
+            temp_coverage=$(mktemp)
+
+            # Extract package-level coverage data
             go tool cover -func=coverage.out | grep -v total | while read line; do
               if [[ $line == *".go:"* ]]; then
-                pkg=$(echo $line | awk '{print $1}' | cut -d'/' -f1-3)
+                # Extract package path from file path (everything before the filename)
-                coverage=$(echo $line | awk '{print $3}')
+                filepath=$(echo "$line" | awk '{print $1}')
-                echo "| $pkg | $coverage |" >> $GITHUB_STEP_SUMMARY
+                pkg_path=$(dirname "$filepath" | sed 's|github.com/kjanat/articulate-parser/||' | sed 's|^\./||')
+                coverage=$(echo "$line" | awk '{print $3}' | sed 's/%//')
+
+                # Use root package if no subdirectory
+                if [[ "$pkg_path" == "." || "$pkg_path" == "" ]]; then
+                  pkg_path="root"
+                fi
+
+                echo "$pkg_path $coverage" >> "$temp_coverage"
               fi
-            done | sort -u
+            done
-            
+
+            # Aggregate coverage by package (average)
+            awk '{
+              packages[$1] += $2;
+              counts[$1]++
+            }
+            END {
+              for (pkg in packages) {
+                avg = packages[pkg] / counts[pkg]
+                printf "| %s | %.1f%% |\n", pkg, avg
+              }
+            }' $temp_coverage | sort >> $GITHUB_STEP_SUMMARY
+
+            rm -f $temp_coverage
+
+            echo "</details>" >> $GITHUB_STEP_SUMMARY
+
             echo "" >> $GITHUB_STEP_SUMMARY
           else
             echo "## ⚠️ Coverage Report" >> $GITHUB_STEP_SUMMARY
@@ -158,10 +227,10 @@ jobs:
         run: |
           echo "## 🔍 Static Analysis (Go ${{ matrix.go }})" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          
+
           VET_OUTPUT=$(go vet ./... 2>&1 || echo "")
           VET_STATUS=$?
-          
+
           if [ $VET_STATUS -eq 0 ]; then
             echo "✅ **go vet:** No issues found" >> $GITHUB_STEP_SUMMARY
           else
@@ -172,13 +241,13 @@ jobs:
             echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
           fi
           echo "" >> $GITHUB_STEP_SUMMARY
-          
+
           exit $VET_STATUS
 
       - name: Run go fmt
         run: |
           FMT_OUTPUT=$(gofmt -s -l . 2>&1 || echo "")
-          
+
           if [ -z "$FMT_OUTPUT" ]; then
             echo "✅ **go fmt:** All files properly formatted" >> $GITHUB_STEP_SUMMARY
           else
@@ -220,6 +289,53 @@ jobs:
           flags: Go ${{ matrix.go }}
           token: ${{ secrets.CODECOV_TOKEN }}
 
+  docker-test:
+    name: Docker Build Test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Capture build date
+        run: echo "BUILD_TIME=$(git log -1 --format=%cd --date=iso-strict)" >> $GITHUB_ENV
+
+      - name: Build Docker image (test)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: false
+          load: true
+          tags: test:latest
+          build-args: |
+            VERSION=test
+            BUILD_TIME=${{ env.BUILD_TIME }}
+            GIT_COMMIT=${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Test Docker image
+        run: |
+          echo "## 🧪 Docker Image Tests" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          # Test that the image runs and shows help
+          echo "**Testing help command:**" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          docker run --rm test:latest --help >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          # Test image size
+          IMAGE_SIZE=$(docker image inspect test:latest --format='{{.Size}}' | numfmt --to=iec-i --suffix=B)
+          echo "**Image size:** $IMAGE_SIZE" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
   dependency-review:
     name: Dependency Review
     runs-on: ubuntu-latest
@@ -242,7 +358,7 @@ jobs:
     if: github.ref_type == 'tag'
     permissions:
       contents: write
-    needs: [ "test" ]
+    needs: ['test']
     steps:
       - uses: actions/checkout@v4
         with:
@@ -258,14 +374,14 @@ jobs:
         run: |
           echo "## 🚀 Release Tests" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          
+
           go test -v ./... 2>&1 | tee release-test-output.log
           TEST_STATUS=$?
-          
+
           TOTAL_TESTS=$(grep -c "=== RUN" release-test-output.log || echo "0")
           PASSED_TESTS=$(grep -c "--- PASS:" release-test-output.log || echo "0")
           FAILED_TESTS=$(grep -c "--- FAIL:" release-test-output.log || echo "0")
-          
+
           echo "| Metric | Value |" >> $GITHUB_STEP_SUMMARY
           echo "|--------|-------|" >> $GITHUB_STEP_SUMMARY
           echo "| Total Tests | $TOTAL_TESTS |" >> $GITHUB_STEP_SUMMARY
@@ -273,7 +389,7 @@ jobs:
           echo "| Failed | ❌ $FAILED_TESTS |" >> $GITHUB_STEP_SUMMARY
           echo "| Status | $([ $TEST_STATUS -eq 0 ] && echo "✅ PASSED" || echo "❌ FAILED") |" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          
+
           exit $TEST_STATUS
 
       - name: Install UPX
@@ -285,9 +401,9 @@ jobs:
         run: |
           echo "## 🔨 Build Process" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          
+
-          # Set the build time environment variable
+          # Set the build time environment variable using git commit timestamp
-          BUILD_TIME=$(date -u +'%Y-%m-%dT%H:%M:%SZ')
+          BUILD_TIME=$(git log -1 --format=%cd --date=iso-strict)
 
           # Add run permissions to the build script
           chmod +x ./scripts/build.sh
@@ -310,29 +426,34 @@ jobs:
         run: |
           echo "## 📦 Binary Compression" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          
+
           echo "Compressing binaries with UPX..."
           cd build/
-          
+
           # Get original sizes
           echo "**Original sizes:**" >> $GITHUB_STEP_SUMMARY
           echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
           ls -lah >> $GITHUB_STEP_SUMMARY
           echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          
+
           # Compress all binaries except Darwin (macOS) binaries as UPX doesn't work well with recent macOS versions
           for binary in articulate-parser-*; do
-            if [[ "$binary" == *"darwin"* ]]; then
+            echo "Compressing $binary..."
-              echo "Skipping UPX compression for $binary (macOS compatibility)"
+            upx --best "$binary" || {
-            else
+              echo "Warning: UPX compression failed for $binary, keeping original"
-              echo "Compressing $binary..."
+            }
-              upx --best --lzma "$binary" || {
+
-                echo "Warning: UPX compression failed for $binary, keeping original"
+            # if [[ "$binary" == *"darwin"* ]]; then
-              }
+            #   echo "Skipping UPX compression for $binary (macOS compatibility)"
-            fi
+            # else
+            #   echo "Compressing $binary..."
+            #   upx --best "$binary" || { # removed `--lzma`
+            #     echo "Warning: UPX compression failed for $binary, keeping original"
+            #   }
+            # fi
           done
-          
+
           echo "**Final sizes:**" >> $GITHUB_STEP_SUMMARY
           echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
           ls -lah >> $GITHUB_STEP_SUMMARY
@@ -356,6 +477,129 @@ jobs:
           files: build/*
           generate_release_notes: true
           draft: false
+          # Mark v0.x.x releases as prerelease (pre-1.0 versions are considered unstable)
           prerelease: ${{ startsWith(github.ref, 'refs/tags/v0.') }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  docker:
+    name: Docker Build & Push
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    needs: ['test']
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/tags/') || startsWith(github.ref, 'refs/heads/feature/docker'))
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ${{ env.IMAGE_NAME }}
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest,enable={{is_default_branch}}
+          labels: |
+            org.opencontainers.image.title=Articulate Parser
+            org.opencontainers.image.description=A powerful CLI tool to parse Articulate Rise courses and export them to multiple formats including Markdown HTML and DOCX. Supports media extraction content cleaning and batch processing for educational content conversion.
+            org.opencontainers.image.vendor=kjanat
+            org.opencontainers.image.licenses=MIT
+            org.opencontainers.image.url=https://github.com/${{ github.repository }}
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            org.opencontainers.image.documentation=https://github.com/${{ github.repository }}/blob/master/DOCKER.md
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          # Multi-architecture build - Docker automatically provides TARGETOS, TARGETARCH, etc.
+          # Based on Go's supported platforms from 'go tool dist list'
+          platforms: |
+            linux/amd64
+            linux/arm64
+            linux/arm/v7
+            linux/386
+            linux/ppc64le
+            linux/s390x
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          annotations: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            VERSION=${{ github.ref_type == 'tag' && github.ref_name || github.sha }}
+            BUILD_TIME=${{ github.event.head_commit.timestamp }}
+            GIT_COMMIT=${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=A powerful CLI tool to parse Articulate Rise courses and export them to multiple formats including Markdown HTML and DOCX. Supports media extraction content cleaning and batch processing for educational content conversion.
+          sbom: true
+          provenance: true
+
+      - name: Generate Docker summary
+        run: |
+          echo "## 🐳 Docker Build Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Image:** \`ghcr.io/${{ github.repository }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Tags built:**" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "${{ steps.meta.outputs.tags }}" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Features:**" >> $GITHUB_STEP_SUMMARY
+          echo "- **Platforms:** linux/amd64, linux/arm64, linux/arm/v7, linux/386, linux/ppc64le, linux/s390x" >> $GITHUB_STEP_SUMMARY
+          echo "- **Architecture optimization:** ✅ Native compilation for each platform" >> $GITHUB_STEP_SUMMARY
+          echo "- **Multi-arch image description:** ✅ Enabled" >> $GITHUB_STEP_SUMMARY
+          echo "- **SBOM (Software Bill of Materials):** ✅ Generated" >> $GITHUB_STEP_SUMMARY
+          echo "- **Provenance attestation:** ✅ Generated" >> $GITHUB_STEP_SUMMARY
+          echo "- **Security scanning:** Ready for vulnerability analysis" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Usage:**" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "# Pull the image" >> $GITHUB_STEP_SUMMARY
+          echo "docker pull ghcr.io/${{ github.repository }}:latest" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "# Run with help" >> $GITHUB_STEP_SUMMARY
+          echo "docker run --rm ghcr.io/${{ github.repository }}:latest --help" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "# Process a local file (mount current directory)" >> $GITHUB_STEP_SUMMARY
+          echo "docker run --rm -v \$(pwd):/workspace ghcr.io/${{ github.repository }}:latest /workspace/input.json markdown /workspace/output.md" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+  # Security and quality analysis workflows
+  codeql-analysis:
+    name: CodeQL Analysis
+    uses: ./.github/workflows/codeql.yml
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read

.github/workflows/codeql.yml

@@ -1,100 +1,104 @@
-# For most projects, this workflow file will not need changing; you simply need
+# For most projects, this workflow file will not need changing; you simply need
-# to commit it to your repository.
+# to commit it to your repository.
-#
+#
-# You may wish to alter this file to override the set of languages analyzed,
+# You may wish to alter this file to override the set of languages analyzed,
-# or to provide custom queries or build logic.
+# or to provide custom queries or build logic.
-#
+#
-# ******** NOTE ********
+# ******** NOTE ********
-# We have attempted to detect the languages in your repository. Please check
+# We have attempted to detect the languages in your repository. Please check
-# the `language` matrix defined below to confirm you have the correct set of
+# the `language` matrix defined below to confirm you have the correct set of
-# supported CodeQL languages.
+# supported CodeQL languages.
-#
+#
-name: "CodeQL"
+name: "CodeQL"
-
+
-on:
+# This workflow is configured to be called by other workflows for more controlled execution
-  push:
+# This allows integration with the main CI pipeline and avoids redundant runs
-    branches: [ "master" ]
+# To enable automatic execution, uncomment the triggers below:
-  pull_request:
+on:
-    branches: [ "master" ]
+  workflow_call:
-  schedule:
+  schedule:
-    - cron: '44 16 * * 6'
+    - cron: '44 16 * * 6'
-
+  # push:
-jobs:
+  #   branches: [ "master" ]
-  analyze:
+  # pull_request:
-    name: Analyze (${{ matrix.language }})
+  #   branches: [ "master" ]
-    # Runner size impacts CodeQL analysis time. To learn more, please see:
+
-    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+jobs:
-    #   - https://gh.io/supported-runners-and-hardware-resources
+  analyze:
-    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    name: Analyze (${{ matrix.language }})
-    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
-    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
-    permissions:
+    #   - https://gh.io/supported-runners-and-hardware-resources
-      # required for all workflows
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
-      security-events: write
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
-
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
-      # required to fetch internal or private CodeQL packs
+    permissions:
-      packages: read
+      # required for all workflows
-
+      security-events: write
-      # only required for workflows in private repositories
+
-      actions: read
+      # required to fetch internal or private CodeQL packs
-      contents: read
+      packages: read
-
+
-    strategy:
+      # only required for workflows in private repositories
-      fail-fast: false
+      actions: read
-      matrix:
+      contents: read
-        include:
+
-        - language: actions
+    strategy:
-          build-mode: none
+      fail-fast: false
-        - language: go
+      matrix:
-          build-mode: autobuild
+        include:
-        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'swift'
+        - language: actions
-        # Use `c-cpp` to analyze code written in C, C++ or both
+          build-mode: none
-        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        - language: go
-        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+          build-mode: autobuild
-        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'swift'
-        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # Use `c-cpp` to analyze code written in C, C++ or both
-        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
-        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
-    steps:
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
-    - name: Checkout repository
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
-      uses: actions/checkout@v4
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
-
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
-    # Add any setup steps before running the `github/codeql-action/init` action.
+    steps:
-    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    - name: Checkout repository
-    # or others). This is typically only required for manual builds.
+      uses: actions/checkout@v4
-    # - name: Setup runtime (example)
+
-    #   uses: actions/setup-example@v1
+    # Add any setup steps before running the `github/codeql-action/init` action.
-
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
-    # Initializes the CodeQL tools for scanning.
+    # or others). This is typically only required for manual builds.
-    - name: Initialize CodeQL
+    # - name: Setup runtime (example)
-      uses: github/codeql-action/init@v3
+    #   uses: actions/setup-example@v1
-      with:
+
-        languages: ${{ matrix.language }}
+    # Initializes the CodeQL tools for scanning.
-        build-mode: ${{ matrix.build-mode }}
+    - name: Initialize CodeQL
-        # If you wish to specify custom queries, you can do so here or in a config file.
+      uses: github/codeql-action/init@v3
-        # By default, queries listed here will override any specified in a config file.
+      with:
-        # Prefix the list here with "+" to use these queries and those in the config file.
+        languages: ${{ matrix.language }}
-
+        build-mode: ${{ matrix.build-mode }}
-        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # If you wish to specify custom queries, you can do so here or in a config file.
-        # queries: security-extended,security-and-quality
+        # By default, queries listed here will override any specified in a config file.
-
+        # Prefix the list here with "+" to use these queries and those in the config file.
-    # If the analyze step fails for one of the languages you are analyzing with
+
-    # "We were unable to automatically build your code", modify the matrix above
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
-    # to set the build mode to "manual" for that language. Then modify this step
+        # queries: security-extended,security-and-quality
-    # to build your code.
+
-    # ℹ️ Command-line programs to run using the OS shell.
+    # If the analyze step fails for one of the languages you are analyzing with
-    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    # "We were unable to automatically build your code", modify the matrix above
-    - if: matrix.build-mode == 'manual'
+    # to set the build mode to "manual" for that language. Then modify this step
-      shell: bash
+    # to build your code.
-      run: |
+    # ℹ️ Command-line programs to run using the OS shell.
-        echo 'If you are using a "manual" build mode for one or more of the' \
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
-          'languages you are analyzing, replace this with the commands to build' \
+    - if: matrix.build-mode == 'manual'
-          'your code, for example:'
+      shell: bash
-        echo '  make bootstrap'
+      run: |
-        echo '  make release'
+        echo 'If you are using a "manual" build mode for one or more of the' \
-        exit 1
+          'languages you are analyzing, replace this with the commands to build' \
-
+          'your code, for example:'
-    - name: Perform CodeQL Analysis
+        echo '  make bootstrap'
-      uses: github/codeql-action/analyze@v3
+        echo '  make release'
-      with:
+        exit 1
-        category: "/language:${{matrix.language}}"
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

.github/workflows/dependency-review.yml

@@ -0,0 +1,25 @@
+name: Dependency Review
+
+# This workflow is designed to be called by other workflows rather than triggered automatically
+# This allows for more controlled execution and integration with other CI/CD processes
+# To enable automatic execution on pull requests, uncomment the line below:
+# on: [pull_request]
+on: [workflow_call]
+
+permissions:
+  contents: read
+  # Required to post security advisories
+  security-events: write
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout Repository'
+        uses: actions/checkout@v4
+
+      - name: 'Dependency Review'
+        uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: moderate
+          comment-summary-in-pr: always

.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Create Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
+          check-latest: true
+
+      - name: Run tests
+        run: go test -v ./...
+
+      - name: Install UPX
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y upx
+
+      - name: Build binaries
+        run: |
+          # Set the build time environment variable using git commit timestamp
+          BUILD_TIME=$(git log -1 --format=%cd --date=iso-strict)
+
+          # Add run permissions to the build script
+          chmod +x ./scripts/build.sh
+
+          # Build for all platforms
+          ./scripts/build.sh \
+            --verbose \
+            -ldflags "-s -w -X github.com/kjanat/articulate-parser/internal/version.Version=${{ github.ref_name }} -X github.com/kjanat/articulate-parser/internal/version.BuildTime=$BUILD_TIME -X github.com/kjanat/articulate-parser/internal/version.GitCommit=${{ github.sha }}"
+
+      - name: Compress binaries
+        run: |
+          cd build/
+          for binary in articulate-parser-*; do
+            echo "Compressing $binary..."
+            upx --best "$binary" || {
+              echo "Warning: UPX compression failed for $binary, keeping original"
+            }
+          done
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            build/articulate-parser-linux-amd64
+            build/articulate-parser-linux-arm64
+            build/articulate-parser-windows-amd64.exe
+            build/articulate-parser-windows-arm64.exe
+            build/articulate-parser-darwin-amd64
+            build/articulate-parser-darwin-arm64
+          generate_release_notes: true
+          draft: false
+          # Mark pre-1.0 versions (v0.x.x) as prerelease since they are considered unstable
+          # This helps users understand that these releases may have breaking changes
+          prerelease: ${{ startsWith(github.ref, 'refs/tags/v0.') }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -1,66 +1,71 @@
-# Created by https://www.toptal.com/developers/gitignore/api/go
+# Created by https://www.toptal.com/developers/gitignore/api/go
-# Edit at https://www.toptal.com/developers/gitignore?templates=go
+# Edit at https://www.toptal.com/developers/gitignore?templates=go
-
+
-### Go ###
+### Go ###
-# If you prefer the allow list template instead of the deny list, see community template:
+# If you prefer the allow list template instead of the deny list, see community template:
-# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
-#
+#
-# Binaries for programs and plugins
+# Binaries for programs and plugins
-*.exe
+*.exe
-*.exe~
+*.exe~
-*.dll
+*.dll
-*.so
+*.so
-*.dylib
+*.dylib
-
+
-# Test binary, built with `go test -c`
+# Test binary, built with `go test -c`
-*.test
+*.test
-
+
-# Output of the go coverage tool, specifically when used with LiteIDE
+# Output of the go coverage tool, specifically when used with LiteIDE
-*.out
+*.out
-
+
-# Dependency directories (remove the comment below to include it)
+# Dependency directories (remove the comment below to include it)
-# vendor/
+# vendor/
-
+
-# Go workspace file
+# Go workspace file
-go.work
+go.work
-
+
-# End of https://www.toptal.com/developers/gitignore/api/go
+# End of https://www.toptal.com/developers/gitignore/api/go
-
+
-# Shit
+# Shit
-.github/TODO
+.github/TODO
-
+
-# Local test files
+# Local test files
-output/
+output/
-outputs/
+outputs/
-articulate-sample.json
+articulate-sample.json
-test-output.*
+test-output.*
-go-os-arch-matrix.csv
+go-os-arch-matrix.csv
-test_godocx.go
+test_godocx.go
-test_input.json
+test_input.json
-
+
-# Build artifacts
+# Build artifacts
-build/
+build/
-
+
-# Old workflows
+# Old workflows
-.github/workflows/ci-old.yml
+.github/workflows/ci-old.yml
-.github/workflows/ci-enhanced.yml
+.github/workflows/ci-enhanced.yml
-
+
-# Test coverage files
+# Test coverage files
-coverage.out
+coverage.out
-coverage.txt
+coverage.txt
-coverage.html
+coverage.html
-coverage.*
+coverage.*
-coverage
+coverage
-*.cover
+*.cover
-*.coverprofile
+*.coverprofile
-main_coverage
+main_coverage
-
+
-# Other common exclusions
+# Other common exclusions
-*.exe
+*.exe
-*.exe~
+*.exe~
-*.dll
+*.dll
-*.so
+*.so
-*.dylib
+*.dylib
-*.test
+*.test
-*.out
+*.out
-/tmp/
+/tmp/
+.github/copilot-instructions.md
+
+# Editors
+.vscode/
+.idea/

DOCKER.md

@@ -0,0 +1,82 @@
+# Articulate Parser - Docker
+
+A powerful command-line tool for parsing and processing articulate data files, now available as a lightweight Docker container.
+
+## Quick Start
+
+### Pull from GitHub Container Registry
+
+```bash
+docker pull ghcr.io/kjanat/articulate-parser:latest
+```
+
+### Run with Articulate Rise URL
+
+```bash
+docker run --rm -v $(pwd):/data ghcr.io/kjanat/articulate-parser:latest https://rise.articulate.com/share/N_APNg40Vr2CSH2xNz-ZLATM5kNviDIO#/ markdown /data/output.md
+```
+
+### Run with local files
+
+```bash
+docker run --rm -v $(pwd):/data ghcr.io/kjanat/articulate-parser:latest /data/input.json markdown /data/output.md
+```
+
+## Usage
+
+### Basic File Processing
+
+```bash
+# Process from Articulate Rise URL
+docker run --rm -v $(pwd):/data ghcr.io/kjanat/articulate-parser:latest https://rise.articulate.com/share/N_APNg40Vr2CSH2xNz-ZLATM5kNviDIO#/ markdown /data/output.md
+
+# Process a local JSON file
+docker run --rm -v $(pwd):/data ghcr.io/kjanat/articulate-parser:latest /data/document.json markdown /data/output.md
+
+# Process with specific format and output
+docker run --rm -v $(pwd):/data ghcr.io/kjanat/articulate-parser:latest /data/input.json docx /data/output.docx
+```
+
+### Display Help and Version
+
+```bash
+# Show help information
+docker run --rm ghcr.io/kjanat/articulate-parser:latest --help
+
+# Show version
+docker run --rm ghcr.io/kjanat/articulate-parser:latest --version
+```
+
+## Available Tags
+
+-   `latest` - Latest stable release
+-   `v1.x.x` - Specific version tags
+-   `main` - Latest development build
+
+## Image Details
+
+-   **Base Image**: `scratch` (minimal attack surface)
+-   **Architecture**: Multi-arch support (amd64, arm64)
+-   **Size**: < 10MB (optimized binary)
+-   **Security**: Runs as non-root user
+-   **Features**: SBOM and provenance attestation included
+
+## Development
+
+### Local Build
+
+```bash
+docker build -t articulate-parser .
+```
+
+### Docker Compose
+
+```bash
+docker-compose up --build
+```
+
+## Repository
+
+-   **Source**: [github.com/kjanat/articulate-parser](https://github.com/kjanat/articulate-parser)
+-   **Issues**: [Report bugs or request features](https://github.com/kjanat/articulate-parser/issues)
+-   **License**: See repository for license details

Dockerfile

@@ -0,0 +1,78 @@
+# Build stage
+FROM golang:1.24-alpine AS builder
+
+# Install git and ca-certificates (needed for fetching dependencies and HTTPS)
+RUN apk add --no-cache git ca-certificates tzdata file
+
+# Create a non-root user for the final stage
+RUN adduser -D -u 1000 appuser
+
+# Set the working directory
+WORKDIR /app
+
+# Copy go mod files
+COPY go.mod go.sum ./
+
+# Download dependencies
+RUN go mod download
+
+# Copy source code
+COPY . .
+
+# Build the application
+# Disable CGO for a fully static binary
+# Use linker flags to reduce binary size and embed version info
+ARG VERSION=dev
+ARG BUILD_TIME
+ARG GIT_COMMIT
+# Docker buildx automatically provides these for multi-platform builds
+ARG BUILDPLATFORM
+ARG TARGETPLATFORM  
+ARG TARGETOS
+ARG TARGETARCH
+ARG TARGETVARIANT
+
+# Debug: Show build information
+RUN echo "Building for platform: $TARGETPLATFORM (OS: $TARGETOS, Arch: $TARGETARCH, Variant: $TARGETVARIANT)" \
+&& echo "Build platform: $BUILDPLATFORM" \
+&& echo "Go version: $(go version)"
+
+RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build \
+-ldflags="-s -w -X github.com/kjanat/articulate-parser/internal/version.Version=${VERSION} -X github.com/kjanat/articulate-parser/internal/version.BuildTime=${BUILD_TIME} -X github.com/kjanat/articulate-parser/internal/version.GitCommit=${GIT_COMMIT}" \
+-o articulate-parser \
+./main.go
+
+# Verify the binary architecture
+RUN file /app/articulate-parser || echo "file command not available"
+
+# Final stage - minimal runtime image
+FROM scratch
+
+# Copy CA certificates for HTTPS requests
+COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+
+# Copy timezone data
+COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo
+
+# Add a minimal /etc/passwd file to support non-root user
+COPY --from=builder /etc/passwd /etc/passwd
+
+# Copy the binary
+COPY --from=builder /app/articulate-parser /articulate-parser
+
+# Switch to non-root user (appuser with UID 1000)
+USER appuser
+
+# Set the binary as entrypoint
+ENTRYPOINT ["/articulate-parser"]
+
+# Default command shows help
+CMD ["--help"]
+
+# Add labels for metadata
+LABEL org.opencontainers.image.title="Articulate Parser"
+LABEL org.opencontainers.image.description="A powerful CLI tool to parse Articulate Rise courses and export them to multiple formats (Markdown, HTML, DOCX). Supports media extraction, content cleaning, and batch processing for educational content conversion."
+LABEL org.opencontainers.image.vendor="kjanat"
+LABEL org.opencontainers.image.licenses="MIT"
+LABEL org.opencontainers.image.source="https://github.com/kjanat/articulate-parser"
+LABEL org.opencontainers.image.documentation="https://github.com/kjanat/articulate-parser/blob/master/DOCKER.md"

Dockerfile.dev

@@ -0,0 +1,78 @@
+# Development Dockerfile with shell access
+# Uses Alpine instead of scratch for debugging
+
+# Build stage - same as production
+FROM golang:1.24-alpine AS builder
+
+# Install git and ca-certificates (needed for fetching dependencies and HTTPS)
+RUN apk add --no-cache git ca-certificates tzdata file
+
+# Create a non-root user
+RUN adduser -D -u 1000 appuser
+
+# Set the working directory
+WORKDIR /app
+
+# Copy go mod files
+COPY go.mod go.sum ./
+
+# Download dependencies
+RUN go mod download
+
+# Copy source code
+COPY . .
+
+# Build the application
+# Disable CGO for a fully static binary
+# Use linker flags to reduce binary size and embed version info
+ARG VERSION=dev
+ARG BUILD_TIME
+ARG GIT_COMMIT
+# Docker buildx automatically provides these for multi-platform builds
+ARG BUILDPLATFORM
+ARG TARGETPLATFORM  
+ARG TARGETOS
+ARG TARGETARCH
+ARG TARGETVARIANT
+
+# Debug: Show build information
+RUN echo "Building for platform: $TARGETPLATFORM (OS: $TARGETOS, Arch: $TARGETARCH, Variant: $TARGETVARIANT)" \
+&& echo "Build platform: $BUILDPLATFORM" \
+&& echo "Go version: $(go version)"
+
+RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build \
+-ldflags="-s -w -X github.com/kjanat/articulate-parser/internal/version.Version=${VERSION} -X github.com/kjanat/articulate-parser/internal/version.BuildTime=${BUILD_TIME} -X github.com/kjanat/articulate-parser/internal/version.GitCommit=${GIT_COMMIT}" \
+-o articulate-parser \
+./main.go
+
+# Verify the binary architecture
+RUN file /app/articulate-parser || echo "file command not available"
+
+# Development stage - uses Alpine for shell access
+FROM alpine:3.21.3
+
+# Install minimal dependencies
+RUN apk add --no-cache ca-certificates tzdata
+
+# Copy the binary
+COPY --from=builder /app/articulate-parser /articulate-parser
+
+# Copy the non-root user configuration
+COPY --from=builder /etc/passwd /etc/passwd
+
+# Switch to non-root user
+USER appuser
+
+# Set the binary as entrypoint
+ENTRYPOINT ["/articulate-parser"]
+
+# Default command shows help
+CMD ["--help"]
+
+# Add labels for metadata
+LABEL org.opencontainers.image.title="Articulate Parser (Dev)"
+LABEL org.opencontainers.image.description="Development version of Articulate Parser with shell access"
+LABEL org.opencontainers.image.vendor="kjanat"
+LABEL org.opencontainers.image.licenses="MIT"
+LABEL org.opencontainers.image.source="https://github.com/kjanat/articulate-parser"
+LABEL org.opencontainers.image.documentation="https://github.com/kjanat/articulate-parser/blob/master/DOCKER.md"

README.md

@@ -9,6 +9,8 @@ A Go-based parser that converts Articulate Rise e-learning content to various fo
 [![License](https://img.shields.io/github/license/kjanat/articulate-parser?label=License)][MIT License] <!-- [![Commit activity](https://img.shields.io/github/commit-activity/m/kjanat/articulate-parser?label=Commit%20activity)][Commits] -->
 [![Last commit](https://img.shields.io/github/last-commit/kjanat/articulate-parser?label=Last%20commit)][Commits]
 [![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/kjanat/articulate-parser?label=Issues)][Issues]
+[![Docker Image](https://img.shields.io/badge/docker-ghcr.io-blue?logo=docker&logoColor=white)][Docker image] <!-- [![Docker Size](https://img.shields.io/docker/image-size/kjanat/articulate-parser?logo=docker&label=Image%20Size)][Docker image] -->
+[![Docker](https://img.shields.io/github/actions/workflow/status/kjanat/articulate-parser/docker.yml?logo=docker&label=Docker)][Docker workflow]
 [![CI](https://img.shields.io/github/actions/workflow/status/kjanat/articulate-parser/ci.yml?logo=github&label=CI)][Build]
 [![Codecov](https://img.shields.io/codecov/c/gh/kjanat/articulate-parser?token=eHhaHY8nut&logo=codecov&logoColor=%23F01F7A&label=Codecov)][Codecov]
 
@@ -101,7 +103,7 @@ The system follows **Clean Architecture** principles with clear separation of co
 
 ### Prerequisites
 
--   Go, I don't know the version, but I use go1.24.2 right now, and it works, see the [CI][Build] workflow where it is tested.
+-   Go, I don't know the version, but I have [![Go version](https://img.shields.io/github/go-mod/go-version/kjanat/articulate-parser?label=)][gomod] configured right now, and it works, see the [CI][Build] workflow where it is tested.
 
 ### Install from source
 
@@ -200,6 +202,130 @@ Then run:
 ./articulate-parser input.json md output.md
 ```
 
+## Docker
+
+The application is available as a Docker image from GitHub Container Registry.
+
+### 🐳 Docker Image Information
+
+- **Registry**: `ghcr.io/kjanat/articulate-parser`
+- **Platforms**: linux/amd64, linux/arm64
+- **Base Image**: Scratch (minimal footprint)
+- **Size**: ~15-20MB compressed
+
+### Quick Start
+
+```bash
+# Pull the latest image
+docker pull ghcr.io/kjanat/articulate-parser:latest
+
+# Show help
+docker run --rm ghcr.io/kjanat/articulate-parser:latest --help
+```
+
+### Available Tags
+
+| Tag | Description | Use Case |
+|-----|-------------|----------|
+| `latest` | Latest stable release from master branch | Production use |
+| `edge` | Latest development build from master branch | Testing new features |
+| `v1.x.x` | Specific version releases | Production pinning |
+| `develop` | Development branch builds | Development/testing |
+| `feature/docker-ghcr` | Feature branch builds | Feature testing |
+| `master` | Latest master branch build | Continuous integration |
+
+### Usage Examples
+
+#### Process a local file
+
+```bash
+# Mount current directory and process a local JSON file
+docker run --rm -v $(pwd):/workspace \
+  ghcr.io/kjanat/articulate-parser:latest \
+  /workspace/input.json markdown /workspace/output.md
+```
+
+#### Process from URL
+
+```bash
+# Mount output directory and process from Articulate Rise URL
+docker run --rm -v $(pwd):/workspace \
+  ghcr.io/kjanat/articulate-parser:latest \
+  "https://rise.articulate.com/share/xyz" docx /workspace/output.docx
+```
+
+#### Export to different formats
+
+```bash
+# Export to HTML
+docker run --rm -v $(pwd):/workspace \
+  ghcr.io/kjanat/articulate-parser:latest \
+  /workspace/course.json html /workspace/course.html
+
+# Export to Word Document
+docker run --rm -v $(pwd):/workspace \
+  ghcr.io/kjanat/articulate-parser:latest \
+  /workspace/course.json docx /workspace/course.docx
+
+# Export to Markdown
+docker run --rm -v $(pwd):/workspace \
+  ghcr.io/kjanat/articulate-parser:latest \
+  /workspace/course.json md /workspace/course.md
+```
+
+#### Batch Processing
+
+```bash
+# Process multiple files in a directory
+docker run --rm -v $(pwd):/workspace \
+  ghcr.io/kjanat/articulate-parser:latest \
+  bash -c "for file in /workspace/*.json; do
+    /articulate-parser \"\$file\" md \"\${file%.json}.md\"
+  done"
+```
+
+### Docker Compose
+
+For local development, you can use the provided `docker-compose.yml`:
+
+```bash
+# Build and run with default help command
+docker-compose up articulate-parser
+
+# Process files using mounted volumes
+docker-compose up parser-with-files
+```
+
+### Building Locally
+
+```bash
+# Build the Docker image locally
+docker build -t articulate-parser:local .
+
+# Run the local image
+docker run --rm articulate-parser:local --help
+
+# Build with specific version
+docker build --build-arg VERSION=local --build-arg BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ) -t articulate-parser:local .
+```
+
+### Environment Variables
+
+The Docker image supports the following build-time arguments:
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `VERSION` | Version string embedded in the binary | `dev` |
+| `BUILD_TIME` | Build timestamp | Current time |
+| `GIT_COMMIT` | Git commit hash | Current commit |
+
+### Docker Security
+
+- **Non-root execution**: The application runs as a non-privileged user
+- **Minimal attack surface**: Built from scratch base image
+- **No shell access**: Only the application binary is available
+- **Read-only filesystem**: Container filesystem is read-only except for mounted volumes
+
 ## Development
 
 ### Code Quality
@@ -329,6 +455,8 @@ This is a utility tool for educational content conversion. Please ensure you hav
 [Build]: https://github.com/kjanat/articulate-parser/actions/workflows/ci.yml
 [Codecov]: https://codecov.io/gh/kjanat/articulate-parser
 [Commits]: https://github.com/kjanat/articulate-parser/commits/master/
+[Docker workflow]: https://github.com/kjanat/articulate-parser/actions/workflows/docker.yml
+[Docker image]: https://github.com/kjanat/articulate-parser/pkgs/container/articulate-parser
 [Go report]: https://goreportcard.com/report/github.com/kjanat/articulate-parser
 [gomod]: go.mod
 [Issues]: https://github.com/kjanat/articulate-parser/issues

docker-compose.yml

@@ -0,0 +1,39 @@
+services:
+  articulate-parser: &articulate-parser
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        VERSION: "dev"
+        BUILD_TIME: "2024-01-01T00:00:00Z"
+        GIT_COMMIT: "dev"
+    image: articulate-parser:local
+    volumes:
+      # Mount current directory to /workspace for file access
+      - .:/workspace
+    working_dir: /workspace
+    # Override entrypoint for interactive use
+    entrypoint: ["/articulate-parser"]
+    # Default to showing help
+    command: ["--help"]
+
+  # Service for processing files with volume mounts
+  parser-with-files:
+    <<: *articulate-parser
+    volumes:
+      - ./input:/input:ro
+      - ./output:/output
+    command: ["/input/sample.json", "markdown", "/output/result.md"]
+
+  # Service for development - with shell access
+  parser-dev:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    image: articulate-parser:dev
+    volumes:
+      - .:/workspace
+    working_dir: /workspace
+    entrypoint: ["/bin/sh"]
+    command: ["-c", "while true; do sleep 30; done"]
+    # Uses Dockerfile.dev with Alpine base instead of scratch for shell access

internal/version/version.go

@@ -5,7 +5,7 @@ package version
 // Version information.
 var (
 	// Version is the current version of the application.
-	Version = "0.3.1"
+	Version = "0.4.1"
 
 	// BuildTime is the time the binary was built.
 	BuildTime = "unknown"

main.go

@@ -7,9 +7,11 @@ import (
 	"fmt"
 	"log"
 	"os"
+	"strings"
 
 	"github.com/kjanat/articulate-parser/internal/exporters"
 	"github.com/kjanat/articulate-parser/internal/services"
+	"github.com/kjanat/articulate-parser/internal/version"
 )
 
 // main is the entry point of the application.
@@ -28,15 +30,23 @@ func run(args []string) int {
 	exporterFactory := exporters.NewFactory(htmlCleaner)
 	app := services.NewApp(parser, exporterFactory)
 
+	// Check for version flag
+	if len(args) > 1 && (args[1] == "--version" || args[1] == "-v") {
+		fmt.Printf("%s version %s\n", args[0], version.Version)
+		fmt.Printf("Build time: %s\n", version.BuildTime)
+		fmt.Printf("Git commit: %s\n", version.GitCommit)
+		return 0
+	}
+
+	// Check for help flag
+	if len(args) > 1 && (args[1] == "--help" || args[1] == "-h" || args[1] == "help") {
+		printUsage(args[0], app.GetSupportedFormats())
+		return 0
+	}
+
 	// Check for required command-line arguments
 	if len(args) < 4 {
-		fmt.Printf("Usage: %s <source> <format> <output>\n", args[0])
+		printUsage(args[0], app.GetSupportedFormats())
-		fmt.Printf("  source: URI or file path to the course\n")
-		fmt.Printf("  format: export format (%s)\n", joinStrings(app.GetSupportedFormats(), ", "))
-		fmt.Printf("  output: output file path\n")
-		fmt.Println("\nExample:")
-		fmt.Printf("  %s articulate-sample.json markdown output.md\n", args[0])
-		fmt.Printf("  %s https://rise.articulate.com/share/xyz docx output.docx\n", args[0])
 		return 1
 	}
 
@@ -73,25 +83,17 @@ func isURI(str string) bool {
 	return len(str) > 7 && (str[:7] == "http://" || str[:8] == "https://")
 }
 
-// joinStrings concatenates a slice of strings using the specified separator.
+// printUsage prints the command-line usage information.
 //
 // Parameters:
-//   - strs: The slice of strings to join
+//   - programName: The name of the program (args[0])
-//   - sep: The separator to insert between each string
+//   - supportedFormats: Slice of supported export formats
-//
+func printUsage(programName string, supportedFormats []string) {
-// Returns:
+	fmt.Printf("Usage: %s <source> <format> <output>\n", programName)
-//   - A single string with all elements joined by the separator
+	fmt.Printf("  source: URI or file path to the course\n")
-func joinStrings(strs []string, sep string) string {
+	fmt.Printf("  format: export format (%s)\n", strings.Join(supportedFormats, ", "))
-	if len(strs) == 0 {
+	fmt.Printf("  output: output file path\n")
-		return ""
+	fmt.Println("\nExample:")
-	}
+	fmt.Printf("  %s articulate-sample.json markdown output.md\n", programName)
-	if len(strs) == 1 {
+	fmt.Printf("  %s https://rise.articulate.com/share/xyz docx output.docx\n", programName)
-		return strs[0]
-	}
-
-	result := strs[0]
-	for i := 1; i < len(strs); i++ {
-		result += sep + strs[i]
-	}
-	return result
 }

main_test.go

@@ -85,80 +85,6 @@ func TestIsURI(t *testing.T) {
 	}
 }
 
-// TestJoinStrings tests the joinStrings function with various input scenarios.
-func TestJoinStrings(t *testing.T) {
-	tests := []struct {
-		name      string
-		strs      []string
-		separator string
-		expected  string
-	}{
-		{
-			name:      "empty slice",
-			strs:      []string{},
-			separator: ", ",
-			expected:  "",
-		},
-		{
-			name:      "single string",
-			strs:      []string{"hello"},
-			separator: ", ",
-			expected:  "hello",
-		},
-		{
-			name:      "two strings with comma separator",
-			strs:      []string{"markdown", "docx"},
-			separator: ", ",
-			expected:  "markdown, docx",
-		},
-		{
-			name:      "three strings with comma separator",
-			strs:      []string{"markdown", "md", "docx"},
-			separator: ", ",
-			expected:  "markdown, md, docx",
-		},
-		{
-			name:      "multiple strings with pipe separator",
-			strs:      []string{"option1", "option2", "option3"},
-			separator: " | ",
-			expected:  "option1 | option2 | option3",
-		},
-		{
-			name:      "strings with no separator",
-			strs:      []string{"a", "b", "c"},
-			separator: "",
-			expected:  "abc",
-		},
-		{
-			name:      "strings with newline separator",
-			strs:      []string{"line1", "line2", "line3"},
-			separator: "\n",
-			expected:  "line1\nline2\nline3",
-		},
-		{
-			name:      "empty strings in slice",
-			strs:      []string{"", "middle", ""},
-			separator: "-",
-			expected:  "-middle-",
-		},
-		{
-			name:      "nil slice",
-			strs:      nil,
-			separator: ", ",
-			expected:  "",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := joinStrings(tt.strs, tt.separator)
-			if result != tt.expected {
-				t.Errorf("joinStrings(%v, %q) = %q, want %q", tt.strs, tt.separator, result, tt.expected)
-			}
-		})
-	}
-}
-
 // BenchmarkIsURI benchmarks the isURI function performance.
 func BenchmarkIsURI(b *testing.B) {
 	testStr := "https://rise.articulate.com/share/N_APNg40Vr2CSH2xNz-ZLATM5kNviDIO#/"
@@ -169,17 +95,6 @@ func BenchmarkIsURI(b *testing.B) {
 	}
 }
 
-// BenchmarkJoinStrings benchmarks the joinStrings function performance.
-func BenchmarkJoinStrings(b *testing.B) {
-	strs := []string{"markdown", "md", "docx", "word", "pdf", "html"}
-	separator := ", "
-
-	b.ResetTimer()
-	for i := 0; i < b.N; i++ {
-		joinStrings(strs, separator)
-	}
-}
-
 // TestRunWithInsufficientArgs tests the run function with insufficient command-line arguments.
 func TestRunWithInsufficientArgs(t *testing.T) {
 	tests := []struct {
@@ -236,15 +151,109 @@ func TestRunWithInsufficientArgs(t *testing.T) {
 	}
 }
 
+// TestRunWithHelpFlags tests the run function with help flag arguments.
+func TestRunWithHelpFlags(t *testing.T) {
+	helpFlags := []string{"--help", "-h", "help"}
+
+	for _, flag := range helpFlags {
+		t.Run("help_flag_"+flag, func(t *testing.T) {
+			// Capture stdout
+			oldStdout := os.Stdout
+			r, w, _ := os.Pipe()
+			os.Stdout = w
+
+			// Run with help flag
+			args := []string{"articulate-parser", flag}
+			exitCode := run(args)
+
+			// Restore stdout
+			w.Close()
+			os.Stdout = oldStdout
+
+			// Read captured output
+			var buf bytes.Buffer
+			io.Copy(&buf, r)
+			output := buf.String()
+
+			// Verify exit code is 0 (success)
+			if exitCode != 0 {
+				t.Errorf("Expected exit code 0 for help flag %s, got %d", flag, exitCode)
+			}
+
+			// Verify help content is displayed
+			expectedContent := []string{
+				"Usage:",
+				"source: URI or file path to the course",
+				"format: export format",
+				"output: output file path",
+				"Example:",
+				"articulate-sample.json markdown output.md",
+				"https://rise.articulate.com/share/xyz docx output.docx",
+			}
+
+			for _, expected := range expectedContent {
+				if !strings.Contains(output, expected) {
+					t.Errorf("Expected help output to contain %q when using flag %s, got: %s", expected, flag, output)
+				}
+			}
+		})
+	}
+}
+
+// TestRunWithVersionFlags tests the run function with version flag arguments.
+func TestRunWithVersionFlags(t *testing.T) {
+	versionFlags := []string{"--version", "-v"}
+
+	for _, flag := range versionFlags {
+		t.Run("version_flag_"+flag, func(t *testing.T) {
+			// Capture stdout
+			oldStdout := os.Stdout
+			r, w, _ := os.Pipe()
+			os.Stdout = w
+
+			// Run with version flag
+			args := []string{"articulate-parser", flag}
+			exitCode := run(args)
+
+			// Restore stdout
+			w.Close()
+			os.Stdout = oldStdout
+
+			// Read captured output
+			var buf bytes.Buffer
+			io.Copy(&buf, r)
+			output := buf.String()
+
+			// Verify exit code is 0 (success)
+			if exitCode != 0 {
+				t.Errorf("Expected exit code 0 for version flag %s, got %d", flag, exitCode)
+			}
+
+			// Verify version content is displayed
+			expectedContent := []string{
+				"articulate-parser version",
+				"Build time:",
+				"Git commit:",
+			}
+
+			for _, expected := range expectedContent {
+				if !strings.Contains(output, expected) {
+					t.Errorf("Expected version output to contain %q when using flag %s, got: %s", expected, flag, output)
+				}
+			}
+		})
+	}
+}
+
 // TestRunWithInvalidFile tests the run function with a non-existent file.
 func TestRunWithInvalidFile(t *testing.T) {
 	// Capture stdout and stderr
 	oldStdout := os.Stdout
 	oldStderr := os.Stderr
-	
+
 	stdoutR, stdoutW, _ := os.Pipe()
 	stderrR, stderrW, _ := os.Pipe()
-	
+
 	os.Stdout = stdoutW
 	os.Stderr = stderrW
 
@@ -267,7 +276,7 @@ func TestRunWithInvalidFile(t *testing.T) {
 	var stdoutBuf, stderrBuf bytes.Buffer
 	io.Copy(&stdoutBuf, stdoutR)
 	io.Copy(&stderrBuf, stderrR)
-	
+
 	stdoutR.Close()
 	stderrR.Close()
 
@@ -288,10 +297,10 @@ func TestRunWithInvalidURI(t *testing.T) {
 	// Capture stdout and stderr
 	oldStdout := os.Stdout
 	oldStderr := os.Stderr
-	
+
 	stdoutR, stdoutW, _ := os.Pipe()
 	stderrR, stderrW, _ := os.Pipe()
-	
+
 	os.Stdout = stdoutW
 	os.Stderr = stderrW
 
@@ -314,7 +323,7 @@ func TestRunWithInvalidURI(t *testing.T) {
 	var stdoutBuf, stderrBuf bytes.Buffer
 	io.Copy(&stdoutBuf, stdoutR)
 	io.Copy(&stderrBuf, stderrR)
-	
+
 	stdoutR.Close()
 	stderrR.Close()