Cicero: Serving presentation slides written in Markdown

You write your talk in Markdown, host it on GitHub or GitLab. We render it using remark of reveal.js and serve it for you before you can say blueberry pie. You can style your slides to your heart’s content.

Getting started in 5 minutes

Place the following Markdown file on https://github.com or https://gitlab.com, perhaps as mytalk.md:

class: center, middle

# Simple example presentation

## Author

---

## Another slide

Try **F** and **P** keys.

- A bullet point
- Another convincing argument

---

## Code blocks are no problem

Here we have some Python code:

```python
from itertools import cycle

fizz = cycle(['', '', 'Fizz'])
buzz = cycle(['', '', '', '', 'Buzz'])

for i in range(1, 101):
    print((next(fizz) + next(buzz)) or i)
```

[Source](https://github.com/olemb/nonsense/blob/master/fizzbuzz/itertools_cycle.py)

---

## Images

An image fetched from the web:

![Sample image](https://upload.wikimedia.org/wikipedia/commons/thumb/4/4f/The_Young_Cicero_Reading.jpg/316px-The_Young_Cicero_Reading.jpg)

Let us assume your talk is on (replace <namespace> and <repository>):

https://github.com/<namespace>/<repository>/mytalk.md

You can now visit (replace <namespace> and <repository>):

https://cicero.xyz/v3/remark/0.14.0/github.com/<namespace>/<repository>/main/mytalk.md

Of course you can reference another branch or tag or hash than main.

If you like https://revealjs.com better, then check https://github.com/bast/cicero/tree/main/demo/reveal.js.

Exporting slides to PDF

The to my knowledge best way to export slides to PDF is using https://github.com/astefanutti/decktape.

First install the tool following https://github.com/astefanutti/decktape#install, then you can export slides, e.g.:

$ decktape https://example.org/my-slides.md/ my-slides.pdf

If you prefer not to install it but have Singularity installed, you can do this instead:

$ singularity pull docker://astefanutti/decktape
$ ./decktape_latest.sif https://example.org/my-slides.md/ my-slides.pdf

Running the app locally

You can preview your changes locally and also present your talk without relying on https://cicero.xyz:

$ pip install cicero
$ cicero --file /home/user/my-talk/talk.md

Available options

$ cicero --help

usage: cicero.py [-h] [--file FILENAME] [--engine ENGINE] [--debug]
                 [--host HOST] [--port PORT]

optional arguments:
  -h, --help            show this help message and exit
  --file FILENAME, -f FILENAME
                        serve a local file (default: None)
  --engine ENGINE       rendering engine (available: remark-0.13.0,
                        remark-0.14.0, remark-legacy, reveal.js-3.7.0)
                        (default: remark-0.14.0)
  --debug
  --host HOST
  --port PORT

How to use your own CSS

If you place a file in the same path as your talk, with the same name as your talk, and only replace the .md suffix by .css. Then the rendering engine will use this file: https://github.com/bast/cicero/blob/main/cicero/templates/render.html#L11-L13

In other words, if your talk is called mytalk.md and you want to customize CSS, place a file called mytalk.css in the same place as your mytalk.md.

With this you can even override CSS directives and style your slides to your heart’s content.

Example: https://github.com/bast/cicero/tree/main/demo/remark/styling

Images

You can either include images the Markdown way:

![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

![alt text](path/myimage.jpg "Local image")

or the HTML way:

<img src="file.jpg" style="height: 450px;"/>

Background image

remark

Setting and changing the background image is nicely documented here: https://github.com/gnab/remark/wiki/Markdown#background-image

How to customize everything

You want to change looks and fonts? CSS is not enough? Perhaps you need an external JavaScript library?

You can place *.head.html and/or *.body.html alongside your *.md slides. In these files you can do and change almost everything: https://github.com/bast/cicero/blob/main/cicero/templates/render.html.

To get inspired of what is in these by default and what can be changed, please browse https://github.com/bast/cicero/tree/main/cicero/static/engines.

v2

This API is the past but still supported:

/v2/remark/github/<namespace>/<repo>/<branch>/<path>

Example: https://cicero.xyz/v2/remark/github/bast/cicero/main/demo/remark/original/talk.md

v1

This API is deprecated since it does not allow talks in subdirectories:

/v1/github/<namespace>/<repo>/<branch>/<path>/remark/

Running your own server

You can run your own Cicero instance on your own server. Cicero is a Flask app and to serve it you should use a WSGI server for production. The sources are open: https://github.com/bast/cicero

Environment variables

You will need to define CICERO_URL_BASE to the URL of your server. This sets the URL base for generated links in the Markdown file finder.

As an example, for https://cicero.xyz we set:

CICERO_URL_BASE=https://cicero.xyz

Dependencies

The app depends on the following Python packages:

  • Flask 1.0.2
  • Requests 2.20.0

On the front-end side we depend on the following libraries:

  • Vue 2.5.16
  • Bootstrap 4.1.3

Setting up your environment

First install the dependencies (you need a network connection for this step):

$ git checkout https://github.com/bast/cicero
$ cd cicero

Now install https://flit.readthedocs.io/ from requirements.txt.

Then install the package and start the server:

$ flit install --symlink
$ cicero

* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)