Skip to content

Latest commit

 

History

History
272 lines (231 loc) · 13.9 KB

README-NAVIGATE-SLIDES.md

File metadata and controls

272 lines (231 loc) · 13.9 KB
Raw

SEE SLIDES

This file is only a part of multiple sets of presentation slides. If you are reading this, consider viewing slides instead. However, this can't point you to the actual slides. (Why? Because several presentations use this file.) Instead, see

  • the GitHub project (or its clone/copy) or webpage you that referred you to this file; or
  • index.html at the root of the actual presentation that referred to this file. However, do NOT open it from a filesystem, but from a web server instead. See python3 -m http.server below for an example; or
  • the list of the original author's presentations.

But, if you are reading this, or any related README*.md files (referred to from index.html of the actual presentation), there are limitations:

  • Start with README.md and follow other README*.md files (in the actual presentation's webroot). See the end of each README*.md file, or source of index.html (in the actual presentation's webroot).
  • Unfortunately, you will not be able to see source code examples as a part of the README*.md documents. Instead, follow links to the respective source code. Those links highlight respective line ranges. However, source code loaded in the slides may be newer than the source code links in README*.md files. And source code shown on a video recording (if there is one) may be older or newer (than source code links in README*.md files).
  • Any comments in the referred sources starting with "presentation-" indicate start and end of relevant code examples.

The rest of this file assumes that you are viewing its content through index.html in the relevant presentation's webroot, either on GitHub pages or served by a local (or other) web server.

If you are reading the rest of the file from its source (from https://github.com/peter-kehl/present_markdown_reveal.js/blob/main/README-NAVIGATE-SLIDES.md or its clone), beware links (if any) with CSS classes

  • link_relative_to_presentation_github_repo_blob
  • link_relative_to_presentation_github_repo_tree
  • pre_relative_to_code_github_repo_raw
  • tours
  • vs_code_github_dev
  • videos.

They are NOT relative to this file (README-NAVIGATE-SLIDES.md)! Instead, they are relative to directory of the actual presentation (one that referred you to this file).

Reading this not as slides?

This is a shared file for presentation(s) in *.md file(s) (written in Reveal.js's Markdown mostly compatible with GitHub Markdown). The content is to be rendered by Reveal.js (also https://revealjs.com) through index.html of the given presentation. It won't display correctly if open from a filesystem! It requires to be accessed through a web server.

Such presentation(s) can load external files (both content and example code). In order to show them:

  1. Access index.html of the given presentation from a webserver (GitHub Pages, or another public/local webserver).
  2. But don't open it from a local file opened directly in browser. See Reveal.js > Markdown > External Markdown.
  3. You do not need npm. For example, you can run python3 -m http.server instead.
  4. But you do need to run the webserver for a directory at least one level above the clone of this project - so that the webserver serves the neighbor projects, too. Open the source of index.html of the actual presentation, and search for .. to see what neighbor projects it requires.
  5. Beware that, as of August 2022, python3 -m http.server and/or Firefox caused local README*.md files to be cached for up to 24 hours. Even refreshing the page in Firefox didn't help. It required purging Firefox cache: Firefox special URL about:preferences#privacy (or Preferences/Settings > Privacy & Security) > "Cookies and Site Data" > "Clear Data..." button > choose "Cached Web Content" > "Clear Data" button.
  6. Have the neighbor directories. On GitHub pages, fork all related projects (ones referred to from index.html through links containing ..). Then configure all those related forked GitHub repositories to publish their main branch to GitHub Pages (do not use master, or you will need to modify index.html). Alternatively, change the relative CSS and JS URL's in index.html.

Using relative URLs for plugins gives a benefit: People who fork/copy a project can use the same source code, and can merge back. Also, such relative URLs refer to their own GitHub forks of the plugins, hence not consuming GitHub pages bandwidth limit of the original project.

Use outside of GitHub

This is tailored for GitHub Pages. However, all the above principles (about viewing these slides) are independent of GitHub. You may be able to apply this to any decent source code hub that can serve the files' raw content and can serve source of JS files with text/javascript MIME. If your webserver doesn't allow to list directories starting with a dot, and if you want to list CodeTour file(s), then you need to either

  • put CodeTour files under tours directory and make .tours a symlink to it, or
  • have .vscode/settings.json pointing CodeTour to the directory where you keep CodeTour files: 
    {
  "codetour.customTourDirectory": "xxx"
}
  • but don't apply both (of the above), because then (local) VS Code shows the code tours twice.

Rendered with: Reveal.js

If you'd like to render this locally, you need to run a web server. Then you can access this in a web browser as (a part of) your presentation's index.html. See Reveal.js > Markdown > External Markdown. You can also test snippets of markdown.

Unfortunately, Reveal.js doesn't publish/document how to load its CSS & JS files online (and they don't seem to be publicly available on CDN's, either). Instead, it wants us to distribute its copies. However, that would make the actual presentation's repository much larger. It would also mean more work when updating (a copy of) Reveal.js for several presentations. Having your multiple presentations refer to your (one) clone of Remark.js makes it simpler.

So this presentation uses my fork of Reveal.js. It's idential (except for an extra CSS theme). It's served/loaded through GitHub Pages, which has bandwidth limit of 100GB per month.

Even though visitors of my presentations may not make it go over that bandwidth limit, we might reach the limit if authors of other presentations link to (my) forks of

Hence, please don't link to my forks. Instead, get your own forks.

(That will also boost their GitHub projects. And while you're at it, please star their GitHub repositories, too).

To make a GitHub repository show up on GitHub Pages (under .github.io) configure your fork repository's Settings > Pages > Source > Branch: main (and /(root)).

Reveal.js uses highlight.js. In addition to syntax-coloring, you can even highlight selected line(s) and transition between them. See Markdown and Presenting Code. (FYI supported languages). See highlight.js docs and its wiki.

Alternative: Remark.js

If you don't want to clone and track Reveal.js, and if you're happy with simpler and lightweight alternative, try Remark.js (see also its wiki). It allows your presentations to get Remark.js's JS files online (without copying and distributing them).

For an example on how to render it online with Gitlab CLI, see an example of slides and their source. (This example is authored by Cameron Dersham, the leader of Indy.rs, in July 2022. In addition to kindly sharing his knowledge, his presentation are a good source of important Rust news, both general and embedded.) As with Reveal.js, Remark.js also allows you to include a separate Markdown file. And it has slide notes and presenter mode, too.

However, it doesn't seem to support any plugins. And it doesn't have an ability to include (and then syntax-color) source files. (So you need to copy and paste the code examples). It doesn't seem to allow highlighting of selected lines of example code lines, either.

Both Reveal.js and Remark.js support code source highlighting. However, only Reveal.js can

  • highlight specified parts of (lines), and
  • display (parts of) external source files.

Unfortunately, Reveal.js doesn't support vertical scrolling of the slides (except for limited scrolling on mobile). Please give that issue thums up.

Navigate Slides

Essentials

  • Suggest rotating the screen (to landscape).
  • Zooming is tricky on mobile.
  • Suggest Firefox (showing code blocks better than Chrome).
  • Bottom left button or m key (lowercase): Menu with list of slides & themes.
  • See video(s) in videos/ repository TODO.
  • For manual navigation and outside of github.io see README-NAVIGATE-SLIDES.md: Original highlighted online (or raw source from a neighbor clone, if you cloned it next to this clone).

Navigate Slides > Desktop

Desktop

  • Easier navigation through slides and search.
  • Left & Right arrow keys to switch slides.
  • ? (question mark) for keyboard shortcuts.
  • ESC or o key (lowercase) to show (or hide) an overview of the nearby slides. (Navigate through the overview with arrow keys.)
  • Ctrl Shift F to show (or hide) a search input (at the top right).
    • Type the text and Enter.
    • Click anywhere on the slide to use the keys for navigation again.
    • This search is sticky: Any matching text will stay highlighted, even as you navigate to other slides.
    • Search results get highlighted in the overview, too.
  • Replay tour(s) from .tours/ directory (TODO TREE) in VS Code with Code Tour.
  • Follow bookmarks in VS Code with Bookmarks.