ci: add action and workflow documentations to github pages

Signed-off-by: Emilien Escalle <emilien.escalle@escemi.com>

Author: neilime

.github/workflows/__test-action-deploy-jekyll-jampack.yml

@@ -16,20 +16,58 @@ jobs:
       - name: Arrange - Checkout
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
+      - name: Arrange - Create linked test pages
+        run: |
+          mkdir -p docs/tests
+          cat <<'EOF' > docs/tests/source.md
+          # Source Page
+
+          Link to [Target](docs/tests/target.md).
+          EOF
+          cat <<'EOF' > docs/tests/target.md
+          # Target Page
+
+          Target content for link rewriting validation.
+          EOF
+          printf '\n- [Docs Source](docs/tests/source.md)\n' >> README.md
+
       - name: Act - Deploy Jekyll
         id: deploy-jekyll
         uses: ./actions/deploy/jekyll
+        with:
+          pages: |
+            .github/workflows/release-actions.md
+            actions/deploy/jekyll/README.md
+            docs/tests/source.md
+            docs/tests/target.md
 
       - name: Assert - Check outputs
         uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           script: |
             const assert = require("assert");
-            const { existsSync } = require("fs");
+            const { existsSync, readFileSync } = require("fs");
+            const path = require("path");
 
             const buildPathOutput = ${{ toJSON(steps.deploy-jekyll.outputs.build-path) }};
             assert(buildPathOutput, `"build-path" output is empty`);
 
+            const workspacePath = process.env.GITHUB_WORKSPACE;
+            assert(workspacePath, "GITHUB_WORKSPACE environment variable is missing");
+
+            const jekyllSourcePath = path.join(workspacePath, "_site");
+            const indexMarkdownPath = path.join(jekyllSourcePath, "index.md");
+            assert(existsSync(indexMarkdownPath), `Index markdown does not exist at: ${indexMarkdownPath}`);
+
+            const sourceMarkdownPath = path.join(
+              jekyllSourcePath,
+              "docs/tests/source/index.md"
+            );
+            assert(
+              existsSync(sourceMarkdownPath),
+              `Generated source page markdown does not exist at: ${sourceMarkdownPath}`
+            );
+
             // Check if the build path exists
             assert(existsSync(buildPathOutput), `Build path does not exist: ${buildPathOutput}`);
 
@@ -41,6 +79,33 @@ jobs:
             const cssFilePath = `${buildPathOutput}/assets/css/style.css`;
             assert(existsSync(cssFilePath), `Jekyll site CSS file does not exist in the build path: ${cssFilePath}`);
 
+            // Check if the custom page files exist in the build path
+            const customPage1Path = `${buildPathOutput}/github/workflows/release-actions/index.html`;
+            assert(existsSync(customPage1Path), `Custom page 1 does not exist in the build path: ${customPage1Path}`);
+            const customPage2Path = `${buildPathOutput}/actions/deploy/jekyll/index.html`;
+            assert(existsSync(customPage2Path), `Custom page 2 does not exist in the build path: ${customPage2Path}`);
+
+            const copiedAssetPath = `${buildPathOutput}/assets/github/logo.svg`;
+            assert(existsSync(copiedAssetPath), `Expected local asset to be copied to: ${copiedAssetPath}`);
+
+            const customPage2Content = readFileSync(customPage2Path, "utf8");
+            assert(
+              customPage2Content.includes("/assets/github/logo.svg"),
+              `Generated page should reference the copied asset using the /assets prefix`
+            );
+
+            const indexMarkdownContent = readFileSync(indexMarkdownPath, "utf8");
+            assert(
+              indexMarkdownContent.includes("](docs/tests/source)"),
+              "Index markdown should rewrite links to created site pages"
+            );
+
+            const sourceMarkdownContent = readFileSync(sourceMarkdownPath, "utf8");
+            assert(
+              sourceMarkdownContent.includes("](../target)"),
+              "Created site page should rewrite links to sibling pages"
+            );
+
       - name: Act - Run Jampack
         uses: ./actions/deploy/jampack
         with:
@@ -68,6 +133,9 @@ jobs:
             const cssFilePath = `${buildPathOutput}/assets/css/style.css`;
             assert(existsSync(cssFilePath), `Jekyll site CSS file does not exist in the build path: ${cssFilePath}`);
 
+            const copiedAssetPath = `${buildPathOutput}/assets/github/logo.svg`;
+            assert(existsSync(copiedAssetPath), `Expected local asset to remain after packing: ${copiedAssetPath}`);
+
             // Assert that there is no "_jampack" directory in the build path
             const jampackDir = `${buildPathOutput}/_jampack`;
             assert(!existsSync(jampackDir), `Jampack cache directory should not exist in the build path: ${jampackDir}`);

.github/workflows/release-actions.yml

@@ -198,6 +198,38 @@ jobs:
           artifact-ids: ${{ needs.generate-documentation.outputs.artifact-id }}
           path: /
 
+      - id: get-documentation-paths
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        with:
+          script: |
+            const documentationPaths = [];
+
+            // Retrieve action manifests
+            const globber = await glob.create('./actions/**/README.md');
+            for await (const file of globber.globGenerator()) {
+              core.debug(`Found action documentation: ${file}`);
+              documentationPaths.push(file);
+            }
+
+            // Retrieve workflow manifests
+            const workflowGlobber = await glob.create('./.github/workflows/*.md');
+            for await (const file of workflowGlobber.globGenerator()) {
+              core.debug(`Found workflow documentation: ${file}`);
+              // Ignore internal workflows
+              if (file.match(/\/\.github\/workflows\/__.*\.md$/)) {
+                core.debug(`Ignoring internal workflow documentation: ${file}`);
+                continue;
+              }
+              core.debug(`Including workflow documentation: ${file}`);
+              documentationPaths.push(file);
+            }
+
+            core.setOutput(
+              'documentation-paths',
+              documentationPaths
+                .join('\n')
+            );
+
       # FIXME: This is a workaround for having workflow actions. See https://github.com/orgs/community/discussions/38659
       - id: oidc
         uses: ChristopherHX/oidc@73eee1ff03fdfce10eda179f617131532209edbd # v3
@@ -215,6 +247,8 @@ jobs:
 
       - id: build-jekyll
         uses: ./self-workflow/actions/deploy/jekyll
+        with:
+          pages: ${{ steps.get-documentation-paths.outputs.documentation-paths }}
 
       - uses: actions/create-github-app-token@67018539274d69449ef7c02e8e71183d1719ab42 # v2.1.4
         if: inputs.github-app-id

AGENTS.md

@@ -0,0 +1,26 @@
+# CI GitHub Publish - Agent Instructions
+
+## Quick Start
+
+This project is a collection of **opinionated GitHub Actions** for streamlined CI/CD workflows. For comprehensive documentation, see the main [README.md](README.md).
+
+### Key Sections to Reference
+
+- **[Overview](README.md#overview)** - Project purpose and scope
+- **[Actions](README.md#actions)** - Complete catalog of available actions by category
+- **[Reusable Workflows](README.md#reusable-workflows)** - Orchestration workflows for complex deployments
+- **[Contributing](README.md#contributing)** - Guidelines for contributing to the project; Structure patterns and development standards
+- **[Development Workflow](README.md#development-workflow)** - Commands for linting, testing, and local development
+
+## Agent-Specific Development Patterns
+
+### Critical Workflow Knowledge
+
+```bash
+# Essential commands for development
+make lint        # Run Super Linter (dockerized)
+make lint-fix    # Auto-fix linting issues
+gh act -W .github/workflows/workflow-file-to-test.yml  # Test workflows locally with `act`
+```
+
+For detailed documentation on each action and workflow, refer to the individual README files linked in the main [README.md](README.md).

README.md

@@ -1,19 +1,20 @@
-<!-- markdownlint-disable-next-line first-line-heading -->
-<div align="center" width="100%">
+# Continuous Integration - GitHub - Publish
 
-# <img src=".github/logo.svg" width="60px" align="center" alt="logo" /> Continuous Integration - GitHub - Publish
+<div align="center">
+  <img src=".github/logo.svg" width="60px" align="center" alt="Logo for Continuous Integration - GitHub - Publish" />
+</div>
+
+---
 
 [![Continuous Integration](https://github.com/hoverkraft-tech/ci-github-publish/actions/workflows/__main-ci.yml/badge.svg)](https://github.com/hoverkraft-tech/ci-github-publish/actions/workflows/__main-ci.yml)
 [![GitHub tag](https://img.shields.io/github/tag/hoverkraft-tech/ci-github-publish?include_prereleases=&sort=semver&color=blue)](https://github.com/hoverkraft-tech/ci-github-publish/releases/)
 [![License](https://img.shields.io/badge/License-MIT-blue)](#license)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-</div>
+## Overview
 
 Opinionated GitHub Actions and workflows for streamlined release, deployment, and publishing.
 
----
-
 ## Actions
 
 ### ArgoCD
@@ -112,6 +113,104 @@ _Reusable workflows for managing release process._
 
 👍 If you wish to contribute to this project, please read the [CONTRIBUTING.md](CONTRIBUTING.md) file, PRs are Welcome !
 
+### Action Structure Pattern
+
+All actions follow this consistent structure:
+
+```text
+actions/{category}/{action-name}/
+├── action.yml          # Action definition with inputs/outputs
+├── README.md          # Usage documentation
+└── *.js              # Optional Node.js scripts (e.g., prepare-site.js)
+```
+
+### Development Standards
+
+#### Action Definition Standards
+
+1. **Consistent branding**: All actions use `author: hoverkraft`, `icon: <specific-icon>`, `color: blue`
+2. **Composite actions**: Use `using: "composite"` with GitHub Script for complex logic
+3. **Pinned dependencies**: Always pin action versions with SHA (e.g., `@ed597411d8f924073f98dfc5c65a23a2325f34cd`)
+4. **Input validation**: Validate inputs early in GitHub Script steps
+
+#### JavaScript Patterns
+
+- **Class-based architecture**: Use classes like `AssetManager` for complex functionality
+- **Path utilities**: Extensive use of Node.js `path` module for cross-platform compatibility
+- **Regular expression patterns**: Define constants for reusable patterns (`MARKDOWN_IMAGE_REGEX`, `HTML_IMAGE_REGEX`)
+- **Caching**: Implement Map-based caching for expensive operations
+
+### Development Workflow
+
+#### Linting & Testing
+
+```bash
+make lint        # Run Super Linter (dockerized)
+make lint-fix    # Auto-fix issues where possible
+
+# Use GitHub Actions locally with `act`
+gh act -W .github/workflows/workflow-file-to-test.yml
+```
+
+#### File Conventions
+
+- **Dockerfile**: Uses Super Linter slim image for consistent code quality
+- **Tests**: Located in `tests/` with expected vs actual file comparisons
+- **Workflows**: Private workflows prefixed with `__` (e.g., `__main-ci.yml`)
+
+#### Action Development Conventions
+
+**Always follow these patterns when creating/modifying actions:**
+
+1. **Pinned Dependencies**: Use exact SHA commits for all action dependencies:
+
+   ```yaml
+   uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+   ```
+
+2. **Consistent Branding**: Every action.yml must include:
+
+   ```yaml
+   author: hoverkraft
+   branding:
+     icon: <specific-icon>
+     color: blue
+   ```
+
+3. **Input Validation**: Always validate inputs early in GitHub Script steps:
+   ```javascript
+   const urlInput = ${{ toJson(inputs.url ) }};
+   if (!urlInput) {
+     return core.setFailed("URL input is required.");
+   }
+   ```
+
+#### JavaScript Development Patterns
+
+**For Node.js scripts (like `prepare-site.js`):**
+
+- Use class-based architecture for complex functionality
+- Define regex patterns as constants (`MARKDOWN_IMAGE_REGEX`, `HTML_IMAGE_REGEX`)
+- Implement Map-based caching for expensive operations
+- Always use Node.js `path` module for cross-platform compatibility
+
+#### File Structure Understanding
+
+```text
+actions/{category}/{action-name}/     # Modular action organization
+├── action.yml                        # Action definition with inputs/outputs
+├── README.md                         # Usage documentation
+└── *.js                             # Optional Node.js scripts
+
+.github/workflows/                    # Reusable workflows
+├── deploy-*.yml                      # Deployment orchestration
+├── clean-deploy-*.yml               # Cleanup workflows
+└── __*.yml                          # Private/internal workflows
+
+tests/                               # Expected vs actual comparisons
+└── argocd-app-of-apps/             # Template testing structure
+```
+
 ## Author
 
 🏢 **Hoverkraft <contact@hoverkraft.cloud>**

actions/deploy/jekyll/action.yml

@@ -27,74 +27,18 @@ runs:
       uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
       with:
         script: |
-          const { randomUUID } = require('crypto');
-          const { join, relative, basename, extname, dirname } = require('path');
-          const { existsSync, readFileSync, writeFileSync } = require('fs');
-
-          // Prepare paths
-          const workspacePath = "${{ github.workspace }}";
-          const sitePath = join(workspacePath, "_site");
-          const buildPath = join(sitePath, "build");
-          core.setOutput("build-path", buildPath);
-
-          core.setOutput("jekyll-source", relative(workspacePath, sitePath));
-          core.setOutput("jekyll-destination", relative(workspacePath, buildPath));
-
-          // Prepare site pages
-          await io.mkdirP(sitePath);
-
-          // Set config
-          const configPath = join(sitePath, "_config.yml");
-          if (!existsSync(configPath)) {
-            const theme = "${{ inputs.theme }}";
-            if (!theme) {
-              throw new Error("Theme input is required.");
+          const prepareSite = require('./actions/deploy/jekyll/prepare-site.js');
+          await prepareSite({
+            core,
+            io,
+            glob,
+            inputs: {
+              theme: ${{ toJson(inputs.theme) }},
+              pages: ${{ toJson(inputs.pages) }}
             }
-            const isGitHubSupportedTheme = theme.startsWith("jekyll-theme-");
-
-            const configContent = isGitHubSupportedTheme
-              ? `theme: ${theme}`
-              : `remote_theme: ${theme}\nplugins:\n  - jekyll-remote-theme`;
-
-            writeFileSync(configPath, configContent);
-          }
-
-          function getPageSection(pageFile) {
-            const sectionDir = basename(pageFile, extname(pageFile))
-              .toLowerCase()
-              .replace(/[^a-z0-9]+/g, '-')
-              .replace(/^-|-$/g, '');
-
-            return join(sitePath, sectionDir, "index.md");
-          }
-
-          function getPageTitle(pageFile) {
-            return getPageSection(pageFile)
-              .split('-')
-              .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-              .join(' ');
-          }
-
-          async function createSitePage(pageFile, pageTitle = null, pagePath = null) {
-            pageTitle = pageTitle || getPageTitle(pageFile);
-            pagePath = pagePath || getPageSection(pageFile);
-            await io.mkdirP(dirname(pagePath));
-
-            const pageContent = `---\nlayout: default\ntitle: ${pageTitle}\n---\n\n${readFileSync(pageFile, 'utf8')}`;
-            return writeFileSync(pagePath, pageContent);
-          }
-
-          const indexPath = join(sitePath, "index.md");
-          if (!existsSync(indexPath)) {
-            await createSitePage("./README.md", "Home", indexPath);
-          }
+          });
 
-          const pages = "${{ inputs.pages }}";
-          const pageFilePatterns = pages.split([" ", "\n"]).map(p => p.trim()).filter(Boolean);
-          const globber = await glob.create(pageFilePatterns.join('\n'));
-          for await (const pageFile of globber.globGenerator()) {
-            await createSitePage(pageFile);
-          }
+    - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
 
     - name: Build Jekyll site
       uses: actions/jekyll-build-pages@44a6e6beabd48582f863aeeb6cb2151cc1716697 # v1.0.13