Markdown RevealJS

xieby1

🎉2022.06.10

1 Intro

A Simple Easy Converter

Markdown ➡ Reveal.js

  • Based on Pandoc
  • Auto-generated TOC
  • Touch-device friendly
  • Header footer supported

1.1 Demo

This README.md is converted to revealjs, see it here.

1.2 How it works

Bash script + Template file + Pandoc

It’s simple and esay!

2 Installation

2.1 First

git clone https://github.com/xieby1/markdown_revealjs

2.2 Second

Install latest pandoc.

Note: Ubuntu 22’s apt-installed pandoc is too old.

👍That’s it!

🎊You’ve installed markdown_revealjs!

2.3 Third (Optional)

Add revealjs.sh to your PATH env.

ln -s <path/to>/revealjs.sh /usr/bin/
# or /usr/local/bin/, or ~/.local/bin/

3 Quick Start

3.1 First Page

Add the metadata (title, author, date)

to top of your markdown file.

These info will become the first page of your slide.

% markdown_revealjs !
% xieby1
% 2022.06.24

3.2 Basic Syntax

syntax meaning
1st-level header New horizontal slide
2nd/3rd/4th/5th/6th-level header New vertical slide

3.3 Convert!

$ revealjs.sh <input.md>
# will generate input.html

🐱

It’s simple and easy, right?

4 Themes

Here are predefined themes (template),

just download the source markdown,

and revealjs.sh xxx.md!

Enjoy the themes below🎉

🔽🔽🔽

4.1 HUSTIC

themes/bosc/index.md

4.2 开芯院

themes/bosc/index.md

4.3 龙芯

themes/loongson/index.md

4.4 微处理器研究中心

themes/ict_mtrc_proposal/index.md

4.5 国科大计算所答辩

themes/ucas_ict_thesis/index.md

5 Advanced Syntax

Sorted in alphabet.

6 Alignment

All elements

in Reveal.JS

are centered

by default.

😺

6.1 Left Alignment

If you prefer to left align

all children elements.

Add these styles

to the parent element.

😽

:::{style="display:inline-block; text-align:left;"}
things here are all

left aligned

!
:::

7 Backgrounds

Did you notice that every page has a default background?

7.1 Default Backgrounds

Set default backgrounds in yml front matter, like

title-slide-background-image: <URL>
toc-slide-background-image: <URL>
level1-slide-background-image: <URL>
level2-slide-background-image: <URL>
level3-slide-background-image: <URL>
background-size: <CSS background-size>

7.2 Per-Slide Backgrounds

Set per-slide background, like

# Per-Slide Backgrounds {data-background-color="LightPink"}

More info about background see:

8 Fragments

8.1 Multi Lines

::: {.fragment}
Your content here
:::

8.2 One Line

It’s in one line! 🐱 🐶 🐹

[It's in one line!]{.fragment}
[🐱]{.fragment}
[🐶]{.fragment}
[🐹]{.fragment}

9 Headings and slides

Normally, each level of heading will start a new slide.

9.1 Heading not start a new slide

If you want a heading that doesn a new slide, like this

Level-3 Heading!

Just use html heading!

<h3>Level-3 Heading!</h3>

9.2 Force starting a new slide

If you want to start a new slide without headings.

Just use the markdown horizontal break ---, like this

Force starting a new slide!

10 Include Files

10.1 include files normally

More details: https://github.com/pandoc/lua-filters/blob/master/include-files/include-files.lua

10.2 include files in code block

``` {include="./helloworld.c"}
```

More details: https://github.com/pandoc/lua-filters/blob/master/include-code-files/include-code-files.lua

10.3 example: Chart.js

include a chart.js plot

``` {.include}
./plots/chartjs.html
```

10.4 example: Plotly.py

include a plotly.py plot

``` {.include}
./plots/plotlypy.html
```

12 Localization (Offline mode)

markdown_revealjs can be used completely offline!

12.1 Download this repo

# download by git
git clone https://github.com/xieby1/markdown_revealjs
# or download the source code without .git
wget https://github.com/xieby1/markdown_revealjs/archive/master.tar.gz
tar xzf master.tar.gz

12.2 Run revealjs.sh against local repo

Assuming the path to the local repo is <REPO>

REPOROOT=<REPO> <REPO>/bin/revealjs.sh <MD File>

Then you can view your slides completely offline!

13 Long Table

Bother by long table?

Then use wrap your long table

with .longtable like below

::: {.longtable style="height: 300px;"}
<your long table here>
:::

13.1 Example

This is a long vertical table
1 2 3 4 5 6
2 2 3 4 5 6
3 2 3 4 5 6
4 2 3 4 5 6
5 2 3 4 5 6
6 2 3 4 5 6
7 2 3 4 5 6
8 2 3 4 5 6
9 2 3 4 5 6
10 2 3 4 5 6
11 2 3 4 5 6
12 2 3 4 5 6
13 2 3 4 5 6
14 2 3 4 5 6
15 2 3 4 5 6
16 2 3 4 5 6
17 2 3 4 5 6
18 2 3 4 5 6
19 2 3 4 5 6
20 2 3 4 5 6

14 Math

Write latex math equation like this

$$
F = G \frac{m_1 \times m_2}{R^2}
$$

\[ F = G \frac{m_1 \times m_2}{R^2} \]

15 Multiple columns

  • Pandoc Extension: fenced_divs
  • Builtin CSS class: container and col

15.1 Two-column Example

It is two columns!

This is column 1

This is column 2

::: {.container}
:::: {.col}
Column 1
::::
:::: {.col}
Column 2
::::
:::

You can add as many columns as possible.

15.2 Multiple-column Vertical Alignment (Top)

col1

  • Default is center alignment
  • This is top alignment

col2

Top alignment code:

::: {.container style="align-items: flex-start;"}
:::: {.col}
col1
::::
:::: {.col}
col2
::::
:::

15.3 Multiple-column Vertical Alignment (Bottom)

  • Default is center alignment
  • This is bottom alignment

col1

Top alignment code:

::: {.container style="align-items: flex-end;"}
:::: {.col}
col1
::::
:::: {.col}
col2
::::
:::

col2

16 Pandoc Options

Because markdown_revealjs is just

a shell wrapper of pandoc.

You can override them!

See pandoc available options by pandoc -h

16.1 Metadata in .md file (lower priority)

Override in md file metadata, like

pandoc-opts: "<PANDOC OPTIONS>"

Example:

---
title: Markdown RevealJS
author: xieby1
date: 2022.06.10
...
pandoc-opts: "--toc=false"
---

16.2 CLI Options (higher priority)

Override by appending reveal.sh command, like

reveal.sh <MD File> <PANDOC OPTIONS>

Example:

reveal.sh README.md --toc=false

17 Slide Number End

Slides after the specific slides

can be excluded from the total slide number.

Think about a situation where,

in your PhD defense,

there are several backup slides at the end.

You do not want them counted to the total slide number.

17.1 .slide-count-end

Add .slide-count-end to the heading of the slide,

# Heading {.slide-count-end}

17.2 Example

In this README, .slide-count-end is added to slide QnA.

Therefore, the slides after QnA, like Backup Slides

are not counted to total slide number

18 TOC (resident)

See,

some key TOC entries are resident at the top of the slides?

18.1 Two Types of Attributes

  • Top slide without subsequent vertical slides
    • data-name="<TOC_Entry_Name>"
  • Top slide with subsequent vertical slides
    • data-stack-name="<TOC_Entry_Name>"
  • Example:
...
# H1 {data-name="h1"}

# H2 {data-stack-name="h2"}

## H2_1
...

18.1.1 Two Types of Attributes: details

18.2 Hide Resident TOC

Want to hide resident TOC in specific slides?

Add data-sminvisible=true to the slide heading, like

## Hide Resident TOC {data-sminvisible=true}

...

18.3 More Example

My 国科大计算所答辩 theme use resident TOC

18.4 Want to know more?

Resident TOC is implemented based on revealjs plugin:

martinomagnifico/reveal.js-simplemenu.

19 TOC (full)

19.1 TOC Depth

Default TOC depth is 2.

You can override it in yml front matter, like

toc-depth: 1

19.2 TOC Columns

The number of TOC columns is controlled by yml front matter:

  • toc-width for TOC width
  • toc-column-width for TOC’s column width
  • toc-margin for TOC’s margin

Therefore, by adjusting these two variable,

you can control how many TOC columns you have.

19.2.1 Default Values (3-column TOC)

  • Remember the default slide width is 1200px.
  • The default toc-column-width is 290px
  • The default toc-margin is 0 0 0 0
  • Thus a 3-column toc is presented.

19.2.2 1-column TOC

Here is an example of 1-column TOC

toc-width: 1200px
toc-column-width: unset
toc-margin: 0 400px

20 QnA

  • Problems?
  • tips?
  • Advice?

New issue and pull request is welcome!

21 Backup Slides

Test the functionality of Slide Number End.

From this slide on,

the total slide number ends counting.

21.1 Level-2 Backup Slides

🐱

21.2 Another Level-2 Backup Slides

🐈

Github Repo
↙️ xieby1