Presentations

Source controlled presentations using Remark.js and Markdown in dedicated directories with individual HTML files.

This repository provides a system for creating and maintaining presentations using:

• Markdown for content (easy to write and version control)
• Directory-based organization with individual HTML files for each presentation
• Remark.js for rendering beautiful HTML slides
• Git for version control and collaboration
• Reusable templates and shared assets

# Create a new presentation with starter content and structure
./templates/create-presentation.sh 2025-12-01-my-awesome-talk "My Awesome Talk" "Conference 2025"

# This creates:
# _presentations/2025-12-01-my-awesome-talk/
#   ├── presentation.md            # Your Remark.js slides
#   ├── README.md                  # Metadata and abstract (with front matter)
#   ├── slides.html                # Presentation viewer (auto-generated by Jekyll)
#   └── img/                       # Presentation-specific images

# Start Jekyll server
bundle exec jekyll serve

# Edit the markdown file with your slides
vim _presentations/2025-12-01-my-awesome-talk/presentation.md

# Preview in browser at:
# http://localhost:4000/presentations/2025-12-01-my-awesome-talk/slides.html

Navigate to your presentation viewer in the browser: http://localhost:4000/presentations/2025-12-01-my-awesome-talk/slides.html

Presentation Controls:

• Navigate: Arrow keys, Page Up/Down, or click
• Fullscreen: Press F
• Presenter Mode: Press P (shows current + next slide, timer, notes)
• Clone View: Press C (for dual monitor setup)

Common development tasks are available via the Makefile:

# Install dependencies
make install

# Start development server
make serve

# Build for production
make build

# Clean generated files
make clean

Important Note: Presentations must be served via Jekyll server (cannot view static files directly) because the markdown content is loaded dynamically via JavaScript.

# Install dependencies
bundle install

# Serve locally
bundle exec jekyll serve

# Visit http://localhost:4000

# Build site to _site/ directory
bundle exec jekyll build

# The _site/ directory contains the complete static site
# ready for deployment to GitHub Pages

Jekyll-based site with presentations as collections:

presentations/
├── _config.yml                    # Jekyll configuration
├── Gemfile                        # Ruby dependencies
├── _presentations/                # Jekyll collection
│   └── 2025-06-24-oss-na/
│       ├── presentation.md        # Remark.js slides (standardized name)
│       ├── README.md             # Metadata + abstract (front matter)
│       ├── slides.html           # Viewer page (uses layout)
│       ├── style.css             # Optional custom CSS
│       └── img/                  # Presentation images
├── _layouts/
│   ├── presentation-detail.html  # Detail page layout
│   └── presentation-viewer.html  # Full-screen Remark.js viewer
├── shared/                       # Shared assets
├── templates/
│   └── create-presentation.sh    # Presentation creation script
└── index.html                    # Auto-generated listing

class: center, middle, title-slide

# Main Title
## Subtitle
### Author • Date

---

## Regular Slide

Content goes here...

---

# Next Slide

More content...

• Text Styling: .red[text], .highlight[text], .blue[text]
• Two-Column Layouts: .left-column[] and .right-column[]
• Code Syntax Highlighting: ```python code blocks
• Images: ![Alt text](img/image.png) or ![Shared](../shared/images/logo.png)
• Speaker Notes: ??? followed by notes (visible in presenter mode)
• Footnotes: .footnote[text]

1. Create: ./templates/create-presentation.sh presentation-name
2. Edit: Modify the .md file with your content
3. Preview: Open the .html file in your browser
4. Iterate: Edit markdown, refresh browser

• Presentation-specific images: Save to presentation-name/img/
• Shared images: Use shared/images/ for logos, common diagrams
• Reference from markdown: ![Image](img/screenshot.png) or ![Logo](../shared/images/company-logo.png)

# Work on presentations in branches
git checkout -b presentation/my-new-talk
git add my-new-talk/
git commit -m "Add new presentation: My New Talk"
git push origin presentation/my-new-talk

✅ Self-Contained: Each presentation directory is fully portable with all assets
✅ Direct HTML Access: No server required, works offline
✅ Version Control: Track changes to both content and styling
✅ Shared Assets: Reuse common images and resources
✅ Template Updates: Consistent styling across presentations
✅ Documentation: Each presentation documents its own purpose and structure

Use pptx2md for automated conversion:

# Install pptx2md
pipx install pptx2md

# Convert PowerPoint to markdown
pptx2md presentation.pptx -o presentation.md -i img --enable-slides

# Create presentation directory using the template script
./templates/create-presentation.sh YYYY-MM-DD-presentation-name "Presentation Title" "Event Name"

# Replace the generated presentation.md with your converted content
mv presentation.md _presentations/YYYY-MM-DD-presentation-name/
mv img/* _presentations/YYYY-MM-DD-presentation-name/img/

# Serve and view at http://localhost:4000/presentations/YYYY-MM-DD-presentation-name/slides.html

Benefits of pptx2md:

• ✅ Preserves all text formatting (bold, italic, colors)
• ✅ Extracts all images automatically
• ✅ Maintains slide structure with --- separators
• ✅ Includes speaker notes
• ✅ Handles tables and lists properly

1. Extract content: Copy text content slide by slide
2. Download images: Save to presentation-name/img/
3. Convert formatting: Use markdown syntax and CSS classes
4. Test presentation: Preview frequently during conversion

# Serve with Jekyll (hot reload enabled)
bundle exec jekyll serve

# Visit: http://localhost:4000
# Presentations at: http://localhost:4000/presentations/<name>/
# Full-screen viewer: http://localhost:4000/presentations/<name>/slides.html

• Individual HTML files work offline
• Share entire presentation folder for offline viewing
• No server required for basic functionality

• Remark.js Documentation
• Markdown Guide

Happy presenting! 🎉

This system gives you the power of version control with the simplicity of individual HTML files for each presentation.