GitHub Pages Setup

Simple guide to enable GitHub Pages for your gem-ci repository documentation.

Quick Setup

1. Enable GitHub Pages

  1. Go to repository Settings
  2. Scroll to Pages section
  3. Under Source, select Deploy from a branch
  4. Choose Branch: master or main
  5. Choose Folder: / (root) or /docs
  6. Click Save

2. Configure Jekyll (if using /docs folder)

The repository already includes docs/_config.yml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

title: gem-ci
description: Ruby gem continuous integration workflows
baseurl: "/gem-ci"
url: "https://your-username.github.io"

markdown: kramdown
highlighter: rouge
theme: minima

plugins:
  - jekyll-feed
  - jekyll-sitemap

exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor

3. Update Configuration

Edit docs/_config.yml with your details:

1
2
3
4

title: Your Gem Name
description: Your gem description
baseurl: "/your-repo-name"
url: "https://your-username.github.io"

4. Access Your Site

After setup, your documentation will be available at:

1

https://your-username.github.io/your-repo-name/

File Structure

The docs folder should look like:

1
2
3
4
5
6
7
8
9
10
11
12
13

docs/
├── _config.yml          # Jekyll configuration
├── index.md            # Homepage
├── guides/             # User guides
│   ├── gitflow.md
│   └── local-testing.md
├── setup/              # Setup instructions
│   ├── secrets.md
│   └── github-pages.md
├── workflows/          # Workflow documentation
│   └── overview.md
└── diagrams/           # Workflow diagrams
    └── ci-workflow-overview.md

Custom Domain (Optional)

To use a custom domain:

  1. Create docs/CNAME file with your domain: 
    1

    your-domain.com
  2. Configure DNS with your domain provider:
    • Add CNAME record pointing to your-username.github.io
  3. In repository Settings > Pages:
    • Enter your custom domain
    • Enable “Enforce HTTPS”

Testing Locally

Install Jekyll to test locally:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Install Jekyll
gem install jekyll bundler

# Navigate to docs folder
cd docs

# Create Gemfile if needed
bundle init
bundle add jekyll
bundle add minima

# Serve locally
bundle exec jekyll serve

# View at http://localhost:4000

Troubleshooting

Site not updating?

404 errors?

Build failures?

Frontmatter Template

Add to the top of each markdown file:

1
2
3
4
5

---
layout: default
title: Page Title
description: Page description
---

That’s it! Your gem-ci documentation will be live on GitHub Pages.