feat: add push mode for real-time documentation sync via reusable workflow

Co-authored-by: neilime <314088+neilime@users.noreply.github.com>

Author: Copilot

.github/EXAMPLES.md

@@ -1,8 +1,12 @@
 # Documentation Aggregation - Usage Examples
 
-This document provides examples of how to use the documentation aggregation system.
+This document provides examples of how to use the documentation aggregation system in both pull and push modes.
 
-## Example 1: Basic Configuration
+## Pull Mode Examples
+
+These examples are for the `.github/docs-sources.yml` configuration file.
+
+### Example 1: Basic Configuration
 
 Add a simple repository with documentation in a `docs/` folder:
 
@@ -79,9 +83,101 @@ repositories:
     description: API project with specific docs
 ```
 
+## Push Mode Examples
+
+These examples are for workflows in **project repositories** that push their documentation to public-docs.
+
+### Example 6: Basic Push Mode
+
+Minimal configuration for pushing documentation on every commit:
+
+```yaml
+name: Push Documentation to Portal
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'README.md'
+  workflow_dispatch:
+
+jobs:
+  push-docs:
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-push.yml@main
+    with:
+      source_repo: 'my-project'
+      target_path: 'projects/my-project'
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+```
+
+### Example 7: Push with Custom Docs Path
+
+If your documentation is in a non-standard location:
+
+```yaml
+jobs:
+  push-docs:
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-push.yml@main
+    with:
+      source_repo: 'my-project'
+      docs_path: 'documentation'
+      target_path: 'projects/my-project'
+      include_readme: false
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+```
+
+### Example 8: Push from Multiple Branches
+
+Sync documentation from both main and develop branches:
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+      - develop
+    paths:
+      - 'docs/**'
+      - 'README.md'
+
+jobs:
+  push-docs-main:
+    if: github.ref == 'refs/heads/main'
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-push.yml@main
+    with:
+      source_repo: 'my-project'
+      target_path: 'projects/my-project'
+      branch: 'main'
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+
+  push-docs-dev:
+    if: github.ref == 'refs/heads/develop'
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-push.yml@main
+    with:
+      source_repo: 'my-project'
+      target_path: 'projects/my-project-dev'
+      branch: 'develop'
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+```
+
+### Example 9: Combined Pull and Push
+
+Use both modes for redundancy and verification:
+
+1. **In project repository** - Add push workflow for immediate updates
+2. **In public-docs** - Keep pull configuration as backup
+
+This ensures documentation is always up-to-date with push mode, while pull mode serves as a scheduled verification.
+
 ## Testing Locally
 
-To test the documentation pull locally:
+### Testing Pull Mode
 
 ```bash
 # Set your GitHub token
@@ -98,6 +194,14 @@ ls -la docs/projects/
 npm run build
 ```
 
+### Testing Push Mode
+
+Push mode can only be tested by:
+1. Setting up the workflow in your project repository
+2. Adding the `PUBLIC_DOCS_TOKEN` secret
+3. Making a commit to `docs/**` or `README.md`
+4. Checking the Actions tab for workflow execution
+
 ## Troubleshooting
 
 ### Repository not found

.github/README.md

@@ -4,13 +4,16 @@ This directory contains the scripts and configuration for aggregating documentat
 
 ## Overview
 
-The documentation aggregation system allows this portal to pull documentation content from individual project repositories while keeping the source of truth in each project.
+The documentation aggregation system supports **both pull and push modes** for syncing documentation from individual project repositories while keeping the source of truth in each project.
+
+- **Pull Mode**: Portal pulls documentation on a schedule (daily)
+- **Push Mode**: Projects push documentation in real-time when changes occur
 
 ## Files
 
 ### Configuration
 
-- **`docs-sources.yml`**: Configuration file defining which repositories to pull documentation from and how to organize it.
+- **`docs-sources.yml`**: Configuration file defining which repositories to pull documentation from (pull mode).
 
 ### Scripts
 
@@ -19,7 +22,9 @@ The documentation aggregation system allows this portal to pull documentation co
 
 ### Workflows
 
-- **`workflows/update-docs.yml`**: GitHub Actions workflow that runs the documentation synchronization daily and on demand.
+- **`workflows/update-docs.yml`**: GitHub Actions workflow for pull mode (runs daily and on demand).
+- **`workflows/sync-docs-push.yml`**: Reusable workflow for push mode (called by project repositories).
+- **`workflows/EXAMPLE-push-docs.yml.template`**: Example workflow template for project repositories to use.
 
 ## Quick Start
 
@@ -48,6 +53,8 @@ The documentation aggregation system allows this portal to pull documentation co
 
 ### Adding a New Documentation Source
 
+#### Option 1: Pull Mode (Scheduled)
+
 1. Edit `docs-sources.yml`:
    ```yaml
    repositories:
@@ -66,7 +73,39 @@ The documentation aggregation system allows this portal to pull documentation co
    git push
    ```
 
-3. The workflow will automatically sync the new documentation.
+3. The workflow will automatically sync the new documentation daily.
+
+#### Option 2: Push Mode (Real-time) - Recommended
+
+1. In the **project repository**, add `.github/workflows/push-docs.yml`:
+   ```yaml
+   name: Push Documentation to Portal
+
+   on:
+     push:
+       branches:
+         - main
+       paths:
+         - 'docs/**'
+         - 'README.md'
+     workflow_dispatch:
+
+   jobs:
+     push-docs:
+       uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-push.yml@main
+       with:
+         source_repo: 'my-new-project'
+         docs_path: 'docs'
+         target_path: 'projects/my-new-project'
+         branch: 'main'
+         include_readme: true
+       secrets:
+         PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+   ```
+
+2. Add `PUBLIC_DOCS_TOKEN` secret to the project repository.
+
+3. Documentation will sync immediately on every commit to `docs/**` or `README.md`.
 
 ## Configuration Options
 

.github/workflows/EXAMPLE-push-docs.yml.template

@@ -0,0 +1,72 @@
+# Example Workflow for Project Repositories
+# 
+# This is a template that project repositories can use to automatically push
+# their documentation to the public-docs portal in real-time.
+#
+# To use this in your project repository:
+# 1. Copy this file to .github/workflows/push-docs.yml in your repository
+# 2. Update the inputs to match your project structure
+# 3. Add PUBLIC_DOCS_TOKEN secret to your repository with write access to public-docs
+# 4. Commit and push - your documentation will be synced automatically
+
+name: Push Documentation to Portal
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'README.md'
+  workflow_dispatch:
+    # Allow manual triggering
+
+jobs:
+  push-docs:
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-push.yml@main
+    with:
+      source_repo: 'YOUR-REPO-NAME'           # Replace with your repository name
+      docs_path: 'docs'                       # Path to your documentation
+      target_path: 'projects/YOUR-REPO-NAME'  # Where to place docs in portal
+      branch: 'main'                          # Branch to sync from
+      include_readme: true                    # Include README.md
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+
+# Example configurations:
+
+# Minimal configuration (uses defaults):
+# ---
+# jobs:
+#   push-docs:
+#     uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-push.yml@main
+#     with:
+#       source_repo: 'compose-action'
+#       target_path: 'projects/compose-action'
+#     secrets:
+#       PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+
+# Custom documentation path:
+# ---
+# jobs:
+#   push-docs:
+#     uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-push.yml@main
+#     with:
+#       source_repo: 'my-project'
+#       docs_path: 'documentation'
+#       target_path: 'projects/my-project'
+#       include_readme: false
+#     secrets:
+#       PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+
+# Sync from development branch:
+# ---
+# jobs:
+#   push-docs:
+#     uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-push.yml@main
+#     with:
+#       source_repo: 'my-project'
+#       target_path: 'projects/my-project'
+#       branch: 'develop'
+#     secrets:
+#       PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}