[In the digital matrix where URLs thread through luminous forests, a wraith prowlsโthe 404 Specter. Its hunger is broken paths; its lair, forgotten slugs. Today you rise as a Link Warden, weaving binary incantations to bind the 404 and light every trail.]
Your quest blends myth and method: a practical Jekyll journey powered by GitHub CI/CD that harmonizes with the companion article โ404 Hunting: The Quest for Resources.โ Follow these chapters to forge stable permalinks, etch redirect runes, summon automated hyperlink guardians, and grow living resource endpoints so your realm strengthens with every release.
Once, refactors fractured timelines and slugs wandered nameless. Guild lore taught three arts to restore order: predictable permalinks, decisive redirects, and vigilant guardians that patrol every merge. Master these and the 404 Specter fades into mist.
jekyll-redirect-from frontโmatter runespretty permalinks affect trailing slashesbrew install rbenv ruby-build
rbenv install 3.2.4
rbenv local 3.2.4
gem install bundler
bundle install
bundle exec jekyll serve --livereload
# Use WSL2 Ubuntu and follow Linux steps
sudo apt-get update && sudo apt-get install -y ruby-full build-essential zlib1g-dev
gem install bundler
bundle install
bundle exec jekyll serve
Add or confirm in _config.yml:
permalink: pretty
url: https://your-domain.example
baseurl: "" # set to "/repo" for project pages
plugins:
- jekyll-sitemap
- jekyll-feed
- jekyll-redirect-from
Create an inviting 404.html:
---
permalink: /404.html
layout: default
---
<main class="not-found">
<h1>๐งญ Lost in the Linkwood</h1>
<p>The path you sought fades into mist. Try these routes:</p>
<ul>
<li><a href="/">Return to camp (home)</a></li>
<li><a href="/sitemap.xml">Consult the star map (sitemap)</a></li>
</ul>
<h2>Recent beacons</h2>
<ul>
<li><a href="/posts/essential-vscode-extensions-developers/">Essential VS Code Extensions for Developers: The Ultimate 2025 Guide</a></li>
<li><a href="/posts/docker-beginners-tutorial/">Docker for Beginners: Complete Tutorial to Get Started with Containers</a></li>
<li><a href="/posts/prd-machine-self-writing-documentation/">PRD Machine: Building a Self-Writing Product Requirements Distillery</a></li>
<li><a href="/posts/mastering-prompt-engineering-vscode-copilot/">Mastering Prompt Engineering: A Practical Guide to VS Code Copilot</a></li>
<li><a href="/posts/mastering-react-beginners-guide/">Mastering React: A Beginner's Guide</a></li>
</ul>
<p>If this seems wrong, please <a href="https://github.com/bamr87/it-journey/issues/new?title=404:%20/quests/level-1110-404-hunting-quest/">open a scroll (issue)</a>.</p>
<style>.not-found{max-width:720px;margin:3rem auto;padding:0 1rem}</style>
</main>
baseurl and how to use relative_url?Enable redirects:
# Gemfile
gem "jekyll-redirect-from"
# _config.yml
plugins:
- jekyll-redirect-from
On the new canonical page, add old trails:
redirect_from:
- /2023/11/04/old-title/
- /posts/old-title/
Or create a dedicated redirect stub:
---
layout: redirect
redirect_to: /posts/new-canonical-title/
permalink: /legacy-path/
---
Lychee (quick, generous):
name: Hyperlink Guardian
on:
pull_request:
push:
branches: [ main ]
schedule:
- cron: '0 3 * * 1'
jobs:
lychee:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run lychee
uses: lycheeverse/lychee-action@v1
with:
args: >-
--verbose --no-progress --cache --max-cache-age 1d
--accept 200,204,206,301,302,308
--exclude-mail
--timeout 20
**/*.md **/*.html
env:
GITHUB_TOKEN: $
HTMLProofer (strict, post-build):
name: Link Checker
on: [push, pull_request]
jobs:
htmlproofer:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ruby/setup-ruby@v1
with:
ruby-version: '3.2'
bundler-cache: true
- name: Build Jekyll
run: |
bundle install --path vendor/bundle
bundle exec jekyll build --trace
- name: HTMLProofer
run: |
gem install html-proofer
htmlproofer ./_site \
--assume-extension \
--check-external-hash \
--enforce-https \
--typhoeus-config 'timeout:20' \
--url-ignore "^https://localhost,https://127.0.0.1" \
--http-status-ignore '0,429'
Declare a collection:
collections:
resources:
output: true
permalink: /resources/:path/
Example content _resources/magic-spell.md:
---
title: The Magic Spell of Code
---
Content about spells...
Data-driven links via _data/quests.yml:
- name: 404 Hunting
description: Banish errors!
Template snippet:
Objective: Rename an existing page and preserve the old trail.
Requirements:
redirect_from for the old pathsSuccess Criteria:
Objective: Add one link checker on PRs and a scheduled weekly sweep.
Requirements:
Success Criteria:
Objective: Use guardian logs to create a minimal viable resource (MVR) or redirect to resolve a real 404.
graph TD
A[๐ฐ Quest Start] --> B{๐งโโ๏ธ Choose Path}
B -->|๐ macOS| C[Setup Ruby & Jekyll]
B -->|๐ช Windows| D[Use WSL2]
B -->|๐ง Linux| E[Install Ruby & Bundler]
C --> F[Forge Permalinks]
D --> F
E --> F
F --> G[Craft 404]
G --> H[Tame with Redirects]
H --> I[Summon CI Guardians]
I --> J[Grow Endpoints]
J --> K{โ
No 404s?}
K -->|Yes| L[๐ Rewards]
K -->|No| M[๐ง Debug & Retry]
M --> I
Prerequisite Quests:
Follow-Up Quests:
Validation Recap: