Sinaptia Slide Builder

A custom slide generation system that separates content (Markdown) from templates (HTML structure), enabling easy content creation and template maintenance.

Quick Start

1. Create your slides - Write Markdown files in the slides/ directory
2. Add images - Place image files in the slides/media/ directory
3. Build slides - Run ruby build
4. View output - Open generated HTML files in output/ directory

How to Create Slides

Basic Slide Structure

Every slide is a Markdown file with YAML frontmatter:

---
template: content
---

# Your Slide Title

Your content goes here with **bold** and *italic* text.

Available Templates

1. Frontpage Template

For hero/title slides:

---
template: frontpage
---

# Welcome to My Presentation
## Subtitle Here

2. Section Title Template

For chapter dividers:

---
template: section-title
---

# Chapter 1
## Getting Started

3. Content Template

For main content slides:

---
template: content
---

# Slide Title

- Bullet point 1
- Bullet point 2
- Bullet point 3

Some paragraph text with **emphasis**.

Adding Images

Step 1: Place Images

Put your image files in the slides/media/ directory:

slides/
   1.md
   2.md
   media/
      whale.png        # Your image here
      diagram.jpg      # Another image

Step 2: Reference in Markdown

Use standard Markdown image syntax:

---
template: content
---

# My Slide with Image

Here's an important diagram:

![Diagram description](media/diagram.jpg)

And here's a fun whale:

![Whale](media/whale.png)

⚠️ CRITICAL: Always use media/filename (without leading slash) in your Markdown. Do NOT use /media/filename. The build process copies files from slides/media/ to output/media/ and converts paths automatically.

Code Blocks

Basic Code Block

```ruby
def hello_world
  puts "Hello, World!"
end

### Supported Languages
The system supports syntax highlighting for:
- Ruby
- JavaScript
- Python
- HTML
- CSS
- JSON
- And many more via Prism.js

### Example with Code
```markdown
---
template: content
---

# Ruby Example

Here's a simple Ruby method:

```ruby
class Presentation
  def initialize(title)
    @title = title
  end

  def display
    puts "Presenting: #{@title}"
  end
end

## File Naming and Organization

### Current Structure
Based on the actual project:

slides/ 1.md # Slides 2.md 2b.md 2c.md 3.md 4.md 4a.md 4b.md 4c.md 4d.md 6.md 6a.md 7.md 7a.md 7b.md 8.md media/ # Images and media directory whale.png cow.png pass.png works-on-my-machine.png no-moon.png haha.mp3

### Build Output
After running `ruby build`:

output/ 1.html 2.html 2b.html 2c.html 3.html 4.html 4a.html 4b.html 4c.html 4d.html 6.html 6a.html 7.html 7a.html 7b.html 8.html media/ whale.png cow.png pass.png works-on-my-machine.png no-moon.png haha.mp3

## Complete Examples

### Example 1: Welcome Slide
**File**: `slides/1.md`
```markdown
---
template: frontpage
---

# Building Better APIs
## A Developer's Guide to REST and GraphQL

Example 2: Section Divider

File: slides/2.md

---
template: section-title
---

# REST Fundamentals
## Understanding HTTP and Resources

Example 3: Content with Code and Images

File: slides/3.md

---
template: content
---

# REST API Example

Here's a simple user endpoint:

```javascript
// GET /api/users/123
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}

Architecture Overview

Key benefits:

• Stateless - Each request contains all needed information
• Cacheable - Responses can be cached for performance
• Uniform Interface - Consistent patterns across endpoints

### Example 4: Image-Heavy Slide
**File**: `slides/4.md`
```markdown
---
template: content
---

# REST vs GraphQL

## REST Architecture
![REST Diagram](media/rest-flow.png)

## GraphQL Architecture
![GraphQL Diagram](media/graphql-flow.png)

## Performance Comparison
![Performance Chart](media/performance.png)

Building Your Slides

Build Command

ruby build

What Happens During Build

1. Reads all .md files from slides/ directory
2. Parses YAML frontmatter and Markdown content
3. Applies appropriate HTML template
4. Renders Markdown to HTML with custom styling
5. Copies images from slides/media/ to output/media/
6. Generates final HTML files in output/ directory
7. Adds syntax highlighting and navigation

Viewing Your Slides

Open any .html file in output/ directory with your browser:

open output/1.html

Tips and Best Practices

Content Tips

• Keep titles short and clear
• Use bullet points for key information
• Include one main concept per slide
• Add images to break up text-heavy slides

Image Tips

• ALWAYS use media/filename path format (without leading slash)
• Use descriptive alt text for accessibility
• Keep image file sizes reasonable (< 1MB)
• Use consistent image formats (PNG for graphics, JPG for photos)
• Supported formats: PNG, JPG, JPEG, GIF, SVG, WebP
• Audio files also supported: MP3, WAV, OGG, M4A, AAC

Code Tips

• Keep code blocks short and focused
• Add comments to explain complex parts
• Use proper indentation
• Test code examples before including them

Organization Tips

• Use numbered or lettered prefixes for slide order (1.md, 2.md, 2b.md, etc.)
• Group related slides with consistent naming
• Create a slide outline before writing content
• Keep backup copies of important images

Troubleshooting

Common Issues

Images not showing:

• Check that image files are in slides/media/ directory
• Verify image paths use media/filename format in Markdown (NO leading slash)
• Ensure image filenames match exactly (case-sensitive)
• Common mistake: using /media/filename instead of media/filename

Code not highlighting:

• Verify language name is correct after ```
• Check for unclosed code blocks
• Make sure there are no extra spaces

Template not applied:

• Check YAML frontmatter syntax
• Verify template name matches available templates
• Ensure YAML frontmatter is at the very top of file

Getting Help

If you encounter issues:

1. Check that all .md files have proper YAML frontmatter
2. Verify image files exist in slides/media/ directory
3. Run ruby build and check for error messages
4. Compare your files with the examples in this manual

Advanced Usage

Custom Navigation

The system includes navigation between slides. Special slides like 2b.html are automatically included in navigation when they exist.

Template Customization

To modify templates, edit files in the templates/ directory:

• templates/frontpage.erb - Hero slides
• templates/section-title.erb - Chapter dividers
• templates/content.erb - Main content slides

Bulk Operations

To rebuild all slides after template changes:

ruby build

To compare generated slides with originals:

ruby compare_results.rb