Creating Geeks Club Presentations

What is Geeks Club?

Internal company meeting where developers present technical topics to other developers. Presentations share recent learnings, post-mortems, deep dives into technologies, patterns, or incidents. Tone is technical but approachable — think "conference talk for your team."

Repository conventions

Folder structure

Each presentation lives in a numbered folder at the repo root:

Presentations/
├── 1_CloudFlare/
│   ├── cloudflare_outage_2025.md          # Polish version (source)
│   ├── cloudflare_outage_2025_en.md       # English version (source)
│   ├── cloudflare_outage_2025.rendered.md  # Auto-generated
│   ├── cloudflare_outage_2025.html         # Auto-generated
│   └── assets/mermaid/                     # Auto-generated SVGs
├── 2_CancellationToken/
│   └── ...
├── N_TopicName/
│   ├── topic-name.md
│   ├── topic-name_en.md        # (optional English version)
│   └── assets/mermaid/

• •Increment the number prefix for each new presentation
• •Use PascalCase or descriptive name after the number prefix
• •Create assets/mermaid/ directory (pipeline stores rendered SVGs there)
• •Only create .md source files — .rendered.md, .html, .pdf are auto-generated by CI

File naming

• •<topic-name>.md — primary version (can be Polish or English)
• •<topic-name>_en.md — English translation (optional)
• •Never create .rendered.md files manually

Marp Markdown syntax essentials

Front-matter

Every presentation starts with YAML front-matter:

---
marp: true
theme: default
paginate: true
---

Slide separation

Use horizontal rulers (---) to separate slides. An empty line before --- is recommended.

Directives

• •Global (apply to whole deck): theme, style, headingDivider
• •Local (apply to current + following slides): paginate, header, footer, class, backgroundColor, color
• •Spot (apply to single slide only): prefix with _, e.g. _class: lead, _paginate: false

Directives can be set in front-matter or HTML comments:

<!-- _class: lead -->
# This slide uses lead class

Presenter notes

Use HTML comments at the end of each slide. These appear in presenter view and are NOT shown to the audience:

# Slide Title

Content here.

<!--
Your presenter notes here.
Use bullet points for easy reading during delivery.
-->

Images

Marp extends standard Markdown image syntax:

• •![bg](image.jpg) — background image
• •![bg right](image.jpg) — split slide with image on right
• •![bg left:40%](image.jpg) — split with custom ratio
• •![width:300px](image.jpg) — resize

Presentation template

Use this dark theme template. It matches the established Geeks Club visual identity:

---
marp: true
theme: default
paginate: true
backgroundColor: #1a1a2e
color: #eaeaea
style: |
  section {
    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
  }
  h1 {
    color: #f77f00;
  }
  h2 {
    color: #fcbf49;
  }
  h3 {
    color: #eae2b7;
  }
  code {
    background-color: #2d2d44;
    color: #00d9ff;
  }
  a {
    color: #00d9ff;
  }
  .mermaid {
    background-color: transparent;
  }
  .mermaid svg {
    max-height: 350px;
    width: auto;
  }
  section img[alt="mermaid diagram"] {
    max-height: 350px;
    width: auto;
    display: block;
    margin: 0 auto;
  }
  strong {
    color: #f77f00;
  }
  blockquote {
    border-left: 4px solid #f77f00;
    background-color: #2d2d44;
    padding: 1em;
  }
  section.compact {
    font-size: 0.9em;
  }
  section.compact h1 {
    margin-bottom: 0.2em;
  }
  section.compact h3 {
    margin-top: 0.6em;
  }
  section.compact table {
    font-size: 0.7em;
  }
  section.compact ul {
    margin-top: 0.3em;
    font-size: 0.9em;
  }
  section.compact blockquote {
    margin-bottom: 0.6em;
  }
  table {
    font-size: 0.8em;
    color: #1a1a2e;
  }
  th {
    background-color: #f77f00;
    color: #1a1a2e;
  }
  svg foreignObject section table th,
  svg foreignObject section table td,
  section table th,
  section table td {
    color: #000000 !important;
  }
---

<style>
  table, table th, table td { color: #000000 !important; }
</style>

# 🔥 Presentation Title
## Subtitle or Hook

**Geeks Club**

📅 [Date]

<!--
Opening presenter notes — set context for the talk.
-->
---

# 📋 Agenda

1. 🌐 **Topic 1** — Brief description
2. 💥 **Topic 2** — Brief description
3. 🔧 **Topic 3** — Brief description
4. 📝 **Conclusions**
5. 💭 **Discussion**

---

<!-- Slide content follows... -->

Slide design patterns

Use emoji in headings for visual navigation

# 🔥 Problem Description
# 📊 Data Analysis
# 🧪 Testing Approach
# 🎯 Summary
# 🤔 For Discussion

Mermaid diagrams

Use fenced code blocks with mermaid language. Supported types: flowchart, sequenceDiagram, timeline, mindmap, classDiagram, stateDiagram-v2, erDiagram, gantt.

```mermaid
flowchart LR
    A[👤 User] --> B[🛡️ Service]
    B --> C[📦 Database]
`` `

Custom dimensions via comments inside the block:

```mermaid
%% width: 600
%% height: 400
flowchart LR
    A --> B --> C
`` `

Keep diagrams simple — max ~8 nodes per diagram for readability on slides. Use emoji in node labels.

Code blocks

Use standard fenced code blocks with language identifiers:

```rust
fn main() {
    println!("Hello Geeks Club!");
}
```

Tables

Tables render with dark text on light background (ensured by the CSS template):

| Category | Detail |
|----------|--------|
| 🏢 Technology | Rust, ClickHouse |
| 📊 Scale | 16% of internet |

Blockquotes for key quotes or callouts

> "Today's outage was the most serious incident since 2019"
> — Matthew Prince, CEO

Compact class for dense slides

When a slide has too much content to fit on screen (e.g. large tables, many bullet points, or combined headings + table + list), apply the compact class to reduce font sizes and margins:

<!-- _class: compact -->
# Slide with Lots of Content

| Column A | Column B |
|----------|----------|
| ... | ... |

Important: Marp puts _class on the <section> element itself, so compact styles must use section.compact (no space) in CSS — not .compact (descendant selector). The template already includes the correct selectors.

Prefer splitting content across multiple slides. Use compact only when splitting would break the logical flow.

Spot directive for special slides

<!-- _class: lead -->
# Centered Title Slide

Use _paginate: false on title slides to hide page numbers.

Recommended slide structure

A typical Geeks Club presentation follows this flow:

1. •Title slide — topic, subtitle/hook, "Geeks Club", date
2. •Agenda — numbered list with emoji, 4–6 items
3. •Context/Background — why this topic matters (2–3 slides)
4. •Core content — technical deep dive with diagrams and code (6–12 slides)
5. •Key lessons / Conclusions — numbered takeaways (1–2 slides)
6. •Discussion questions — 3–5 questions for the team
7. •Summary — mindmap or visual recap
8. •Sources — links to articles, videos, documentation
9. •Thank you + Q&A — contact info, ASCII art optional

Target: 15–25 slides total. Each slide should be digestible in 1–2 minutes.

Presenter notes guidelines

• •Add notes to every slide (especially technical ones)
• •Use bullet points for easy scanning during delivery
• •Include: talking points, context not on slides, transition cues, audience interaction prompts
• •Mark audience questions with "Ask:" prefix

<!--
- Explain the background on this technology
- Mention we use this internally in Project X
- Ask: has anyone encountered this issue?
-->

Building locally

See docs/marp-local-development.md for setup.

Quick commands:

# Live preview
marp --watch --preview "N_TopicName/topic-name.md"

# Pre-render mermaid + generate HTML
node .github/scripts/render-mermaid.js "N_TopicName/topic-name.md" "N_TopicName/topic-name.rendered.md"
marp "N_TopicName/topic-name.rendered.md" -o "N_TopicName/topic-name.html"

CI pipeline

The GitHub Actions workflow (.github/workflows/convert-md.yml) automatically:

1. •Detects changed .md files (ignoring .rendered.md, README.md, docs/)
2. •Pre-renders Mermaid diagrams via render-mermaid.js
3. •Generates .rendered.md, .html, and .pdf
4. •Commits artifacts back to the repo

No manual action needed — just push the .md source file.