Present Markdown with Reveal.js
Work in progress. See https://peter-kehl.github.io/no_std_libs and
https://github.com/peter-kehl/no_std_libs for now.
Benefits
- Present on GitHub Pages by a simple
git push. No npm or any other preprocessing.
- Present from any modern webserver (useful for editing locally).
Scope, Simplifications, Limitations
- No vertical slides.
- Using denehyg/reveal.js-menu, but disabled (hid) a
few of its entries.
- Slides are scrollable, which is very tricky with Reveal.js. Scrolling is not ideal on mobile.
- Not related to webpro/reveal-md.
- Mainstream only: GitHub or generic web server, videos as GitHub raw content and/or Youtube…
- No support for Reveal.js packages that
Suggestions
Slide ID’s
- Give your slides ID’s (in Markdown it’s
<!-- .slide: id="ID-here" -->).
- Make them non-numeric. That way, if you insert new slides in-between, existing links to actual
slides will be still valid.
- Naming conventions for ID’s (as for anything) may be contraversial, but suggest
Underscore_separated or Underscore_Separated_Title_Case.
- Group them semantically: Make related consecutive slides have ID’s starting with the same prefix.
Use that prefix as an ID for the first slide of the group. Like
Navigate_Slides,Navigate_CodeTour. That way if you split/rename some slides in the group, even if the existing
links may become obsolete, users can at least infer the slide group (as listed in the menu).
- This also keeps links consistent if you make some slides computer-only or mobile-only (or specific
browser-only).
- The menu (shown by the bottom left button, or m key) does NOT pick up/use slide ID’s. Instead,
it uses the first header on each slide (even if it’s not the top-level H1
# - it may be H2 ##,
even if there is an H1 # on the sam slide). So, make the first header on each slide the same as
as ID in <!-- .slide: id="ID-here" -->. (But exclude the underscores in the headers.)
- Have the first slide’s ID from each Markdown file reflected in its Markdown file name. But, see
also Markdown File Names below.
Markdown File Names
- Name them
README.md and README-*.md. Uppercase seems to be the standard on GitHub (like
LICENSE-MIT, LICENSE-APACHE…)
- Use hyphen - to separate terms, and underscores within multiword terms.
-
Is your presentation likely to use more than two local Markdown files (in the same directory) -
that is, other than README.md and just one README-SOMETHING.md? If so, number them (except
for README.md): README-01-SOMETHING.md, README-02_-SOMETHING-ELSE.md, ... in the same order as
you include them in index.html. That helps when organizing. You also help people with
accessibility difficulties.
(Do so, even if their filenames would happen to be alphabetically sorted even without 01, 02....
That helps when people sort files by their last update timestamps.)
- Have a Markdown file name (after
README-XY-) reflect the ID of its first slide.
Occasional HTML
Even if you use Markdown, some combinations require HTML.
Beware that Reveal.js’s Markdown ignores <script>. So you need to load any Javascript in
index.html.