MkSlides Documentation

The mkslides assets directory uses git submodules for highlight.js and reveal.js. To update these submodules to specific versions (tags), follow these steps:

1. Navigate into the specific submodule directory.
2. Fetch available tags.
3. Checkout the desired tag.
4. Repeat for other submodules.
5. From the root of the mkslides repository, stage the changes to the submodules so the new commits are recorded in the main repository.

# Update highlight.js to a specific tag
cd src/mkslides/assets/highlight.js
git fetch --tags
git checkout tags/11.11.1

# Update reveal.js to a specific tag
cd src/mkslides/assets/reveal.js
git fetch --tags
# (Optional: git checkout tags/<version>)

# Return to the main repository and stage the submodule updates
cd src/
git add src/mkslides/assets/highlight.js src/mkslides/assets/reveal.js

Use mkslides serve to start a local development server with live reloading. This allows you to see changes in your Markdown files reflected in the browser immediately.

mkslides serve
mkslides serve somefolder/
mkslides serve test.md

WARNING

Similar to the build command, using a single file as the PATH limits asset copying. Use a folder if you need custom assets.

Install the mkslides package using pip to begin building static HTML slideshows from Markdown files.

pip install mkslides

Use the mkslides build command to generate static HTML slideshows from Markdown files.

• Build from a folder: If your Markdown files are in a folder (e.g., slides/), run mkslides build slides/. This will create a collection of slideshows with an index landing page.
• Build from a single file: Run mkslides build test.md to turn one file into a single slideshow.
• Default behavior: If no path is provided, it looks for a slides/ folder, then falls back to a docs/ folder.

WARNING

When using a single file as the PATH, only default static assets are copied. To include custom images or other files, use a folder as the PATH instead.

mkslides build
mkslides build somefolder/
mkslides build test.md

When using Markdown files as slides, you can use YAML frontmatter to override specific settings. Only the following keys are permitted in the frontmatter:

• slides
• revealjs
• plugins

MkSlides allows you to extend its behavior by providing a custom preprocessing script. To do this, create a Python file that defines a function named preprocess. This function must accept a single string argument (the content to be processed) and return a string (the processed content).

When MkSlides loads your script, it looks specifically for the preprocess function. If the function is missing or the script cannot be loaded, an error will be raised.

def preprocess(content: str) -> str:
    # Perform transformations on the content
    new_content = content.replace("OLD_TOKEN", "NEW_TOKEN")
    return new_content

You can customize the appearance and behavior of both the generated index page and the individual slides using a mkslides.yml configuration file.

Customization Options

Index Page

• Theme: Local file path or public URL.
• Favicon: Local file path or public URL.
• Title: The title of the index page.
• Template: Custom HTML template for the output page.

Slides

• Theme: A Reveal.js theme, local file, or public URL.
• Highlight.js Theme: A Highlight.js theme, local file, or public URL.
• Favicon: Local file path or public URL.
• Title: The title of the slide.
• Template: Custom HTML template for the output page.

You can enable or disable the footer text "Documentation built with MkSlides." in your configuration.

Key:

• boolean: Set to true to show or false to hide the footer.

You can override slides, revealjs, and plugins settings directly within a Markdown file using YAML frontmatter. This is useful for per-slide customization.

---
slides:
    theme: solarized
    highlight_theme: vs
    separator: <!--s-->
    title: Frontmatter title.
revealjs:
    height: 1080
    width: 1920
    transition: zoom
---

# Slides with frontmatter

<!--s-->

## Content
...

---
slides:
    theme: solarized
    highlight_theme: vs
    separator: <!--s-->
    title: Frontmatter title.
revealjs:
    height: 1080
    width: 1920
    transition: zoom
---

# Slides with frontmatter

<!--s-->

## Lorem ipsum

Lorem ipsum...

You can extend MkSlides using the plugins list. Each plugin entry allows you to inject additional assets into the generated slides.

Each plugin object supports:

• name: The name of the plugin (string or null).
• extra_css: A list of additional CSS file paths to include (list of strings or null).
• extra_javascript: A list of additional JavaScript file paths to include (list of strings or null).

The slides configuration section controls how the Reveal.js slides are rendered and processed.

Available keys:

• charset: Character encoding (string or null).
• favicon: Path to the slide favicon (string or null).
• highlight_theme: The theme for code syntax highlighting (string, defaults to "monokai").
• preprocess_script: Path to a script to run before preprocessing (string or null).
• separator_notes: String used for note separators (string or null).
• separator_vertical: String used for vertical slide separators (string or null).
• separator: String used for horizontal slide separators (string or null).
• template: The template to use (string or null).
• theme: The Reveal.js theme name (string, defaults to "black").
• title: The title of the slides (string, defaults to "Slides").