radovan.xyz / cicero
:microphone: Serving presentation slides written in Markdown. cicero.pages.dev
markdown presentation slides
Star 0
Fork 0
Watch
JavaScript 73%
Rust 23%
HTML 2%
CSS 2%
5 1 0
examples
functions
preview
public
.gitignore
LICENSE
README.md
wrangler.toml
README.md

cicero #

Renders markdown slide decks straight from Tangled, GitHub, or Codeberg, using remark, reveal.js, or marp, entirely client-side. Live at https://cicero.pages.dev.

Point at a slide deck by adding its path to the site URL:

https://cicero.pages.dev/tangled/{owner}/{repo}/{ref}/{path...}
https://cicero.pages.dev/github/{owner}/{repo}/{ref}/{path...}
https://cicero.pages.dev/codeberg/{owner}/{repo}/{ref}/{path...}

{ref} is a branch name, a tag, or a commit hash. For example, https://cicero.pages.dev/tangled/radovan.xyz/paragliding-aerodynamics/main/slides.md renders https://tangled.org/radovan.xyz/paragliding-aerodynamics.

If a branch name contains slashes (e.g. myname/experiment), add a -- segment to mark where the ref ends and the path begins:

https://cicero.pages.dev/github/{owner}/{repo}/myname/experiment/--/{path...}

Motivation #

  • No more "Can you please email me the slides after the workshop?"
  • All you need is a browser and everybody has a browser in their pocket.
  • It is easier to share a link to slides than it is to serve them.
  • It is easier to reuse a Markdown talk than it is to modify PDF slides.
  • Talks become lightweight, reusable, versionable, branchable, and forkable.
  • Hackable URLs.
  • Presentation URL lives as long as the corresponding Markdown file lives.

The cicero comment block #

A slide deck is a plain markdown file that starts with an HTML comment naming the rendering engine and the JS/CSS assets to load. There is no default engine: every deck declares its own (so decks hopefully never break in the future). Everything after the comment block is ordinary markdown for the chosen engine.

<!-- cicero
engine: remark
js:
  - https://cdnjs.cloudflare.com/ajax/libs/remark/0.14.0/remark.min.js
css:
  - slides.css
highlight: monokai
-->

# First slide
...

Supported engines: remark, reveal.js, and marp.

Examples can be found in examples/, and the site's own help pages show the matching comment blocks. highlight names one of remark's bundled highlight.js themes and is ignored by the other engines. css entries are either absolute URLs or paths relative to the deck's own directory; the same goes for images in the slides.

JavaScript entries #

On cicero.pages.dev, a js: entry must match one of these patterns:

https://cdnjs.cloudflare.com/ajax/libs/remark/{version}/remark.min.js
https://cdnjs.cloudflare.com/ajax/libs/mathjax/{version}/MathJax.js?config={name}
https://cdnjs.cloudflare.com/ajax/libs/reveal.js/{version}/{file}.js
https://cdn.jsdelivr.net/npm/@marp-team/marp-core@{version}/+esm

To extend this list, modify ALLOWED_JS in public/app.js. Everything that cannot execute stays open on the hosted site: CSS, images, and media may come from any URL or from the deck's repository.

In local preview (see below) the deck is your own file running on your own machine, so js: may name any URL or any file next to the deck.

Local preview #

preview/ contains a small command-line tool that renders a deck exactly like the hosted site, but from a local file or a remote URL.

Install it straight from the repo:

$ cargo install --git https://tangled.org/radovan.xyz/cicero

Then you can:

$ cicero --help
$ cicero talk/slides.md
$ cicero https://example.org/raw/slides.md

Exporting to PDF #

decktape works against any URL, so it works against a rendered deck's page too:

$ decktape https://cicero.pages.dev/tangled/radovan.xyz/paragliding-aerodynamics/main/slides.md talk.pdf

If you'd rather not install it but have Singularity, pull the container instead:

$ singularity pull docker://astefanutti/decktape
$ ./decktape_latest.sif https://cicero.pages.dev/tangled/radovan.xyz/paragliding-aerodynamics/main/slides.md talk.pdf

History #

This is a rewrite of https://github.com/bast/cicero, a Flask app that served the same purpose by rendering decks hosted on GitHub or GitLab.

The original was built 2015, by Radovan Bast (idea and pilot implementation), Ole Martin Bjørndalen (local preview), and Roberto Di Remigio (MathJax support, local templating, slide splits), with contributions from Jyry Suvilehto and Martti Louhivuori.