Viewport Navigation
What is it?
Viewport navigation is a JavaScript library which enhances webpages with a navigation menu and slideshow presentation functionality. You can see it in action of this page!
Here’s a fuller list of the features it provides.
- Automatically generates a navigation menu for your document by inspecting the section structure of your document.
- Provides a “viewport” over the navigation menu. This can be handy to see where you are in a long document. Try scrolling this page up and down to see it in action.
-
Provides various display modes:
- Normal
- The default mode.
- Fullscreen
- Display the webpage fullscreen.
- Slideshow
- Display the document one slide at a time. You create slides in your document by marking a section with a special attribute.
- Presentation
- Combines fullscreen and slideshow modes.
- Blank
- Turns the display blank — this can be useful when giving presentations.
-
Provides dark and light themes. The default theme is
chosen as dark or light according to the
prefers-color-scheme
CSS media feature, so it should match a user’s preference. - Provides a responsive design which reduces the navigation menu to a hamburger button for small screens, and shows it in full for bigger screens. The font size is automatically made larger as the screen size increases.
How to get it
You can get viewport navigation in various ways.
- Git
- Clone the source code from its GitLab repository.
- Node.js
- Get it as a npm package.
- Copr
- Install it as an RPM from a Copr repository.
How to use it
- Add the following lines to the header of your document.
<link rel="stylesheet" href="viewport-navigation.min.css"/>
<script src="viewport-navigation.browser.min.js"></script>
-
Add
id
attributes to every sectioning element you want to include in the navigation menu. -
Add
class="_vn-slide"
attributes to every sectioning element you want to appear as a slide in the slideshow and presentation modes.
Keyboard Shortcuts
There are a number of keyboard shortcuts which can be used instead of the controls menu.
Display
Command | Shortcut |
---|---|
Blank display | Ctrl+Shift+Alt+B |
Fullscreen display | Ctrl+Shift+Alt+F |
Normal display | Ctrl+Shift+Alt+N |
Presentation display | Ctrl+Shift+Alt+P |
Slideshow display | Ctrl+Shift+Alt+S |
Theme
Command | Shortcut |
---|---|
Dark theme | Ctrl+Shift+Alt+D |
Light theme | Ctrl+Shift+Alt+L |
Slideshow
The following keyboard shortcuts are available when you are in slideshow or presentation mode.
Command | Shortcut |
---|---|
Show previous slide | Page Up or ↑ or ← |
Show next slide | Page Down or ↓ or → |
Show first slide | Home |
Show last slide | End |
Presentation remotes
You can use a presentation remote or clicker with viewport navigation because they work looking like a normal keyboard to the computer and they typically send key-sequences which will coincide with the keyboad shortcuts discussed in the pevious section.
I have a Doosl wireless presenter and it emits the following key codes.
Button | Prezi Mode | Key Sequence |
---|---|---|
< | Mode 1 | Page Up |
> | Mode 1 | Page Down |
< | Mode 2 | ↑ |
> | Mode 2 | ↓ |
< | Mode 3 | ← |
> | Mode 3 | → |
⧉ First short press | All modes | Esc |
⧉ Second short press | All modes |
|
⧉ Long press | All modes | B |
T | All modes | None |
⏯ | All modes | None |
You can switch between Prezi modes by pressing and holding the < and > buttons. I run mine in Prezi mode 3, so that it emits cursor left and right key codes. This means that viewport navigation shows the previous/next slide when in slideshow or presentation modes, but has no effect otherwise.
And yes, the presenter really does emit all of those key codes one after the other on your second short press of the ⧉ button. Needless to say, this causes absolute chaos in a web browser — so I just try to avoid that button altogether.
If you have a presentation remote and you want to examine the key codes it outputs you can do so by running the evtest command as root on on Linux. You then have to select the USB devices that you want to inspect, note that the names that appear in the list do not always match up with what you would expect. My Doosl presenter appears as a SONix USB Device for instance.
If you are modifying the source code of viewport navigation to suit your presenter then you will find the following list of JavaScript key code to key mappings useful.
Developing
Here’s some useful documentation links to look at when developing viewport navigation.
You can view the latest JSDoc documentation for this project or you can generate a local copy with the command npm run doc.
The build system for this software uses
npm
scripts which are defined in
the package.json
file. I’ve found the excellent
article “How
to Use npm
as a Build Tool”
by Keith Cirkel helps a lot
with how to express scripts in package.json
.