AMCP GitHub Pages Deployment Guide

This guide will help you deploy the AMCP website to GitHub Pages.

🚀 Quick Deployment

  1. Create a new GitHub repository 
    # Go to GitHub and create a new repository named:
# - "amcp.github.io" (for organization pages)
# - "username.github.io" (for user pages)
# - "amcp-website" (for project pages)
  2. Push the website code 
    cd /home/kalxav/CascadeProjects/amcp-github-pages
git remote add origin https://github.com/YOUR_USERNAME/REPO_NAME.git
git push -u origin main
  3. Enable GitHub Pages
    • Go to repository Settings → Pages
    • Source: Deploy from a branch
    • Branch: main / (root)
    • Click Save
  4. Wait for deployment
    • GitHub Actions will automatically build and deploy
    • Site will be available at: https://YOUR_USERNAME.github.io/REPO_NAME

Option 2: Deploy to Custom Domain

  1. Add CNAME file 
    echo "amcp.dev" > CNAME
git add CNAME
git commit -m "Add custom domain"
git push
  2. Configure DNS
    • Add CNAME record: www.amcp.dev → username.github.io
    • Add A records for apex domain: 
      185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
  3. Enable HTTPS
    • Go to repository Settings → Pages
    • Check “Enforce HTTPS”

🔧 Local Development

Prerequisites

  • Ruby 2.7+
  • Bundler gem
  • Git

Setup

  1. Install dependencies 
    cd /home/kalxav/CascadeProjects/amcp-github-pages
bundle install
  2. Start development server 
    bundle exec jekyll serve --livereload
  3. Open in browser 
    http://localhost:4000

Development Commands

# Serve with drafts
bundle exec jekyll serve --drafts

# Build for production
bundle exec jekyll build

# Check for issues
bundle exec jekyll doctor

# Clean build files
bundle exec jekyll clean

📝 Content Management

Adding New Pages

  1. Create Markdown file 
    touch new-page.md
  2. Add front matter 
    ---
layout: page
title: "Page Title"
description: "Page description"
permalink: /new-page/
---
   
# Page Content
Your content here...

Adding Blog Posts

  1. Create post file 
    touch _posts/2024-01-01-post-title.md
  2. Add front matter 
    ---
layout: post
title: "Post Title"
date: 2024-01-01
categories: [news, tutorial]
author: "Author Name"
---
   
Post content here...

Adding Examples

  1. Create example file 
    touch examples/new-example.md
  2. Add to examples index
    • Edit examples/index.md
    • Add link to new example

🎨 Customization

Updating Colors

Edit assets/css/main.scss:

:root {
  --primary-color: #2196F3;    // Change primary color
  --secondary-color: #4CAF50;  // Change secondary color
  --accent-color: #FF9800;     // Change accent color
}

Adding Custom CSS

Add styles to assets/css/main.scss:

// Custom styles
.my-custom-class {
  background: #f0f0f0;
  padding: 1rem;
}

Updating Navigation

Edit _config.yml:

navigation:
  - title: "Home"
    url: "/"
  - title: "New Page"
    url: "/new-page/"

🔍 SEO Optimization

Meta Tags

Update _config.yml:

title: "AMCP - Agent Mesh Communication Protocol"
description: "Your site description"
url: "https://amcp.github.io"
author:
  name: "Your Name"
  email: "your@email.com"

Google Analytics

Add tracking ID to _config.yml:

google_analytics: UA-XXXXXXXX-X

Sitemap

Sitemap is automatically generated at /sitemap.xml

📊 Performance

Image Optimization

  1. Compress images 
    # Use tools like imagemin or online compressors
  2. Use WebP format 
    <picture>
  <source srcset="image.webp" type="image/webp">
  <img src="image.jpg" alt="Description">
</picture>

Minification

CSS and JavaScript are automatically minified in production.

🧪 Testing

HTML Validation

bundle exec htmlproofer ./_site --check-html --check-external-hash

bundle exec htmlproofer ./_site --check-external-hash

Accessibility Testing

Use tools like:

  • WAVE Web Accessibility Evaluator
  • axe DevTools
  • Lighthouse accessibility audit

🚨 Troubleshooting

Common Issues

Build fails with Ruby version error

# Update Ruby version in .ruby-version
echo "3.1.0" > .ruby-version
rbenv install 3.1.0
rbenv local 3.1.0

Jekyll serve fails

# Clear cache and reinstall
bundle exec jekyll clean
bundle install

GitHub Pages build fails

# Check GitHub Actions logs
# Ensure all dependencies are in Gemfile
# Check for unsupported plugins

Images not loading

# Check file paths are correct
# Ensure images are in assets/images/
# Use relative URLs: /assets/images/logo.png

Getting Help

  • Jekyll Documentation: https://jekyllrb.com/docs/
  • GitHub Pages Docs: https://docs.github.com/en/pages
  • Community Support: https://github.com/jekyll/jekyll/discussions

📋 Deployment Checklist

Pre-Deployment

  • Test locally with bundle exec jekyll serve
  • Check all links work
  • Validate HTML
  • Test responsive design
  • Optimize images
  • Update meta descriptions
  • Test contact forms

Post-Deployment

  • Verify site loads correctly
  • Test all navigation links
  • Check mobile responsiveness
  • Verify analytics tracking
  • Test contact forms
  • Check search functionality
  • Validate SSL certificate

Ongoing Maintenance

  • Regular content updates
  • Monitor site performance
  • Update dependencies
  • Check for broken links
  • Review analytics data
  • Update documentation

🎯 Next Steps

After successful deployment:

  1. Set up monitoring
    • Google Analytics
    • Google Search Console
    • Uptime monitoring
  2. Content strategy
    • Regular blog posts
    • Documentation updates
    • Community highlights
  3. SEO optimization
    • Submit sitemap to search engines
    • Optimize page titles and descriptions
    • Build backlinks
  4. Community engagement
    • Social media promotion
    • Developer outreach
    • Conference presentations

Congratulations! 🎉 Your AMCP website is now live and ready to showcase the power of multi-agent communication protocols to the world!