Ship fast with confidence ✨
Build and audit your Jekyll site using Lighthouse, Pa11y, Linkinator, and HTML Validator. Get JSON reports, threshold-based CI failures, and a simple CLI that just works.
npx @brennanbrown/jekyll-audit auditWhat you get
- Lighthouse perf/SEO/best-practices
- Pa11y accessibility scan
- Linkinator broken links
- HTML validation errors
- Aggregated summary + CI exit codes
⚡
Build + Serve
Runs bundle exec jekyll build with JEKYLL_ENV=production, serves _site/, and respects baseurl from _config.yml.
🧭
Smart Targets
Discovers URLs from sitemap.xml or falls back to configured paths. Limits pages via maxPages.
📊
Reports + CI
Writes JSON reports and summary.json. Fails the build when thresholds are exceeded.
Quick start
Requirements: Node ≥ 18, Ruby with Jekyll for builds.
# install and run (no install)
npx @brennanbrown/jekyll-audit audit
# or install globally
npm i -g @brennanbrown/jekyll-audit
jekyll-audit audit
# target a running dev server
jekyll-audit --baseUrl http://127.0.0.1:4000 auditConfig (optional)
Create jekyll-audit.config.js in your repo:
/** @type {import('./dist/config/schema.js').AuditConfig} */
export default {
jekyll: { buildDir: '_site', buildCommand: 'bundle exec jekyll build' },
crawl: { useSitemap: true, maxPages: 50, paths: ['/'] },
thresholds: {
lighthouse: { performance: 0.8, seo: 0.9, 'best-practices': 0.9 },
accessibility: { maxIssues: 0 },
links: { maxBroken: 0 },
html: { maxErrors: 0 },
},
reports: { formats: ['json'], outDir: 'reports' },
};GitHub Actions
Add .github/workflows/jekyll-audit.yml:
name: Jekyll Audit
on: [push, pull_request]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ruby/setup-ruby@v1
with:
ruby-version: '3.2'
bundler-cache: true
- name: Install Jekyll deps
run: bundle install --path vendor/bundle
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm ci
- run: npm run build
- name: Run jekyll-audit
run: node bin/jekyll-audit audit
- name: Upload reports
if: always()
uses: actions/upload-artifact@v4
with:
name: jekyll-audit-reports
path: reports/Support the project 💖
If this tool helps your Jekyll workflows, consider sponsoring: