@sp-days-framework/create-sp-days 1.1.0-beta2 → 1.1.0-beta3

package/templates/addon-slidev/slidev/best-practices-guide.md

@@ -0,0 +1,769 @@
+---
+theme: "@sp-days-framework/slidev-theme-sykehuspartner"
+title: Slidev Best Practices Guide
+description: Learn how to create professional presentations with the Sykehuspartner theme
+layout: cover
+---
+
+# Slidev Best Practices Guide
+
+## Professional Presentations Made Simple
+
+---
+layout: intro
+imageSrc: https://sli.dev/logo.png
+imagePosition: right
+imageRatio: 35%
+---
+
+# What This Guide Covers
+
+- **Presentation Structure** - Opening, sections, and closing slides
+- **Content Density** - How much content per slide
+- **Code Blocks** - Best practices for technical content
+- **Multi-Column Layouts** - Organizing information effectively
+- **Image Layouts** - When and how to use images
+- **Technical Details** - Frontmatter, separators, and parameters
+
+---
+layout: section
+---
+
+# Presentation Structure
+
+## Opening, Sections, and Closing
+
+---
+layout: two-cols-header
+---
+
+# Cover vs Intro Layouts
+
+Both serve as introduction slides with different scope:
+
+::left::
+
+## Cover Layout
+
+**Use for main introductions:**
+
+- Multi-speaker presentations
+- Collection-style slide decks
+- Primary opening slide
+
+```markdown
+---
+layout: cover
+---
+
+# Workshop Title
+
+## Multiple Topics Inside
+```
+
+::right::
+
+## Intro Layout
+
+**Use for secondary introductions:**
+
+- Individual modules or sections
+- Single-topic presentations
+- Different author segments
+
+```markdown
+---
+layout: intro
+imageSrc: /image.png
+---
+
+# Module Introduction
+```
+
+---
+layout: two-cols-header
+---
+
+# Section & End Layouts
+
+Dividers and closings for clear structure:
+
+::left::
+
+## Section Layout
+
+**Mark transitions between topics:**
+
+```markdown
+---
+layout: section
+---
+
+# Module 2
+
+## Advanced Topics
+```
+
+Creates visual break and helps audience follow along.
+
+::right::
+
+## End Layout
+
+**Always close with this layout:**
+
+```markdown
+---
+layout: end
+---
+
+# Thank You!
+
+## Questions?
+```
+
+Professional closing with centered content.
+
+---
+layout: section
+---
+
+# Content Density
+
+## How Much Content Per Slide
+
+---
+
+# Default Layout Limits
+
+## Keep Content Focused
+
+Follow these limits for readable slides:
+
+- **Bullet points:** 5-7 items maximum
+- **Characters:** 500 recommended, 800 absolute maximum
+- **Headings:** H1 for title, H2 for subtitle, H3 for sub-points
+
+```markdown
+---
+layout: default
+---
+
+# Container Benefits
+
+## Key Advantages
+
+- Consistency across environments
+- Fast deployment and scaling
+- Resource efficiency
+```
+
+---
+layout: two-cols-header
+---
+
+# Good vs Bad Content
+
+::left::
+
+## ✅ Good Example
+
+### Docker Benefits
+
+- Consistent environments
+- Fast deployment
+- Resource efficiency
+- Easy scaling
+- Simple rollbacks
+
+*5 clear, concise points*
+
+::right::
+
+## ❌ Bad Example
+
+Too much content causes overflow:
+
+- Point 1 with lengthy explanation
+- Point 2 with even more detail
+- Points 3, 4, 5, 6, 7, 8, 9, 10...
+- Multiple paragraphs of text
+- Way more than 800 characters
+- Audience can't read it all
+- Information overload
+- Hi Mom!
+
+*Overloaded and unreadable*
+
+---
+layout: three-cols-header
+---
+
+# Short-Form Layouts
+
+Use these for emphasis and impact:
+
+::left::
+
+## Center
+
+Short, important messages:
+
+- 1-3 sentences max
+- ~300 characters
+- Key takeaways
+
+```markdown
+---
+layout: center
+---
+
+# Key Point
+
+One impacthat message
+```
+
+::middle::
+
+## Fact
+
+Statistics and metrics:
+
+- Single number focus
+- Supporting context
+- Visual emphasis
+
+```markdown
+---
+layout: fact
+---
+
+# 95%
+
+## use containers
+```
+
+::right::
+
+## Statement / Quote
+
+Bold statements:
+
+- Mission statements
+- Quotations
+- Core principles
+
+```markdown
+---
+layout: statement
+---
+
+# "IaC is the Future"
+```
+
+---
+layout: center
+---
+
+# Infrastructure as Code
+
+Enables consistency, automation, and version control
+
+*This slide demonstrates the center layout - short and impactful*
+
+---
+layout: section
+---
+
+# Code Blocks
+
+## Technical Content Best Practices
+
+---
+layout: two-cols-header
+---
+
+# Code Block Rules
+
+::left::
+
+## Guidelines
+
+- **Maximum 15 lines** per code block
+- **Always specify language** for highlighting
+- Split longer code across multiple slides
+- Use meaningful, focused examples
+
+Supported: Python, JavaScript, TypeScript, C#, Docker, Terraform, YAML, Bash, and 30+ more
+
+::right::
+
+## Proper Example
+
+```python
+def calculate_total(items):
+    """Calculate total price."""
+    total = 0
+    for item in items:
+        total += item.price
+    return total
+```
+
+Language specified, under 15 lines, focused purpose.
+
+---
+layout: two-cols-header
+---
+
+# Two-Column Code Limits
+
+**Critical: Maximum 56 characters per line in two-column layouts**
+
+::left::
+
+### ✅ Correct
+
+```python
+# Lines under 56 chars
+def old_way():
+    result = process()
+    return result
+```
+
+Short, readable lines that fit the column width.
+
+::right::
+
+### ❌ Wrong
+
+```python
+# This line is way too long!
+def function_with_very_very_very_very_very_very_long_name():
+    pass
+```
+
+Long lines overflow and break the layout.
+
+---
+layout: two-cols-header
+---
+
+# Code Mistakes to Avoid
+
+::left::
+
+## Missing Language
+
+```markdown
+❌ Bad - no highlighting:
+\```
+def hello():
+    return "World"
+\```
+
+✅ Good - proper highlighting:
+\```python
+def hello():
+    return "World"
+\```
+```
+
+::right::
+
+## Too Many Lines
+
+- More than 15 lines = hard to read
+- Split into multiple slides
+- Focus on the relevant portion
+- Add context in bullet points
+
+**Three-column code:** Even shorter lines required (~35-40 characters max)
+
+---
+layout: section
+---
+
+# Multi-Column Layouts
+
+## Organizing Information Effectively
+
+---
+layout: two-cols-header
+---
+
+# Two-Column Layouts
+
+This slide demonstrates `two-cols-header` - the recommended variant:
+
+::left::
+
+## When to Use
+
+- Comparisons (before/after)
+- Related but separate concepts
+- Pros and cons lists
+- Code with explanation
+
+**Prefer `two-cols-header`** over `two-cols` for better organization.
+
+::right::
+
+## Content Limits
+
+- ~400 characters per column
+- 5-7 bullet points per column
+- Code: 56 chars per line max
+- Keep columns balanced
+
+```markdown
+---
+layout: two-cols-header
+---
+
+# Title Spans Both
+```
+
+---
+layout: three-cols-header
+---
+
+# Three-Column Layouts
+
+Use `three-cols-header` for organizing related information:
+
+::left::
+
+## Development
+
+- Local setup
+- Unit testing
+- Code review
+- Version control
+
+*~250 chars max*
+
+::middle::
+
+## Staging
+
+- Integration tests
+- UAT environment
+- Performance tests
+- Security scans
+
+*3-5 bullets max*
+
+::right::
+
+## Production
+
+- Deployment
+- Monitoring
+- Scaling
+- Incident response
+
+*Code: ~35 chars/line*
+
+---
+layout: section
+---
+
+# Image Layouts
+
+## When and How to Use Images
+
+---
+layout: image-right
+imageSrc: https://sli.dev/demo-cover.png
+imageRatio: 40%
+---
+
+# Image-Left/Right Layouts
+
+**Use when:**
+
+- Displaying photos or screenshots
+- Adding visual interest
+- Showing diagrams with text
+
+**Parameters:**
+
+- `imageSrc` - Path to image
+- `imageRatio` - Width (30-50%)
+- `imageScale` - Scale within container
+- `imageAlign` - Vertical alignment
+
+*This slide uses `image-right`*
+
+---
+layout: two-cols-header
+---
+
+# Image Layout Modes
+
+The `image` layout has two modes:
+
+::left::
+
+## Background Mode
+
+Text overlays on the image:
+
+```markdown
+---
+layout: image
+imageSrc: /background.jpg
+imageBackgroundMode: true
+---
+
+# Title Over Image
+```
+
+Best for atmospheric backgrounds.
+
+::right::
+
+## Foreground Mode
+
+Image displayed below content:
+
+```markdown
+---
+layout: image
+imageSrc: /diagram.png
+imageBackgroundMode: false
+imageScale: 80%
+---
+
+# Diagram Title
+```
+
+Best for technical diagrams.
+
+---
+layout: section
+---
+
+# Technical Details
+
+## Frontmatter, Separators, and Parameters
+
+---
+layout: two-cols-header
+---
+
+# Frontmatter & Separators
+
+::left::
+
+## Opening Frontmatter
+
+Required fields for first slide:
+
+```yaml
+---
+theme: "@sp-days-framework/
+  slidev-theme-sykehuspartner"
+title: Presentation Title
+description: Brief description
+layout: cover
+---
+
+# First Slide
+```
+
+::right::
+
+## Slide Separators
+
+Always use proper formatting:
+
+```markdown
+---
+# First Slide
+
+Content here
+
+---
+layout: center
+---
+
+# Second Slide
+```
+
+- Use `---` with blank lines around
+- Frontmatter after `---`
+- Blank line before content
+
+---
+layout: two-cols-header
+---
+
+# Headings & Parameters
+
+::left::
+
+## Heading Hierarchy
+
+Consistent structure matters:
+
+- **H1 (`#`)** - Main slide title
+- **H2 (`##`)** - Subtitles, sections
+- **H3 (`###`)** - Sub-points
+
+```markdown
+# Main Title
+
+## Subtitle
+
+### Sub-point
+
+- Bullet details
+```
+
+::right::
+
+## Common Parameters
+
+Per-slide frontmatter options:
+
+| Parameter | Purpose |
+|-----------|---------|
+| `layout` | Slide layout type |
+| `logo` | Show/hide logo |
+| `textAlignment` | top, center, bottom |
+| `zoom` | Scale content |
+| `transition` | Slide transition |
+
+---
+layout: two-cols-header
+---
+
+# Speaker Notes
+
+Add notes visible only in presenter mode:
+
+::left::
+
+## Adding Notes
+
+```markdown
+---
+# Slide Title
+
+Visible content for audience
+
+<!--
+Speaker notes here:
+- Key point to emphasize
+- Questions to ask
+- Time: 2 minutes
+-->
+```
+
+::right::
+
+## Using Presenter Mode
+
+- Press "Presenter Mode" button
+- Opens second window with:
+  - Current slide
+  - Next slide preview
+  - Speaker notes
+  - Timer
+
+Perfect for rehearsing and presenting.
+
+<!--
+This is a speaker note example!
+Press 'o' to see presenter mode.
+-->
+
+---
+layout: two-cols-header
+transition: slide-left
+---
+
+# Transitions
+
+Add smooth animations between slides:
+
+::left::
+
+## Available Transitions
+
+- `slide-left` / `slide-right`
+- `slide-up` / `slide-down`
+- `fade` / `fade-out`
+- `zoom`
+- `none`
+
+*This slide uses `slide-left`*
+
+::right::
+
+## Usage
+
+**Per-slide:**
+```yaml
+---
+transition: slide-left
+---
+```
+
+**Global (first slide):**
+```yaml
+---
+theme: "..."
+transition: fade
+---
+```
+
+---
+layout: two-cols-header
+---
+
+# VSCode Icons
+
+The theme includes icons from Iconify VSCode Icons:
+
+::left::
+
+## Syntax
+
+Use in code block titles:
+
+````markdown
+/```docker [Dockerfile ~i-vscode-icons:file-type-docker~]
+FROM python:3.13
+/```
+
+/```python [app.py ~i-vscode-icons:file-type-python~]
+print("Hello!")
+/```
+````
+
+::right::
+
+## Examples
+
+```docker [Dockerfile ~i-vscode-icons:file-type-docker~]
+FROM python:3.13
+```
+
+```python [app.py ~i-vscode-icons:file-type-python~]
+print("Hello, World!")
+```
+
+```yaml [playbook.yml ~i-vscode-icons:file-type-ansible~]
+- name: Deploy app
+  hosts: servers
+```
+
+---
+layout: end
+---
+
+# Happy Presenting!
+
+## Questions?