Add server-side Mermaid rendering with jekyll-mermaid-plugin

[Copilot]

Enable server-side Mermaid diagram rendering for the docs site by installing jekyll-mermaid-plugin and updating CI to build with Bundler.

Changes

• Gemfile (new): Add Jekyll 4.2 and jekyll-mermaid-plugin dependencies
• docs/_config.yml: Enable the mermaid plugin alongside existing theme
• .github/workflows/jekyll-gh-pages.yml: Replace direct Jekyll build with Bundler-based build
  • Set up Ruby 3.2
  • Install gems via bundle install
  • Build with bundle exec jekyll build --source ./docs --destination ./_site

Mermaid fenced code blocks in docs will now render to SVG at build time rather than requiring client-side JavaScript.

Original prompt

Add server-side Mermaid rendering by installing the jekyll-mermaid-plugin and updating the GitHub Actions workflow to build the site with Bundler. Changes to make:

1. Add a Gemfile at the repository root with these contents:

source "https://rubygems.org"

gem "jekyll", "~> 4.2.0"
gem "jekyll-mermaid-plugin"

2. Update the Jekyll config used for the docs site at docs/_config.yml. Current contents (from the repo):

theme: jekyll-theme-primer

Replace/augment it to enable the plugin (preserve existing theme):

theme: jekyll-theme-primer
plugins:
  - jekyll-mermaid-plugin

3. Replace the existing GitHub Actions workflow at .github/workflows/jekyll-gh-pages.yml with a workflow that installs Ruby, installs Bundler and gems, then builds the site with bundle exec jekyll build --source ./docs --destination ./_site so that the plugin is installed and run at build time. Use the current workflow as a base but modify the build steps accordingly. Proposed workflow content:

name: Deploy Jekyll with GitHub Pages dependencies preinstalled

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.2

      - name: Install Bundler and dependencies
        run: |
          gem install bundler
          bundle config set --local path vendor/bundle
          bundle install --jobs 4 --retry 3

      - name: Build site with Jekyll (bundle exec)
        run: bundle exec jekyll build --source ./docs --destination ./_site

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Notes / rationale:

• The Gemfile ensures jekyll-mermaid-plugin is installed during CI and will render mermaid fenced code blocks into SVG at build time.
• The workflow now sets up Ruby and runs bundle install followed by bundle exec jekyll build against the docs/ source so the plugin is active.
• The docs/_config.yml plugin entry enables the plugin for the docs site.

Please create a PR on the repository with these three file changes (add Gemfile, update docs/_config.yml, update workflow file) on a branch and open it against main. Commit messages should be descriptive (e.g., "Add jekyll-mermaid-plugin and build with Bundler in CI"). Do not include any personal or assignee information in the PR.

This pull request was created as a result of the following prompt from Copilot chat.

Add server-side Mermaid rendering by installing the jekyll-mermaid-plugin and updating the GitHub Actions workflow to build the site with Bundler. Changes to make:

1. Add a Gemfile at the repository root with these contents:

source "https://rubygems.org"

gem "jekyll", "~> 4.2.0"
gem "jekyll-mermaid-plugin"

2. Update the Jekyll config used for the docs site at docs/_config.yml. Current contents (from the repo):

theme: jekyll-theme-primer

Replace/augment it to enable the plugin (preserve existing theme):

theme: jekyll-theme-primer
plugins:
  - jekyll-mermaid-plugin

3. Replace the existing GitHub Actions workflow at .github/workflows/jekyll-gh-pages.yml with a workflow that installs Ruby, installs Bundler and gems, then builds the site with bundle exec jekyll build --source ./docs --destination ./_site so that the plugin is installed and run at build time. Use the current workflow as a base but modify the build steps accordingly. Proposed workflow content:

name: Deploy Jekyll with GitHub Pages dependencies preinstalled

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.2

      - name: Install Bundler and dependencies
        run: |
          gem install bundler
          bundle config set --local path vendor/bundle
          bundle install --jobs 4 --retry 3

      - name: Build site with Jekyll (bundle exec)
        run: bundle exec jekyll build --source ./docs --destination ./_site

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Notes / rationale:

• The Gemfile ensures jekyll-mermaid-plugin is installed during CI and will render mermaid fenced code blocks into SVG at build time.
• The workflow now sets up Ruby and runs bundle install followed by bundle exec jekyll build against the docs/ source so the plugin is active.
• The docs/_config.yml plugin entry enables the plugin for the docs site.

Please create a PR on the repository with these three file changes (add Gemfile, update docs/_config.yml, update workflow file) on a branch and open it against main. Commit messages should be descriptive (e.g., "Add jekyll-mermaid-plugin and build with Bundler in CI"). Do not include any personal or assignee information in the PR.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.