/markdown_revealjs

Markdown to Reveal.js Sildes Converter

Primary LanguageJavaScript

title author date headerl headerr footerl title-slide-background-image toc-slide-background-image level1-slide-background-image level2-slide-background-image level3-slide-background-image background-size toc-depth
Markdown RevealJS
<img src="$reporoot-url$/images/me.png" style="height:1.5em;">xieby1
🎉2022.06.10
<img src="$reporoot-url$/images/me.png" style="height:1.2em;">
↙️ by xieby1
$reporoot-url$/images/liquid-cheese.svg
$reporoot-url$/images/liquid-cheese.svg
$reporoot-url$/images/liquid-cheese.svg
$reporoot-url$/images/liquid-cheese_shallow.svg
$reporoot-url$/images/liquid-cheese_shallow.svg
cover
1

Intro {data-stack-name="Intro"}

A Simple Easy Converter

Markdown ➡ Reveal.js

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

Demo

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

How it works

Bash script + Template file + Pandoc

It's simple and esay!

Installation {data-stack-name="Install"}

First

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

Second

Install latest pandoc.

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

::: {.fragment} 👍That's it!

🎊You've installed markdown_revealjs! :::

Third (Optional)

Add revealjs.sh to your PATH env.

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

Quick Start {data-stack-name="Quick Start"}

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

Basic Syntax

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

Convert!

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

🐱

It's simple and easy, right?

Themes {data-stack-name="Themes"}

Here are predefined themes (template),

just download the source markdown,

and [revealjs.sh xxx.md]{style="font-size: 1.5em;"}!

Enjoy the themes below🎉

🔽🔽🔽

龙芯

themes/loongson.md

<iframe src="./themes/loongson.html" style="width:800px; height: 450px;"></iframe>

微处理器研究中心

themes/ict_mtrc_proposal.md

<iframe src="./themes/ict_mtrc_proposal.html" style="width:800px; height: 450px;"></iframe>

国科大计算所答辩

themes/ucas_ict_thesis.md

<iframe src="./themes/ucas_ict_thesis.html" style="width:800px; height: 450px;"></iframe>

Advanced Syntax {data-name="Advanced Syntax ..."}

Sorted in alphabet.

Alignment

All elements

in Reveal.JS

are centered

by default.

😺

Left Alignment

:::{style="display:inline-block; text-align:left;"} 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

!
:::

:::

Backgrounds

Did you notice that every page has a default background?

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>

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

Set per-slide background, like

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

More info about background see:

Fragments

Multi Lines

::: {.fragment}

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

:::

One Line

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

:::{.fragment}

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

:::

Headings and slides

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

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>

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!

Include Files

include files normally

./included.md

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

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


example: Chart.js


::: {.container}
:::: {.col}


include a chart.js plot


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



::::
:::: {.col}


./plots/chartjs.html



::::
:::


example: Plotly.py


::: {.container}
:::: {.col}


include a plotly.py plot


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



::::
:::: {.col}


./plots/plotlypy.html



::::
:::


Label and Link {#label_and_link}


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


# Label and Link {#label_and_link}


Link


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


[Label and Link](#label_and_link)


Localization (Offline mode)


markdown_revealjs can be used completely offline!


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


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!


Long Table


Bother by long table?


::: {.fragment}
Then use wrap your long table


with [.longtable]{style="font-size:1.5em;"} like below


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


:::


Example


::: {.longtable style="height: 500px;"}






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




:::











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}
$$


Multiple columns


    

  • Pandoc Extension: fenced_divs
    • 

  • Builtin CSS class: container and col
    • 



Two-column Example


::: {.container}
:::: {.col}
It is two columns!


This is column 1
::::
:::: {.col}
This is column 2


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



::::
:::


You can add as many columns as possible.


Multiple-column Vertical Alignment (Top)


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


col1


    

  • Default is center alignment
    • 

  • This is top alignment
::::
:::: {.col}
    • 



col2


Top alignment code:


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



::::
:::


Multiple-column Vertical Alignment (Bottom)


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


    

  • Default is center alignment
    • 

  • This is bottom alignment
    • 



col1

::::
:::: {.col}
Top alignment code:

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



col2

::::
:::

Pandoc Options


Because markdown_revealjs is just


[a shell wrapper of pandoc]{style="font-size:1.5em;"}.


::: {.fragment}
You can [override]{style="font-size:1.5em;"} them!
:::


::: {.fragment style="font-size: 0.5em;"}
See pandoc available options by pandoc -h
:::


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


CLI Options (higher priority)


Override by appending reveal.sh command, like


reveal.sh <MD File> <PANDOC OPTIONS>



Example:


reveal.sh README.md --toc=false


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.


.slide-count-end


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


# Heading {.slide-count-end}


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


TOC (resident)


See,


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


Two Types of Attributes {data-auto-animate=1}


    

  • Top slide without subsequent vertical slides

      

    • data-name="<TOC_Entry_Name>"
      • 

    

    • 

  • Top slide with subsequent vertical slides

      

    • data-stack-name="<TOC_Entry_Name>"
      • 

    

    • 

  • Example:
    • 



::: {.container}
:::: {.col}


...
# H1 {data-name="h1"}

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

## H2_1
...


::::
:::: {.col}

::::
:::


Two Types of Attributes: details {data-auto-animate=1}




Hide Resident TOC {data-sminvisible=true}


Want to hide resident TOC in specific slides?


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


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

...


More Example


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

<iframe src="./themes/ucas_ict_thesis.html" style="width:800px; height: 450px;"></iframe>

Want to know more?


Resident TOC is implemented based on revealjs plugin:


martinomagnifico/reveal.js-simplemenu.


TOC (full)


TOC Depth


Default TOC depth is 2.


You can override it in yml front matter, like


toc-depth: 1


TOC Columns


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


    

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


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



1-column TOC


Here is an example of 1-column TOC


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


QnA {.slide-count-end}


    

  • Problems?
    • 

  • tips?
    • 

  • Advice?
    • 



New issue and pull request is welcome!


Backup Slides


Test the functionality of [Slide Number End].


From this slide on,


the total slide number ends counting.


Level-2 Backup Slides


🐱


Another Level-2 Backup Slides


🐈