gatsby-theme-slidedeck is a Gatsby theme that generates a navigable slide-deck website from Markdown/MDX files, with each .deck.mdx file in the deck directory becoming its own presentation.
What is gatsby-theme-slidedeck?
Gatsby theme that takes .deck.mdx files as input and outputs a static site where every slide has its own route (e.g., /my-presentation/1). It is built on Gatsby's theme system, uses MDX for content, and is styled with Theme UI through gatsby-plugin-theme-ui. The theme was created by FLGMwt for the Gatsby Theme Jam and is distributed with a companion starter, gatsby-starter-slidedeck-theme.
Key Features
- Markdown-driven decks — Write presentations in
.deck.mdxfiles using standard Markdown plus thegatsby-slidedelimiter on its own line to split content into multiple slides. - Keyboard navigation — Right arrow or L goes to the next slide, left arrow or H goes back, R resets to the first slide, and Q returns to the deck index.
- Touch and swipe support — Swipe left or right on touch-enabled devices to navigate slides.
- Component shadowing — Override any theme component (for example,
slideHeader.js) by dropping a file insrc/gatsby-theme-slidedeck/, following Gatsby's component shadowing convention. - Theme UI integration — Colors, type, and layout come from
gatsby-plugin-theme-uiand can be customized via the project's theme configuration. - Automatic deck index — The site root displays a list of all decks; you can also replace it by defining your own
src/pages/index.js. - Accessible components — The bundled button and menu components are styled and keyboard-accessible, and the layout sets viewport width and height for full-screen slides.
- Configurable shortcuts — Keyboard bindings live in
utils/useShortcuts/config.jsand can be shadowed to change or disable shortcuts.
Who should use gatsby-theme-slidedeck?
- Developers who want to version-control presentations as Markdown, diff slide changes, and deploy a static slide site with Gatsby.
- Technical speakers who want to write code-dense slides with MDX and reuse Gatsby's ecosystem for code highlighting and theming.
- Technical writing teams that maintain a collection of slide decks side by side in one repository and need a single index page to browse them.
Use cases
Conference talks: Author a deck in .deck.mdx, split slides with the gatsby-slide delimiter, and push to a Gatsby-powered site for sharing.
Workshop material: Maintain multiple training decks in one project; every deck gets its own route and appears on the index page.
Internal presentations: Build a lightweight company presentation site where each member can drop a .deck.mdx file and get a navigable deck with keyboard controls.
How does gatsby-theme-slidedeck work?
Install the starter with gatsby new my-slidedeck-site https://github.com/FLGMwt/gatsby-starter-slidedeck-theme. Add a .deck.mdx file under the deck directory and insert the text gatsby-slide on its own line to start a new slide. Running npm run develop generates the slides and index pages, and the theme's layout captures viewport size so touch events work across the whole screen.
Pros and cons
Pros:
- Markdown authoring means decks are easy to version, review, and diff.
- Component shadowing allows deep customization without forking the theme.
- Built-in keyboard and swipe navigation require no extra JavaScript.
Cons (limitations noted by the author):
- Slides are separate full page loads; there are no smooth transitions.
- Touch swipe handling uses viewport sizing that can cause scrollbars if components are shadowed.
- Swipe events are not yet blocked when scrolling inside wider
preblocks. - Deck/slide generation relies on a file-node hack the author describes as suboptimal.
FAQ
How do I add a new slide to a deck?
Inside a .deck.mdx file, place the text gatsby-slide on its own line between content blocks. Each separated block becomes a slide, and the URL increments per slide: /my-presentation/1, /my-presentation/2, and so on.
What keyboard shortcuts are available?
The default bindings are L or Right Arrow for next, H or Left Arrow for previous, R to reset to the first slide, and Q to return to the deck list. You can change them by shadowing utils/useShortcuts/config.js, which exports the key-code arrays.
Can I customize the appearance?
The theme uses Theme UI, so you can edit color and typography settings through gatsby-plugin-theme-ui configuration. For larger changes, use Gatsby component shadowing by placing a file with the same name under src/gatsby-theme-slidedeck/.
Does it support touch navigation?
Yes, swiping left or right on a touch screen moves between slides. The root layout is sized to the viewport to capture these swipes anywhere, which the author notes may introduce scrollbars when components are shadowed.
Is there a starter template?
Yes, run gatsby new my-slidedeck-site https://github.com/FLGMwt/gatsby-starter-slidedeck-theme to scaffold a project. The starter comes preconfigured with the theme and a sample deck.
