ℹ️ Usage

Table of Contents

1. Prerequisites
2. Repository Layout
3. Workflow
   1. Checkout
   2. Setup Pages
   3. Dr. Jekyll Build
   4. Upload & Deploy
4. Inputs
5. Writing Pages
   1. Navigation Order
   2. Child Pages
6. Callouts

---

Prerequisites

• A GitHub repository with GitHub Pages enabled (Settings → Pages → Source: GitHub Actions).
• A docs/ directory (or another directory of your choice) containing at least index.md and _config.yml.

---

Repository Layout

my-repo/
├── .github/
│   └── workflows/
│       └── docs.yml        <~ deployment workflow
└── docs/
    ├── _config.yml         <~ site configuration
    ├── index.md            <~ home page
    └── ...                 <~ additional pages

---

Workflow

The full recommended workflow is shown below. Each step is explained in the sections that follow.

---
name: Deploy Documentation

on:
  # Trigger automatically on pushes to the default branch:
  # push:
  #   branches:
  #     - "main"

  # Or trigger manually from the Actions tab:
  workflow_dispatch:

permissions: {}

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

jobs:
  build:
    permissions:
      contents: read   # to check out the repository
      pages: write     # required by actions/configure-pages
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          persist-credentials: false
          fetch-depth: 0

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v6

      - name: Dr. Jekyll Build
        uses: camalot/drjekyll-action@v1
        env:
          JEKYLL_ENV: production
        with:
          input_dir: ./docs
          output_dir: ./_site
          url: "${{ ${{ steps.pages.outputs.origin }} }}"
          baseurl: "${{ ${{ steps.pages.outputs.base_path }} }}"

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

  deploy:
    permissions:
      pages: write      # to deploy to GitHub Pages
      id-token: write   # to authenticate with GitHub Pages
    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@v5

Checkout

- name: Checkout
  uses: actions/checkout@v6
  with:
    persist-credentials: false
    fetch-depth: 0

A full history checkout (fetch-depth: 0) is recommended so that Jekyll can read Git metadata (e.g. page last-modified dates) if your theme uses it.

Setup Pages

- name: Setup Pages
  id: pages
  uses: actions/configure-pages@v6

actions/configure-pages configures the GitHub Pages deployment and exposes the site’s origin as a step output. The id: pages is required so the output can be referenced in the next step.

Dr. Jekyll Build

- name: Dr. Jekyll Build
  uses: camalot/drjekyll-action@v1
  env:
    JEKYLL_ENV: production
  with:
    input_dir: ./docs
    output_dir: ./_site
    url: "${{ ${{ steps.pages.outputs.origin }} }}"
    baseurl: "${{ ${{ steps.pages.outputs.base_path }} }}"

This is the core step. See Inputs below for full details.

Enterprise GitHub or Custom Domains:

• Set url to ${{ steps.pages.outputs.base_url }}.
• Set baseurl to "" (empty string).

Commercial GitHub Pages:

• Set url to ${{ steps.pages.outputs.origin }}.
• Set baseurl to ${{ steps.pages.outputs.base_path }}.

This ensures Jekyll generates correct absolute URLs for stylesheets, scripts, and links. Leaving it empty will cause assets to fail to load on the deployed site.

Upload & Deploy

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

Packages the output_dir as a Pages artifact. The deploy job then picks it up via actions/deploy-pages.

---

Inputs

Input	Description	Required	Default
input_dir	Path to your Jekyll source directory, relative to the repository root.	No	.
output_dir	Path where the built site is written, relative to the repository root.	No	_site
url	Full URL of the deployed site (e.g. https://my-org.github.io).	No	``
baseurl	Base path appended to the URL (e.g. /my-repo). Leave empty "" when deploying to a custom domain or organization Pages site.	No	/

---

Writing Pages

Pages are standard Markdown files with Jekyll front matter:

---
title: My Page
nav_order: 2
---

# My Page

Content goes here.

Navigation Order

Pages appear in the sidebar sorted by nav_order. Lower values appear first. The home page (index.md) should use nav_order: 1.

Child Pages

Use parent in the front matter to nest a page under another:

---
title: Sub-topic
parent: My Page
nav_order: 1
---

---

Callouts

The following callout types are available:

{: .note }
This is a note.

This is a note.

{: .new }
This is new.

This is new.

{: .highlight }
This is a highlight.

This is a highlight.

{: .tip }
This is a tip.

This is a tip.

{: .warning }
This is a warning.

This is a warning.

{: .caution }
This is a caution.

This is a caution.

{: .important }
This is important.

This is important.