search

bast / cicero

:microphone: Serving presentation slides written in Markdown.
https://cicero.xyz
GNU Affero General Public License v3.0
55 stars 17 forks source link

Design of v3 API #43

Closed bast closed 7 years ago

bast commented 7 years ago

Goal of this issue thread is to agree on v3 of the API and iron out some known issues (listed below).

Current headaches with v2:

  1. When upgrading remarkjs, talks can suddenly break. The remarkjs dependency is now implicit and we may want to make it more explicit to avoid "slide deck rot".
  2. We maintain CSS customization (slide splits, colors, footnote) on top of remarkjs which may become difficult to maintain centrally when upgrading remarkjs.
  3. We maintain JS customization (mathjax and code highlighting) on top of what remarkjs provides which may become difficult to maintain centrally when upgrading remarkjs.
bast commented 7 years ago

Suggestion for 1) is to introduce version info into the URL, e.g.: /v3/remark/0.14.0/github/<namespace>/<repo>/<branch>/<file>/

We could also make it possible to create talks which automatically go with the latest remarkjs version: /v3/remark/latest/github/<namespace>/<repo>/<branch>/<file>/ at the expense that talks can break.

Suggestion for 2) is to move CSS customization to user space. If the user wants to serve the file mytalk.md and mytalk.css exists, then mytalk.css is appended after remarkjs' css (both locally and in the cloud). Currently we allow customization by providing own template next to mytalk.md but I think this is too brittle with respect to versions and also exposes more than people perhaps want to see or edit.

Waiting for good suggestions for 3).

bast commented 7 years ago

@robertodr @olemb your ideas/questions/concerns are very welcome.

bast commented 7 years ago

To give a more pictorial representation of what I have now in mind: If you fetch an URL that asks for remarkjs version 1.2.3, I would imagine Cicero assembling the following html and shipping it to the browser:

<html>
    css from remark 1.2.3
    css from user (if any)
    markdown from user
    js from remark 1.2.3
    js from user (if any)  # not sure exactly how
</html>
robertodr commented 7 years ago
  1. Sounds OK. Not really sure about introducing also latest. It's not going to be the default "engine" and if talks break because of that choice, well users were warned (if it's clearly documented)
  2. If local CSS easily overrides and/or extends built-in CSS then go for it.
  3. Same as for CSS. In principle we could also say that only the highlighting is provided in a "default" presentation and document how to add everything else. For heavier JS extensions, the documentation should also explain how to run everything locally.

I think your "picture" :smile: explains it pretty well.

bast commented 7 years ago

I think this is now implemented (although not default yet). I decided to not have latest so that things never break.