Markdown-based Slides

Writing NERSC Slide Decks in Markdown

Documentation and Tutorial

Nestor Demeure
National Energy Research Scientific Computing Center, Berkeley CA, United States

Can we write slides in Markdown?

(And why bother?)

Marp!

These slides are produced with Marp!

  • Written in Markdown,
  • Compiled to HTML / PDF / PPTX / etc.,
  • Using a custom CSS style, following my NERSC theme.

Marp is customizable, but focuses on raw Markdown syntax.

Why bother?

Motivations

Markdown is Code

Version Control

Bringing version control to shared slide decks:

  • Keeping a history of all previous versions,
  • Branches,
  • Issues,
  • Pull requests.

Particularly interesting for shared long-lived decks (user training?).

Accessible to Coding Assistants

Easily modified by coding assistants (i.e., Claude Code):

  • Grammar / spell check,
    "Make sure I used the same acronym on all slides."
  • Deck-wide modifications,
    "We reran everything on this new hardware, update the specs slide and all corresponding mentions."
  • Complex content,
    "Here is a CSV, integrate a violin plot of the data, colored by the Framework column."
  • Translation.
    "Translate this workshop from English to French."

Great to write slides while holding a baby in one hand!

Markdown is Code

All benefits of dealing with code apply:

  • Fitting the tool to our specific needs,
    Integrate code, formulas, plots, etc.
  • Standardizing style over all slide decks,
    And keep it up to date.
  • Testing code blocks at build / push time.
    The Rust documentation does that, do we want to?

No limits to our pre/post-processing abilities.

What can we do?

Marp

Syntax and Capabilities

Marp

Marp slides are written as a --- separated Markdown file.

You can define various slide types and styles in CSS.

And plug into its JavaScript compiler to add advanced capabilities.

# Marp

Marp slides are written as a `---` separated **Markdown file**.

You can define various slide types and **styles in CSS**.

And plug into its **JavaScript compiler** to add advanced capabilities.

Pictures

The Doudna supercomputer is already accelerating innovation:

# Pictures

[**The Doudna supercomputer**](https://www.nersc.gov/what-we-do/computing-for-science/doudna-system) is already accelerating innovation:

![w:550](https://raw.githubusercontent.com/nestordemeure/nersc_markdown_slides/refs/heads/main/slide_decks/docs/images/doudna.jpg)

Code

With syntax highlighting!

# Import JAX
import jax.numpy as jnp
from jax import random

# Create random matrices
key = random.PRNGKey(42)
A = random.normal(key, (1000, 1000))
B = random.normal(key, (1000, 1000))

# Matrix multiplication
C = jnp.dot(A, B)
print(f"Result shape: {C.shape}")

# Code

With **syntax highlighting**!

'''python
# Import JAX
import jax.numpy as jnp
from jax import random

# Create random matrices
key = random.PRNGKey(42)
A = random.normal(key, (1000, 1000))
B = random.normal(key, (1000, 1000))
'''

Formulas

The time-dependent Schrödinger equation in MathJax:

# Formulas

The *time-dependent Schrödinger equation* in [**MathJax**](https://www.mathjax.org/):

$$i\hbar\frac{\partial}{\partial t}\Psi(\mathbf{r},t) = \hat{H}\Psi(\mathbf{r},t)$$

Plots

Generated from a CSV file, easily updated!

# Plots

Generated **from a CSV file**, easily updated!

<iframe src="images/jax_kernel_sizes.html" width="100%" height="500" frameborder="0"></iframe>

Diagrams

  • Mermaid is possible, but people report troubles with it...
  • SVG, and embedded HTML work out of the box:

# Diagrams

- **Mermaid** *is* possible, but people report troubles with it...
+ **SVG**, and **embedded HTML** work out of the box:  

<iframe style="width:100%; border:none;" src="images/jax_xla_schematics.html"></iframe>

And More!

  • Anything you can do in HTML, you can embed in an iframe,
    • Diagrams,
    • Plots,
    • etc.
  • The syntax can be extended by plugging-in the compiler.
    • Colored pro / con bullets,
    • Special QR codes syntax,
    • etc.

Check the Full Code

qr

# Check the Full Code

![qr width:400px](https://github.com/nestordemeure/nersc_markdown_slides/blob/main/slide_decks/docs/slides.md)

Okay, what are we losing?

Shortcomings

  • No real-time interactions,
    • No Google Slides-style interactions.
  • Limited control on item placement,
    • No last minute overlay of a block of text,
    • Standardized "good" defaults out of the box.
  • Less approachable to non-technical people,
    • Compiled,
    • Git versioned,
    • Markdown.
  • Some benefits do not apply to private decks.
    • HTML export expects publicly accessible images,
    • Coding assistant should not be run on non-disclosure agreement decks,
    • it does work fully offline.

Conclusion

Overview and Perspectives

Overview

It works!

Perspectives

This is very much a proof of concept:

  • Porting other people's slides would be a good exercise in feasibility,
  • We should put together an official(-looking) theme,
  • Feel free to play with it, submit issues and PRs!

Thank you!

https://github.com/nestordemeure/
nersc_markdown_slides

ndemeure@lbl.gov