Use
mkslidesEasily turn Markdown files into beautiful slides using the power of Reveal.js!
MKSlides is a static site generator ready to create slideshows. Slideshow source files are written in Markdown, and configured with a single YAML configuration file. The workflow and commands are largely inspired by MkDocs and manifest-md.
- Create static HTML slideshow files from Markdown files.
- Convert a single Markdown file to an HTML slideshow.
- Turn the folder containing Markdown files into a collection of HTML slideshows with an index landing page.
- Publish your slideshow anywhere static files can be served.
- Locally on your own device.
- On a web server.
- Deploy via CI/CD with GitHub/GitLab (like this repo!).
- Preview your site while you work, thanks to Python-livereload.
- Use custom favicons, CSS themes, templates, … if desired.
- Emoji support 😄 🚀 🚀
- Relies heavily on integration/unit tests to prevent regressions.
- And more!
Example slides from https://martenbe.github.io/mkslides with Dracula theme:
Example index page from https://hogenttin.github.io/hogent-markdown-slides with HOGENT theme, custom title and custom background logo:
Example output when creating a website:
Example output when using Live Preview during editing:
Long Video:
Need more examples? An example repo with slides demonstrating all the possibilities (Mermaid.js and PlantUML support, multicolumn slides, image resizing, …) using Reveal.js with the HOGENT theme can be found at https://github.com/HoGentTIN/hogent-markdown-slides.
For example when your markdown files are located slides/ folder:
If slides The folder does not exist, it will return docs For backward compatibility. If docs also does not exist, it will error.
For example when your markdown files are located somefolder/ folder:
mkslides build somefolder/
For example, when you have a single markdown file test.md,
PATHOnly the default static assets will be copied to the output folder. If you want to include images or other files, create a folder instead and pass it as PATHuse a file as PATH Its purpose is to create quick slideshows in a pinch using only text.
The commands for live preview are the same as for creating a static website.
mkslides serve
mkslides serve somefolder/
mkslides serve test.md
mkslides build -h
mkslides serve -h
just make one mkslides.ymlAll options are optional, you only need to add the ones you want to change mkslides.ymlRelative file paths are considered relative to the directory containing the Markdown files (PATH,
Here is an example demonstrating all the possible options in a configuration file:
# Configuration for the generated index page
index:
# Enables or disables the "Documentation built with MkSlides." footer:
# boolean
enable_footer: true
# Favicon of the generated index page: file path or public url to favicon
# file
favicon: example-index-favicon.ico
# Navigation section describing how to structure the slides on the index
# page. This is similar to the `nav` option from MkDocs: list[any]
nav:
- Example: example1.md
- "Example 2": somewhere/example1.md
- example3.md
- somewhere/example4.md
- "More examples":
- example5.md
- "Much more examples":
- "Last example": somewhere/much/more/examples/example6.md
# Title of the generated index page: string
title: example-title
# Jinja 2 template to generate index HTML: file path to Jinja2 file
template: example.jinja
# Theme of the generated index page: file path or public url to CSS file
theme: example-index-theme.css
# Configuration for the slides
slides:
# Charset of the slides: string
# (see https://revealjs.com/markdown/#external-markdown)
charset: utf-8
# Favicon of the slides: file path or public url to favicon file
favicon: example-slides-favicon.ico
# Theme for syntax highlighting of code fragments on the slides: file path
# to CSS file, public url to CSS file, or one of the highlight.js built-in
# themes such as `monokai`, `obsidian`, `tokyo-night-dark`, `vs`, ...
# (see https://highlightjs.org/examples)
highlight_theme: example-slides-highlight-theme.css
# Relative path to a python script containing a function
# Callable[[str], str] named `preprocess`. Important: a relative file path
# here is considered relative to the configuration file, as you probably
# don't want to serve the python scripts.
# For each Markdown file, the whole file content is given to the function as
# a str. The returned string is then further processed as the Markdown to
# give to Reveal.js
preprocess_script: tests/test_preprocessors/replace_ats.py
# Separator to determine notes of the slide: regexp
# (see https://revealjs.com/markdown/#external-markdown)
separator_notes: "^Notes?:"
# Separator to determine end current/begin new vertical slide: regexp
# (see https://revealjs.com/markdown/#external-markdown)
separator_vertical: ^\s*-v-\s*$
# Separator to determine end current/begin new slide: regexp
# (see https://revealjs.com/markdown/#external-markdown)
separator: ^\s*---\s*$
# Jinja 2 template to generate index HTML: file path to Jinja2 file
template: ./example.jinja
# Theme of the slides: file path to CSS file, public url to CSS file, or one
# of the reveal.js themes such as `black`, `white`, `league`, `solarized`,
# `dracula`, ... (see https://revealjs.com/themes/)
theme: example-slides-theme.css
# Title of the slides. If this is set for a slide, it will be used for the
# entry in the generated index HTML: string
title: example-title
# Options to be passed to reveal.js: options in yaml format, they will be
# translated to JSON automatically (see https://revealjs.com/config/)
revealjs:
height: 1080
width: 1920
transition: fade
example_plugin:
example_plugin_option_A: true
example_plugin_option_B: qwerty
# Plugins or additional CSS/JavaScript files for the slides. These are given as
# a list.
plugins:
# Name of the plugin (optional, see plugin README): plugin id string
# (see https://revealjs.com/creating-plugins/#registering-a-plugin)
- name: RevealExamplePlugin
# List of CSS files of the plugin (optional, see plugin README):
# public url to CSS file per entry
extra_css:
- https://cdn.jsdelivr.net/npm/reveal.js-example-pluging/example.min.css
# List of JavaScript files of the plugin (optional, see plugin README):
# public url to JavaScript file per entry
extra_javascript:
- https://cdn.jsdelivr.net/npm/reveal.js-example-pluging/example.min.js
- name: RevealMermaid
extra_javascript:
- https://cdn.jsdelivr.net/npm/reveal.js-mermaid-plugin/plugin/mermaid/mermaid.min.js
- extra_javascript:
- https://cdn.jsdelivr.net/npm/reveal-plantuml/dist/reveal-plantuml.min.js
Default configuration (used even if no configuration file exists):
index:
enable_footer: true
template: assets/templates/index.html.jinja # Comes with the pip package
title: Index
slides:
highlight_theme: monokai
template: assets/templates/slideshow.html.jinja # Comes with the pip package
theme: black
revealjs:
history: true
slideNumber: c/t
It is also possible to override slides, revealjsAnd plugins Using its Frontmatter option on a per markdown file basis. Here, relative file paths are considered relative to the Markdown file itself.
---
slides:
theme: solarized
highlight_theme: vs
separator:
title: Frontmatter title.
revealjs:
height: 1080
width: 1920
transition: zoom
---
# Slides with frontmatter
## Lorem ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
notes:
titleThe only Frontmatter available option here is to set the title of this slideshow in the generated index page. This option is not availablemkslides.yml,- Priority is in front>
mkslides.yml> Default.
Usage: mkslides [OPTIONS] COMMAND [ARGS]...
MkSlides - Slides with Markdown using the power of Reveal.js.
Options:
-V, --version Show the version and exit.
-v, --verbose Enable verbose output
-h, --help Show this message and exit.
Commands:
build Build the MkSlides documentation.
serve Run the builtin development server.
Usage: mkslides build [OPTIONS] [PATH]
Build the MkSlides documentation.
PATH is the path to the directory containing Markdown files. This argument
is optional and will default to 'slides', or 'docs' if the first directory
doesn't exist. If PATH is a single Markdown file or a directory containing a
single Markdown file, it will always be processed into `index.html`
regardless the name of the Markdown file.
Options:
-f, --config-file FILENAME Provide a specific MkSlides-Reveal config file.
-d, --site-dir PATH The directory to output the result of the slides
build. All files are removed from the site dir
before building.
-s, --strict Fail if a relative link cannot be resolved,
otherwise just print a warning.
-h, --help Show this message and exit.
Usage: mkslides serve [OPTIONS] [PATH]
Run the builtin development server.
PATH is the path to the directory containing Markdown files. This argument
is optional and will default to 'slides', or 'docs' if the first directory
doesn't exist. If PATH is a single Markdown file or a directory containing a
single Markdown file, it will always be processed into `index.html`
regardless the name of the Markdown file.
Options:
-f, --config-file FILENAME Provide a specific MkSlides-Reveal config file.
-s, --strict Fail if a relative link cannot be resolved,
otherwise just print a warning.
-a, --dev-addr IP address and port to serve slides locally.
-o, --open Open the website in a Web browser after the
initial build finishes.
-h, --help Show this message and exit.
<a href