pandoc-md-slides

A Pandoc filter to convert markdown notes to markdown slides

This pandoc filter converts markdown notes (written in plain prose) into summarized slides. The filter automatically splits long slides and resolves image target paths to new paths.

Installing using cabal

You can install the package by unpacking the tarball distributable in the releases page and running cabal install

tar -xvf pandoc-md-slides-<version>.tar.gz
cd pandoc-md-slides-<version>
cabal install

Basic Usage

pandoc test.md --filter md-slides -o outputs/output.md

Transformations

Paragraph Blocks

Paragraph blocks are split based on newlines and summarized into a BulletList. The resulting list will only keep important sentences (i.e. sentences with emphasized words and/or strong words).

Separate paragraphs will be placed in separate slides. Only top-level paragraph blocks are transformed into lists.

## Header

This is a paragraph block.
That contains **important sentences**.
And unimportant sentences.
It will keep the *important ones*.
The header will be used as a *slide header*.

Separate Paragraphs will be placed in *separate slides*.
Like *this one*.
Paragraphs with no headers will use the *most recent* headers as slide headers.

# Header

- That contains **important sentences**.
- It will keep the *important ones*.
- The header will be used as a *slide header*.

---

# Header

- Separate Paragraphs will be placed in *separate slides*.
- Like *this one*.
- Paragraphs with no headers will use the *most recent* headers as slide
  headers.

Splitting slides

Long slides are split into multiple slides, if the blocks can be split. Blocks that can be split are, bullet lists (including the transformed summarized paragraphs), ordered lists, display math blocks, code, table.

You can configure the split behavior by controlling the slide lines (-l) and line width (-w) arguments. A slide is split if it exceeds the slide lines. The number of lines of a slide is calculated based on the slide type and line width argument.

pandoc -t json test.md | \
    md-filter -l 6 -w 60 | \
    pandoc -f json \
    -t markdown-simple_tables-multiline_tables-grid_tables \
    -o outputs/output.md

The following default values will be used if the arguments are not set.

• slide lines (-l) - 6
• line width (-w) - 100

## Header

- item1
- item2
- item3
- item4
- item5
- item6
- item7
- item8
- item9
- item10
- item11
- item12
- item13

# Header

- item1
- item2
- item3
- item4
- item5
- item6

---

# Header

- item7
- item8
- item9
- item10

---

# Header

- item11
- item12
- item13

Math

When display math blocks are split, the display math is split based on math newlines (\\), ignoring newlines on matrix and bmatrix environments.

If the entire display math block are in an aligned environment, the split slides will inherit the aligned environment.

## Header

$$
\begin{aligned}
{n \choose r-1}+{n \choose r}&=\frac{n!}{(r-1)!(n-(r-1))!}+\frac{n!}{r!(n-r)!}\\
&=\frac{n!}{(r-1)!(n-r+1)!}+\frac{n!}{r!(n-r)!}\\
&=\frac{n!r}{r!(n-r+1)!}+\frac{n!(n-r+1)}{r!(n-r+1)!}\\
&=\frac{n!r+n!(n-r+1)}{r!(n-r+1)!}\\
&=\frac{n!(n+1)}{r!(n+1-r)!}\\
&=\frac{(n+1)!}{r!(n+1-r)!}\\
{n \choose r-1}+{n \choose r}&={n+1 \choose r}
\end{aligned}
$$

# Header

$$
\begin{aligned}
{n \choose r-1}+{n \choose r}&=\frac{n!}{(r-1)!(n-(r-1))!}+\frac{n!}{r!(n-r)!}\\
&=\frac{n!}{(r-1)!(n-r+1)!}+\frac{n!}{r!(n-r)!}\\
&=\frac{n!r}{r!(n-r+1)!}+\frac{n!(n-r+1)}{r!(n-r+1)!}\\
&=\frac{n!r+n!(n-r+1)}{r!(n-r+1)!}
\end{aligned}
$$

---

# Header

$$
\begin{aligned}
&=\frac{n!(n+1)}{r!(n+1-r)!}\\
&=\frac{(n+1)!}{r!(n+1-r)!}\\
{n \choose r-1}+{n \choose r}&={n+1 \choose r}
\end{aligned}
$$

Image target replacement

You can pass two arguments in the filter, input file directory, and output file directory. When used this way, the filter will replace image target paths with new paths resolved based on the output file directory. If a path cannot be resolved based on the output file directory, then the said path is considered an external url or absolute path.

Here's an example of applying arguments to the filter. Here the markdown is converted to json and the resulting json is piped to the filter with arguments, transformed json is then piped to a pandoc transformation back to the format markdown-simple_tables-multiline_tables-grid_tables.

pandoc -t json test.md | \
    md-filter -s "." -o "outputs/" | \
    pandoc -f json \
    -t markdown-simple_tables-multiline_tables-grid_tables \
    -o outputs/output.md

Here's an example Makefile that you can use to automatically resolve the directories of the source and the output.

INPUTDIR ?= $(dir $(SOURCE))
OUTPUTDIR ?= $(dir $(OUTPUT))

$(OUTPUT): $(SOURCE)
	pandoc -t json $(SOURCE) | \
		md-slides -s $(INPUTDIR) -o $(OUTPUTDIR) | \
		remarkjs | \
		pandoc -f json \
		-t markdown-simple_tables-multiline_tables-grid_tables \
        -o $(OUTPUT)