Deployment Guide

Resilience Comms: The Inclusive Emergency Blueprint

This guide explains how to deploy and maintain this Jekyll-based emergency communication resource.

Important: Before contributing, review our governance documents:

Prerequisites

Local Development

1. Clone the Repository

git clone https://github.com/mgifford/inclusive-emergency-readiness.git
cd inclusive-emergency-readiness

2. Install Dependencies

# Install Bundler if not already installed
gem install bundler

# Install Jekyll and dependencies
bundle install

3. Run Locally

# Serve the site locally
bundle exec jekyll serve

# Site will be available at http://localhost:4000

4. Build for Production

# Build static site
bundle exec jekyll build

# Output will be in _site/ directory

GitHub Pages Deployment

This repository is configured for automatic GitHub Pages deployment.

  1. Push changes to the main branch
  2. GitHub Actions will automatically build and deploy
  3. Site will be available at https://[username].github.io/inclusive-emergency-readiness

Option 2: Manual Configuration

If automatic deployment isn’t working:

  1. Go to repository Settings > Pages
  2. Set Source to “Deploy from a branch”
  3. Set Branch to main and folder to / (root)
  4. Click Save
  5. Site will build in a few minutes

GitHub Actions Setup

Two workflows are included:

Purpose: Weekly check of all external URLs. Dead links are reported.

Schedule: Every Sunday at 2 AM UTC

Manual trigger: Go to Actions > Link Rot Guard > Run workflow

Configuration: .github/workflows/link-checker.yml

Linter of Clarity

Purpose: Readability checks on all Markdown files (Flesch-Kincaid).

Triggers:

Configuration: .github/workflows/readability-check.yml

Customization

Site Configuration

Edit _config.yml to customize:

Styling

Edit stylesheets in assets/css/:

Content

Add or modify content in:

Layouts

Modify layouts in _layouts/:

Includes

Modify reusable components in _includes/:

PWA Configuration

Manifest

Edit manifest.json to customize PWA settings:

Service Worker

Edit assets/js/service-worker.js to customize offline behavior:

Performance Optimization

Images

  1. Add images to assets/images/
  2. Use WebP format for best compression
  3. Provide alt text for all images
  4. Keep images under 100KB when possible

CSS

The stylesheets are already optimized:

JavaScript

JavaScript is minimal and optional:

Site works fully without JavaScript.

Content Guidelines

Writing Style

Accessibility

All content must meet:

Readability

Run readability checks:

# The readability workflow will check automatically
# Or use online tools:
# - Hemingway Editor (hemingwayapp.com)
# - Readable.com
# - WebFX Readability Test

Testing

Before Each Release

Automated Testing

Workflows run automatically:

Manual Testing Tools

Maintenance

Regular Tasks

Weekly:

Monthly:

Quarterly:

Annually:

Troubleshooting

Jekyll Build Fails

Problem: bundle exec jekyll build fails

Solutions:

  1. Update dependencies: bundle update
  2. Check Ruby version: ruby --version (need 2.7+)
  3. Clear cache: bundle exec jekyll clean
  4. Reinstall: bundle install

GitHub Pages Not Updating

Problem: Changes pushed but site doesn’t update

Solutions:

  1. Check Actions tab for build errors
  2. Verify GitHub Pages is enabled in Settings
  3. Check _config.yml for errors
  4. Try force rebuild (Settings > Pages > Rebuild)

Problem: Internal links return 404

Solutions:

  1. Check file paths (case-sensitive)
  2. Verify files are in correct collections (_disabilities, _toolkits, _templates)
  3. Check _config.yml collection configuration
  4. Clear browser cache

Styles Not Applying

Problem: CSS not loading or applying

Solutions:

  1. Check SCSS syntax in assets/css/
  2. Verify _config.yml includes sass configuration
  3. Clear Jekyll cache: bundle exec jekyll clean
  4. Check browser console for errors

Support

Getting Help

Contributing

Before contributing, please review our governance documents:

See README.md for general contribution information.

All contributions must:

Security

Reporting Issues

If you discover a security vulnerability:

  1. DO NOT open a public issue
  2. Email project maintainers
  3. Include detailed description
  4. Allow time for fix before disclosure

Updates

Keep dependencies updated:

# Update all gems
bundle update

# Update specific gem
bundle update jekyll

License

This project is licensed under the Creative Commons Attribution 4.0 International License (CC-BY-4.0). See LICENSE file for details.

This license maximizes sharing and adaptation of emergency preparedness information worldwide.

Credits

Built with:

Follows:

Additional Resources

Questions? Open an issue or discussion on GitHub.

Ready to Deploy? Push to main and let GitHub Actions handle it!