Hugo-WebSlides

Hugo-WebSlides is a Hugo theme for authoring WebSlides.js presentations entirely in Markdown, turning plain-text slide files into interactive HTML slideshow decks.

What is Hugo-WebSlides?

Hugo-WebSlides is an open-source theme for the Hugo static site generator. It takes Markdown files as input and outputs a WebSlides.js-based presentation in HTML, CSS, and JavaScript. The theme is maintained by RCJacH and is published on GitHub under the repository rcjach/hugo-webslides.

Key Features

• Markdown-based slide creation — Write each slide in Markdown and separate slides with a horizontal ruler --- on its own line.
• Class assignment without HTML — Assign CSS classes to slides and elements using a colon-prefixed syntax inside HTML comments, supporting multiple classes for sections, divs, secondary divs, and background elements.
• WebSlides.js foundation — Built on the WebSlides.js library, bringing the full set of WebSlides components and navigation behaviors to your deck.
• Configurable slideshow behavior — Toggle banner, vertical mode, autoslide, change-on-click, loop, wheel delta, scroll navigation, scroll wait, and slide offset via [params.webslides] in config.toml.
• Shortcode components — The theme provides shortcodes for reusable components, with more component shortcodes listed as a future implementation.
• Example site included — The repository includes a fully configured exampleSite folder, previewable with hugo serve --themesDir ../...

Who is it for?

Hugo-WebSlides suits developers, technical writers, and Hugo users who want to produce presentation decks without leaving their Markdown workflow. Use it to keep slide content in version control, generate presentations via the Hugo build pipeline, and deploy them as static sites. It is also useful for workshop instructors and conference speakers who need a lightweight, code-friendly alternative to WYSIWYG presentation tools.

What can you do with it?

• Create a slide deck from Markdown: Write slides in a Markdown file, separate them with ---, and run Hugo to generate a presentation.
• Customize slide layout: Add classes for section, div, background, and background-image properties using the comment-based assignment syntax.
• Preview and iterate: Run the example site locally or host the output on any static host, since the theme produces plain HTML, CSS, and JavaScript.
• Reuse components: Leverage existing shortcodes for UI elements, with additional component shortcodes on the roadmap.

How does it work?

Install Hugo, then clone or add the theme as a git submodule into the themes/hugo-webslides directory. Copy the exampleSite's content folder into your project, edit the Markdown files, and split slides with ---. Configure slideshow options in config.toml under [params.webslides], using the same parameter names as the WebSlides Core API but with the loop, navigateOnScroll, and showIndex options inverted (disabling them via disableLoop, disableNavigateOnScroll, and hideIndex).

FAQ

How do I start a new presentation with Hugo-WebSlides?

Clone the repository into your Hugo site's themes folder, copy the exampleSite content directory into your project, and modify the existing Markdown files.

How do I split slides?

Place a horizontal ruler --- on its own line between slides in a Markdown file. Each block separated by --- becomes one slide.

How do I assign classes to a slide or element?

Use an HTML comment that starts with a colon followed by the class name or a property assignment. For slide-level properties, specify section class, div class, secondary div class, background class, background image, or background image position; block-level classes can be attached to headings and paragraphs.

What configuration options does the theme support?

The theme exposes WebSlides Core API options under [params.webslides] in config.toml, including banner, slideshow, vertical, autoslide, changeOnClick, disableLoop, minWheelDelta, disableNavigateOnScroll, scrollWait, slideOffset, and hideIndex. Some options are inverted in the theme's configuration.

Does the theme require a specific Hugo version?

The installation guide recommends the latest version of Hugo, so using an up-to-date Hugo release is advised.