Add VitePress documentation for Hermes 5.x

.github/workflows/docs.yml

@@ -0,0 +1,150 @@
+name: Deploy Documentation
+
+on:
+  workflow_run:
+    workflows: ["CI", "PHPUnit"]
+    types:
+      - completed
+    branches:
+      - master
+  pull_request:
+    branches: [master, main]
+  push:
+    branches: [master, main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.event_name == 'workflow_run' && 'pages' || format('docs-checks-{0}', github.ref) }}
+  cancel-in-progress: ${{ github.event_name != 'workflow_run' }}
+
+jobs:
+  links:
+    name: Docs links and SVG
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    if: github.event_name == 'pull_request' || github.event_name == 'push'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Check SVG files are well-formed XML
+        run: python3 docs/scripts/check-svg.py
+
+      - name: Setup Node.js
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: docs
+
+      - name: Check links on the built site
+        run: bash scripts/check-links.sh
+        working-directory: docs
+
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      actions: read
+      contents: read
+    if: |
+      github.event_name == 'workflow_run' &&
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_repository.full_name == github.repository &&
+      github.event.workflow_run.head_branch == 'master'
+
+    steps:
+      - name: Checkout code
+        # workflow_run runs from the default branch. Do not check out
+        # workflow_run.head_sha: Scorecard treats that as an untrusted checkout.
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Setup Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: docs
+
+      - name: Build current documentation (master)
+        run: |
+          echo "Building current documentation from master branch..."
+          npm run docs:build
+          mkdir -p ../dist
+          cp -r .vitepress/dist/* ../dist/
+        working-directory: docs
+
+      - name: Download coverage report from PHPUnit
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: coverage-report
+          path: coverage
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          run-id: ${{ github.event.workflow_run.id }}
+
+      - name: Add coverage to dist
+        run: |
+          if [ ! -d coverage ]; then
+            echo "No coverage report found"
+            exit 1
+          fi
+          echo "Adding coverage report to dist/coverage/"
+          mkdir -p dist/coverage
+          cp -r coverage/* dist/coverage/
+          {
+            echo "# Code Coverage Report"
+            echo
+            echo "Open [index.html](./index.html) for the line-by-line report."
+            echo
+            echo "- Commit: ${{ github.event.workflow_run.head_sha }}"
+            echo "- Branch: ${{ github.event.workflow_run.head_branch }}"
+            echo "- Workflow run: ${{ github.event.workflow_run.html_url }}"
+          } > dist/coverage/README.md
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: dist
+
+  deploy:
+    name: Deploy to GitHub Pages
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    if: |
+      github.event_name == 'workflow_run' &&
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_repository.full_name == github.repository &&
+      github.event.workflow_run.head_branch == 'master'
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

.gitignore

@@ -1,6 +1,9 @@
 build/
 vendor/
 composer.lock
+docs/node_modules/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
 coverage.clover
 .idea/
 .phpunit.cache/

README.md

@@ -1,9 +1,18 @@
 # Hermes
 
+<p align="left">
+  <img src="docs/public/logo.svg" alt="Hermes" width="96" height="96" />
+</p>
+
 **Background job processing PHP library**
 
+**Documentation: https://tomaj.github.io/hermes/**
+
+[Getting started](https://tomaj.github.io/hermes/guide/getting-started) · [API reference](https://tomaj.github.io/hermes/api/reference) · [Changelog](https://tomaj.github.io/hermes/changelog)
+
 [![Latest Stable Version](https://img.shields.io/packagist/v/tomaj/hermes.svg)](https://packagist.org/packages/tomaj/hermes)
 [![PHPStan](https://img.shields.io/badge/PHPStan-level%20max-brightgreen.svg)](https://phpstan.org/)
+[![Documentation](https://img.shields.io/badge/docs-5.x-4f46e5.svg)](https://tomaj.github.io/hermes/)
 
 ## What is Hermes?
 
@@ -458,7 +467,17 @@ The coverage reports will be generated in:
 - **HTML report**: `build/coverage/index.html` (open in browser to see line-by-line coverage)
 - **Clover XML**: `build/logs/clover.xml` (for CI/CD integration)
 
-**Online Coverage Reports**: Coverage reports are automatically published to GitHub Pages after each successful test run on the main branch.
+**Online Coverage Reports**: Coverage reports are published with the documentation site after each successful test run on `master`, at [https://tomaj.github.io/hermes/coverage/](https://tomaj.github.io/hermes/coverage/).
+
+## Documentation
+
+- [Documentation](https://tomaj.github.io/hermes/)
+- [Getting started](https://tomaj.github.io/hermes/guide/getting-started)
+- [Concepts](https://tomaj.github.io/hermes/guide/concepts)
+- [Drivers](https://tomaj.github.io/hermes/guide/drivers/)
+- [API reference](https://tomaj.github.io/hermes/api/reference)
+- [Changelog](https://tomaj.github.io/hermes/changelog)
+- [Coverage report](https://tomaj.github.io/hermes/coverage/)
 
 ## Contributing
 

docs/.vitepress/config.mts

@@ -0,0 +1,69 @@
+import { defineConfig } from 'vitepress'
+import { navEn, sidebar5x } from '../site-nav'
+
+const descriptionEn = 'PHP library for background jobs on Redis, RabbitMQ, and Amazon SQS'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: 'Hermes',
+  description: descriptionEn,
+  base: '/hermes/',
+
+  head: [
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/hermes/favicon.svg' }],
+    ['meta', { name: 'theme-color', content: '#4f46e5' }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:title', content: 'Hermes - background jobs for PHP' }],
+    ['meta', { property: 'og:description', content: descriptionEn }],
+    ['meta', { property: 'og:url', content: 'https://tomaj.github.io/hermes/' }],
+    ['meta', { property: 'og:image', content: 'https://tomaj.github.io/hermes/og.svg' }],
+    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+    ['meta', { name: 'twitter:title', content: 'Hermes - background jobs for PHP' }],
+    ['meta', { name: 'twitter:description', content: descriptionEn }],
+    ['meta', { name: 'twitter:image', content: 'https://tomaj.github.io/hermes/og.svg' }],
+  ],
+
+  lastUpdated: true,
+
+
+  // English is the only locale today. A `sk` locale can be added beside `root`
+  // without moving these pages. See guide/versioning.
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en-US',
+      description: descriptionEn,
+    },
+  },
+
+  themeConfig: {
+    logo: {
+      light: '/logo-light.svg',
+      dark: '/logo-dark.svg',
+    },
+
+    nav: navEn,
+
+    sidebar: {
+      '/': sidebar5x,
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/tomaj/hermes' },
+    ],
+
+    editLink: {
+      pattern: 'https://github.com/tomaj/hermes/edit/master/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+
+    search: {
+      provider: 'local',
+    },
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2015-2026 Tomas Majer',
+    },
+  },
+})

docs/.vitepress/theme/Diagram.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import { withBase } from 'vitepress'
+
+defineProps<{ name: string, alt: string }>()
+</script>
+
+<template>
+  <figure class="hand-diagram">
+    <img class="hand-diagram-light" :src="withBase(`/diagrams/${name}-light.svg`)" :alt="alt" loading="lazy" decoding="async">
+    <img class="hand-diagram-dark" :src="withBase(`/diagrams/${name}-dark.svg`)" :alt="alt" loading="lazy" decoding="async">
+  </figure>
+</template>

docs/.vitepress/theme/HeroFlow.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+import svg from '../../public/illustrations/hero-flow.svg?raw'
+</script>
+
+<template>
+  <div
+    class="hero-flow-host"
+    role="img"
+    aria-label="Messages move from emit into a queue. High and default go straight through. A scheduled message waits. One message fails and returns as a retry."
+    v-html="svg"
+  />
+</template>
+
+<style scoped>
+.hero-flow-host {
+  width: min(100%, 520px);
+}
+
+.hero-flow-host :deep(svg) {
+  width: 100%;
+  height: auto;
+  display: block;
+}
+</style>

docs/.vitepress/theme/Layout.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import DefaultTheme from 'vitepress/theme'
+import HeroFlow from './HeroFlow.vue'
+</script>
+
+<template>
+  <DefaultTheme.Layout>
+    <template #home-hero-image>
+      <HeroFlow />
+    </template>
+  </DefaultTheme.Layout>
+</template>