Publishing and distribution kit for Markdown presentations (and regular documents)

• Publishing and distribution kit for Markdown presentations (and regular documents)
  • Design
  • Dependencies
  • Getting Started (workflow)
    • Setup
    • Write
    • Layout and format
    • Print and publish
  • Cleaning prints
  • Notes
  • Tips
  • Useful links

🇫🇷 French version

This toolkit lets you produce Markdown-based presentation materials (slides first) optimized for printing and multi-format distribution:

• As a HTML slide deck for live presentation,
• As a HTML Single Page version for online publishing and easy navigation,
• As a PDF for a stable, portable format,
• As an epub for e-readers and offline reading (and because it's the best format to read).

You can also print standard Markdown documents to HTML, PDF or epub.

Finally, the kit lets you publish your prints to a remote (S)FTP server.

Design

• It is simple;
• It follows the necessary and beneficial separation of content and presentation;
• It is just a shell script that wraps marp and pandoc, adding some useful extra features to solve real world use cases.

Dependencies

• Marp, a slide deck framework built on Markdown, based on marpit;
• pandoc, a universal document converter. Very powerful and easy to script (lovely);
• lftp, an FTP client. Can easily be replaced by another program.

Getting Started (workflow)

Adapt and improve as needed.

Setup

0. Verify that marp, pandoc, and lftp are installed :

marp -v
pandoc -v
lftp -v

1. Duplicate the starter kit (Recommended: automate this step with a script);
2. Create a .env file to list the sources to be printed and your FTP credentials:

cp .env.dist .env

List the files you want to print and/or publish in your .env file :

#slide-decks
SOURCES_SLIDES=(
    slide-deck.md
    presentation.md
)
#standard documents
SOURCES_DOCS=(
    document.md
    exercices.md
)

To install the program globally :

sudo cp publish /usr/local/bin/pp
sudo cp pp-h2-link.lua /usr/local/bin/

We will use pp as an alias of the program for the rest of the documentation.

Write

1. Start the watch mode on the file you are working on:

marp --html --theme theme.css -w --allow-local-files slide-deck.md

Create an alias: alias marpw="marp --html --theme theme.css -w --allow-local-files" then marpw slide-deck.md

2. Open the generated HTML version (source.html). As soon as the file is edited, the output updates (hot reload).
3. Write and develop your Markdown document (Markdown Marpit flavor).

Layout and format

For layout, edit the following CSS files (or create your owns) :

• theme.css: used by HTML slide deck and PDF,
• style.css: used by HTML Single Page and epub and standard Markdown documents,
• style-single.css: used by HTML Single Page standard Markdown documents (override).

You can easily override CSS for epub with the CSS media queries : @media print{...} query, and for HTML Single Page with @media screen{...}.

Print and publish

# Show help
pp -h
# Print all formats (default)
pp
# Print only HTML deck
pp --no-html-single --no-pdf --epub --html-deck
# Or directly
pp --slides-only
# Print only HTML deck + PDF
pp --html-deck --pdf --no-html-single --no-epub
# Print only epub
pp --no-html-single --no-html-deck --no-pdf --epub

Printed documents are placed in the public/ directory by default.

To print and publish to an (S)FTP server:

# Print and publish to an FTP server (HTML Single Page and PDF by default)
pp --ftp

To control which formats are uploaded to the FTP server, set the following environment variables :

#Default values
do_publish_html_deck=false
do_publish_html_single=true
do_publish_pdf=true
do_publish_epub=false

For standard Markdown documents, only do_publish_html_single, do_publish_pdf and do_publish_epub options are available.

Cleaning prints

To clean local prints (in public/, not the sources !) :

pp --clean

Notes

• Slides use (Marpit) Markdown. Marpit enables minimalistic slide decks in the positive sense (content first with clear hierarchy). If you need transitions or sophisticated layouts, this may not be the ideal tool (though Marp can still do it)
• Published documents do not include comments from your source Markdown. Use comments freely to annotate your sources
• A table of contents is generated for HTML Single Page to improve navigation (can be disabled; generated by pandoc)
• The HTML Single Page print process uses a LUA script to generate anchors for each level-2 heading, allowing URLs pointing to each document section !
• The HTML Single Page output is self-contained: it embeds the stylesheet and all images. Larger, but easier to distribute

Tips

• Marp provides an option to set a slide background image. These images often break HTML Single Page and epub layouts (image size and caption). A .marp-bg-img class is automatically added when printing. Use .marp-bg-img in style.css to style/resize/change display of background images as needed;
• Adapt style.css and theme.css to your needs;
• Markdown is not designed for advanced layout. If you need image size constraints, classes, or IDs, prefer using the HTML img tag rather than Markdown image syntax;
• Lots of room for improvement ! Maintaining one single content source and generating multiple formats raises interesting design challenges and small technical issues you can (learn to) solve

Useful links

• Marp, create slide decks in a full Markdown ecosystem. Easily reuse structured content from your presentations to publish in PDF or HTML, and vice versa. Based on Marpit;
• pandoc: the universal document converter;
• Marp : use cases, a simple repository serving as a reference for using Marp.