Investigate Markdown --> PDF Slide Tools

[Shrinks99]

GitBook is a great content serving tool but not such a great presentation tool. In order to deliver the best experience for both instructors and students we should ideally deliver our slides in a presentation friendly format.

Currently everything is written as markdown files and we would like to keep it that way. Markdown is just text and makes everything very flexible and open in ways that dedicated presentation software (Keynote, Powerpoint, etc.) is not. Presentations should ideally be written as markdown files and output as a multi-page PDF presentation, each page being one slide.

So far I have been real impressed with Remark and Backslide for the PDF conversion. I think with a little formatting (in the same style as the website) we will be able to create nice engaging slide decks!

[Shrinks99]

I have finally begun this. So far I have started converting module 1 over to a remark slideshow. Once the content has parity with the GitBook version I will style it nicely and we can investigate switching. I still strongly believe that delivering slides in a PDF format will reduce overhead on presenters.

PDF generation will be done with decktape and integrated into our current build script.

[Shrinks99]

Slides look nicer now! We have real footnotes! Graphics will have to be redone to match the new fonts (Jost, Zilla Slab, and Ubuntu Mono) but other than that it is pretty much ready to go. I expect some more styling when it comes to long form code examples but in-line code should be all set.

Moving content over isn't too painful and most of it can just be copy-pasted in. With remark there is a html and markdown file per presentation, IMO it makes content management easier but it's all pretty similar to what we have now.

[benhylau]

This looks really pretty.

For comparison, existing GitBook version is not nearly as nice: https://tomeshnet.github.io/p2p-internet-workshop/articles/module-1/presentation/

[Shrinks99]

When all is said and done I will also make a Jekyll site for it to replace what we currently have. Remark can be easily integrated into Jekyll with a layout and I'd like something that presents the content in slide format online while sticking to the same style used in these slides.

Existing website is good for now though, hopefully this can come to fruition sooner rather than later!

[benhylau]

Why remake the site? The slides can be integrated into the current Jekyll site. I think it makes sense to theme the current site to be consistent with slide themes, but remaking a site is a lot of effort and I don't see good reason to duplicate the work that Mozilla has already put in.

[Shrinks99]

If it's less work to integrate and theme it then sure but I figure it may be more due to the change of content. I haven't looked into it yet.

[benhylau]

The gitbook / remarkjs swap is completely localized within its directory. Then we can just modify the css of the site itself to align theming.

[Shrinks99]

@benhylau Including all the markdown directly inside the presentation's respective HTML file does allow it to display the presentation directly in the browser when opened as a file however Decktape will not work with a local file due to its use of Chromium to render pages and this quirk.

Loading page file:///Users/Henry/Documents/remark-presentation/module-one.html ...
Loading page finished with status: 0
Remark JS plugin activated

Error: Evaluation failed: DOMException: Failed to read the 'rules' property from 'CSSStyleSheet': Cannot access rules
    at _ (__puppeteer_evaluation_script__:4:20)

The same page works as expected when used with a local web server.

Based on this it looks like we're going to have to run a server to convert the presentations to PDFs which is somewhat unlucky but hey, on the bright side it keeps the markdown and HTML separate which I'm fine with for nice organizational reasons.

[benhylau]

This issue is resolved, see: #81 (comment)