A simple markdown to impress.js converter
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

5.2 KiB

ImpressMeMarkdown

Offficial ImpressMeMarkdown Logo

A simple markdown to impress.js converter

Getting started

From source

Building the binary

Requirements

  • Rust Toolchain (rustc, cargo)
  • git

Obtaining the source

Before you can build the binary, you have to obtain the source code. There are multiple ways to achieve this, but the easiest is to clone the official git repo:

git clone https://codeberg.org/comcloudway/impressme.md.git

Now that you have downloaded the source code, navigate into the folder by running cd impressme.md.

Building a release

Now that you are inside the project root, you can run cargo build --release to build the binary.

This will produce some output files in the target/release/ directory, one of them being impressmemd. You can now execute ./target/release/impressmemd --help to view a help menu. You are technically ready to jump to Preparing Impress.js now, as the installation of the binary is optional.

Installation (Optional)

To be able to run the command from anywhere it is recommended, that you place the executable in you PATH.

On most Linux distro's ~/.local/bin/ is already registered in the $PATH variable. Linking the binary to this folder is as easy as running ln -s $PWD/target/release/impressmemd $HOME/.local/bin/impressme.md. Running the command is as easy as typing impressme.md in the command line. Now you are good to go.

Preparing Impress.js

Requirements

  • git
  • patch

Obtaining the source

To make downloading the source code easier, the impress.js github repo has been added as a git submodule. This makes the download process as easy as running

git submodule update --init

Generating the template

To be able to generate the index.html file with all your slides, you need a template.html file. This template can be generated by patching the example markdown presentation. To do this run:

patch ./impress.js/examples/markdown/index.html ./files/generate-template.patch -o ./build/template.html

Now the index.html file has been patched.

It is recommended to renamr the index.html file to template.html so it using impressmemd is easier. A simple move operation does the trick: mv ./impress.js/examples/markdown/index.html ./impress.js/examples/markdown/template.html

Usage

When running impressme.md, three arguments are required:

  • --input or -i to specify the input.md file
  • --template or -t to specify the template.html to be used
  • --output or -o to specify an output.html file

If you template supports author, description and title meta data you can also set some meta data:

  • --author to set the author
  • --title to set the presentation title
  • --description to set the presentations' description

NOTE: The template generated in Preparing Impress.js supports author, description and title meta data

Markdown specifications

NOTE: Most markdown parsng is done by the impress.js markdown plugin. This library only generates the basic HTML layout

2 Types of Slides

Manually positioned slides

Manually positioned slides, are slides that are transformed into seperate div elements. They can be manually positioned (and styled) by Setting options.

Manually positioned slides are seperated by using =====.

For example the following markdown,

# Title 1
=====
# Title 2

will generate the following html code

<div ...>
# Title 1
</div>
< div ...>
# Title 2
</div>

Automatically positioned slides

Automatically positioned slides, are slides that are part of div elements. Impress.js will then automatically position these slides.

Automatically positioned slides are seperated by using -----.

For example the following markdown,

# Title 1
-----
# Title 2

will generate the following html code

<div ...>
# Title 1
-----
# Title 2
</div>

Setting options

To position or modify a slide (only works on manually positioned ones), impress.js requires you to set some attributes for the div elements.

In markdown this is done using an unofficial commenting syntax, indroduced by this library.

[<key>]: <value>

The <key> represents the attribute name and the <value> the attributes' value.

NOTE: ImpressMeMarkdown automatically adds the data- to the key, if the key is neither id nor class

NOTE: ImpressMeMarkdown automatically adds slide markdown to the class list, so you dont have to

Keeping all of this in mind, the following markdown

[id]: overview
[x]: 1000
[y]: 1000

will generate this html code

<div id="overview" class="markdown slide" data-x="1000" data-y="1000">
</div>

Other Markdown stuff

Basically embedding images, adding text, highlighting links, formatting text and specifying lists works exactly as expected from markdown, just get started and try it out.

The example folder contains example presentations.

Shoutouts

  • impress.js (submodule) for being the greatest presentation tool out there
  • Wikimedia for providing the markdown logo
  • structopt (rust library) for making my life way easier