GitHub Pages Integration Guide
Overview
AutoSlideIdea provides seamless integration with GitHub Pages to publish your presentations as websites. This allows anyone to access your presentations simply by sharing a URL.
🎯 View Demo Site - See actual GitHub Pages output examples
Key Features
- Automatic Deployment: Automatically updates the website when pushing to the main branch
- Beautiful Gallery: Displays multiple presentations in an organized layout
- Search & Filter: Filter presentations by tags or search keywords
- Responsive Design: Works on PCs, tablets, and smartphones
- Dark Mode Support: Automatically switches based on system preferences
Setup Guide
1. Create New with GitHub Pages Workflow
The easiest way is to use the create-presentation.sh
script with the GitHub Pages workflow:
# Create a GitHub Pages-enabled presentation
./scripts/create-presentation.sh --github --workflow github-pages my-portfolio
# Create as a public repository (recommended)
./scripts/create-presentation.sh --github --public --workflow github-pages conference-2024
This command automatically configures:
- GitHub Actions workflow (
.github/workflows/github-pages.yml
) - Required permissions
- Build and deployment automation
2. Add to Existing Presentation
To add GitHub Pages functionality to an existing presentation repository:
- Copy the workflow file
cp templates/github-workflows/github-pages.yml .github/workflows/
- Commit and push
git add .github/workflows/github-pages.yml git commit -m "Add GitHub Pages workflow" git push origin main
- Enable GitHub Pages
- Go to repository Settings → Pages
- Set Source to “GitHub Actions”
3. Initial Deployment
After pushing, GitHub Actions will run automatically:
- Check Progress
- Check progress in the repository’s Actions tab
- First deployment may take 5-10 minutes
- Access URL
https://[username].github.io/[repository-name]/
Managing Presentations
Directory Structure
The GitHub Pages workflow assumes the following structure:
your-presentation/
├── slides.md # Main presentation
├── additional-talk.md # Additional presentations (optional)
├── assets/ # Images and resources
│ ├── images/
│ └── styles/
└── .github/
└── workflows/
└── github-pages.yml
Managing Multiple Presentations
You can manage multiple presentations in one repository:
repository/
├── slides.md # Main presentation
├── workshop/
│ └── hands-on.md # Workshop materials
├── lightning-talks/
│ ├── intro.md # 5-minute talk
│ └── advanced.md # Detailed version
└── assets/ # Shared resources
All .md
files are automatically converted to HTML/PDF and displayed in the gallery.
Customization
Customizing the Index Page
To customize the default index page:
- Copy the template
cp templates/github-pages/index-template.html index-template.html
- Edit placeholders
- ``: Site title
- ``: Site description
- ``: Header title
- Modify other text as needed
- Update workflow Modify the workflow to use your custom template
Presentation Metadata
Add metadata to each presentation to enrich the gallery display:
---
title: Presentation Creation in the AI Era
author: John Doe
date: 2024-01-15
tags: [AI, Automation, Marp]
description: Efficient presentation creation using AI tools
---
# Slide Title
Troubleshooting
Build Failures
- Check Actions Permissions
- Settings → Actions → General
- Ensure “Read and write permissions” is enabled
- Check Workflow
- Review error logs in the Actions tab
- Font installation failures are common
Page Not Displaying
- Check GitHub Pages Settings
- Settings → Pages
- Ensure Source is set to “GitHub Actions”
- If using custom domain, check DNS settings
- Check Deployment Status
- Verify “pages build and deployment” succeeded in Actions tab
Styles Not Applied
- Check Asset Paths
- Verify relative paths are correct
- Ensure
--allow-local-files
option is enabled
- Clear Cache
- Clear browser cache
- GitHub Pages cache lasts up to 10 minutes
Best Practices
- Organize Presentations
- Group related presentations in directories
- Use clear filenames (include dates or event names)
- Asset Management
- Properly compress images
- Consolidate shared resources in
assets/
directory
- Continuous Improvement
- Incorporate feedback after presentations
- Document updates clearly in commit messages
- Security
- Manage confidential presentations separately
- Use private repositories when necessary