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 --recurse-submodules https://github.com/xieby1/markdown_revealjs

2.2 Second

Install latest pandoc.

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

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

3.3 Convert!

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

🐱

It’s simple and easy, right?

3.4 daemonize

$ revealjs.sh -d <input.md>
# will auto refresh browser when input.md is changed

4 Themes

Here are predefined themes (template),

just download the source markdown,

and revealjs.sh xxx.md!

Enjoy the themes below🎉

🔽🔽🔽

4.1 开芯院

themes/bosc/index.md

4.2 龙芯

themes/loongson/index.md

4.3 微处理器研究中心

themes/ict_mtrc_proposal/index.md

4.4 国科大计算所答辩

themes/ucas_ict_thesis/index.md

6 Alignment

All elements

in Reveal.JS

are centered

by default.

😺

6.1 Left Alignment

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

left aligned

!
:::

7 Auto Animate

7.1 Code

```python {data-id="code-animation" data-line-numbers=""}
class Miao:
  def __init__(self):
    pass
```

class Miao:
  def __init__(self):
    pass

7.2 Code

```python {data-id="code-animation" data-line-numbers=""}
# This is a class
class Miao:
  # This is a func def
  def __init__(self):
    pass
```

# This is a class
class Miao:
  # This is a func def
  def __init__(self):
    pass

8 Backgrounds

Did you notice that every page has a default background?

8.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>

8.2 Per-Slide Backgrounds

Set per-slide background, like

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

More info about background see:

• RevealJS: backgrounds
• Pandoc Extension: header_attributes

9 Fragments

• RevealJS: fragments

9.1 Multi Lines

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

9.2 One Line

• Pandoc Extension: bracketed_spans

It’s in one line! 🐱 🐶 🐹

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

10 Headings and slides

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

10.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>

10.2 Force starting a new slide

If you want to start a new slide without headings.

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

11 Include Files

11.1 include files normally

This file is include by

```{.include}
./included.md
```

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

11.2 include files in code block

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

#include <stdio.h>
int main(void);

int main(void)
{
    printf("Hello, world! \n");
    
    return 0;
}

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

11.3 example: Chart.js

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

11.4 example: Plotly.py

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

12 Label and Link

You can label a slide by adding a name to its heading

# Label and Link {#label_and_link}

12.1 Link

Then you can go back to the labeled slide ⬆️ Label and Link⬆️ .

[Label and Link](#label_and_link)

13 Localization (Offline mode)

markdown_revealjs can be used completely offline!

13.1 Download this repo

# download by git
git clone --recurse-submodules 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

13.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!

14 Long Table

Bother by long table?

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

14.1 Example

16 Multiple columns

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

16.1 Two-column Example

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

You can add as many columns as possible.

16.2 Multiple-column Vertical Alignment (Top)

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

16.3 Multiple-column Vertical Alignment (Bottom)

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

17 Pandoc Options

Because markdown_revealjs is just

a shell wrapper of pandoc.

17.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"
---

17.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

18 Slide Number End

Slides after the specific slides

can be excluded from the total slide number.

18.1 .slide-count-end

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

# Heading {.slide-count-end}

18.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

19 TOC (resident)

See,

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

19.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
...

19.1.1 Two Types of Attributes: details

19.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}

...

19.3 More Example

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

19.4 Want to know more?

Resident TOC is implemented based on revealjs plugin:

martinomagnifico/reveal.js-simplemenu.

20 TOC (full)

20.1 TOC Depth

Default TOC depth is 2.

You can override it in yml front matter, like

toc-depth: 1

20.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.

20.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.

20.2.2 1-column TOC

Here is an example of 1-column TOC

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

22 Backup Slides

Test the functionality of Slide Number End.

From this slide on,

the total slide number ends counting.

22.1 Level-2 Backup Slides

🐱

22.2 Another Level-2 Backup Slides

🐈