Open Source Lecture Slides
This is basically a repo to organize my thoughts on how best to create lecture notes that are opensource and improvable by the community. A large range of topics can be found on https://slides.com/.
Installation
npm install
Usage
npm start
This starts a local server and opens any Markdown file as a reveal.js presentation in the default browser.
Software
I'm basically just using reveal-md so I'm going to include relevant info on that package below.
- Markdown
- Theme
- Highlight Theme
- Custom Slide Separators
- Custom Slide Attributes
- reveal-md Options
- Reveal.js Options
- Speaker Notes
- YAML Front Matter
- Live Reload
- Custom Scripts
- Custom CSS
- Custom Favicon
- Pre-process Markdown
- Print to PDF
- Static Website
- Disable Auto-open Browser
- Directory Listing
- Custom Port
- Custom Template
Markdown
The Markdown feature of reveal.js is awesome, and has an easy (and configurable) syntax to separate slides. Use three
dashes surrounded by two blank lines (\n---\n
). Example:
# Title
* Point 1
* Point 2
---
## Second slide
> Best quote ever.
Note: speaker notes FTW!
Theme
Override theme (default: black
):
reveal-md slides.md --theme solarized
See available themes.
Override reveal theme with a custom one. In this example, the file is at ./theme/my-custom.css
:
reveal-md slides.md --theme theme/my-custom.css
Override reveal theme with a remote one (use rawgit.com because the url must allow cross-site access):
reveal-md slides.md --theme https://rawgit.com/puzzle/pitc-revealjs-theme/master/theme/puzzle.css
Highlight Theme
Override highlight theme (default: zenburn
):
reveal-md slides.md --highlight-theme github
See available themes.
Custom Slide Separators
Override slide separator (default: \n---\n
):
reveal-md slides.md --separator "^\n\n\n"
Override vertical/nested slide separator (default: \n----\n
):
reveal-md slides.md --vertical-separator "^\n\n"
Custom Slide Attributes
Use the reveal.js slide attributes functionality to add HTML
attributes, e.g. custom backgrounds. Alternatively, add an HTML id
attribute to a specific slide and style it with
CSS.
Example: set the second slide to have a PNG image as background:
# slide1
This slide has no background image.
---
<!-- .slide: data-background="./image1.png" -->
# slide2
This one does!
reveal-md Options
Define options similar to command-line options in a reveal-md.json
file that must be located at the root of the
Markdown files. They'll be picked up automatically. Example:
{
"separator": "^\n\n\n",
"verticalSeparator": "^\n\n"
}
Reveal.js Options
Define Reveal.js options in a reveal.json
file that must be
located at the root directory of the Markdown files. They'll be picked up automatically. Example:
{
"controls": true,
"progress": true
}
Speaker Notes
Use the speaker notes feature by using a line starting with
Note:
.
YAML Front matter
Set Markdown (and reveal.js) options specific to a presentation with YAML front matter:
---
title: Foobar
separator: <!--s-->
verticalSeparator: <!--v-->
theme: solarized
revealOptions:
transition: 'fade'
---
Foo
Note: test note
<!--s-->
# Bar
<!--v-->
Live Reload
Using -w
option changes to markdown files will trigger the browser to reload and thus display the changed presentation
without the user having to reload the browser.
Custom Scripts
Inject custom scripts into the page:
reveal-md slides.md --scripts script.js,another-script.js
Don't use absolute paths, files should be in adjacent or descending folders.
Custom CSS
Inject custom CSS into the page:
reveal-md slides.md --css style.css,another-style.css
Don't use absolute paths, files should be in adjacent or descending folders.
Custom Favicon
If the directory with the markdown files contains a favicon.ico
file, it will automatically be used as a favicon
instead of the default favicon.
Pre-process Markdown
reveal-md
can be given a markdown preprocessor script via the --preprocessor
(or -P
) option. This can be useful to
implement custom tweaks on the document format without having to dive into the guts of the Markdown parser.
For example, to have headers automatically create new slides, one could have the script preproc.js
:
// headings trigger a new slide
// headings with a caret (e.g., '##^ foo`) trigger a new vertical slide
module.exports = (markdown, options) => {
return new Promise((resolve, reject) => {
return resolve(
markdown
.split('\n')
.map((line, index) => {
if (!/^#/.test(line) || index === 0) return line;
const is_vertical = /#\^/.test(line);
return (is_vertical ? '\n----\n\n' : '\n---\n\n') + line.replace('#^', '#');
})
.join('\n')
);
});
};
and use it like this
$ reveal-md --preprocessor preproc.js slides.md
Print to PDF
Create a (printable) PDF from the provided Markdown file:
reveal-md slides.md --print slides.pdf
The PDF is generated using Puppeteer. Alternatively, append ?print-pdf
to the url from the command-line or in the
browser (make sure to remove the #/
or #/1
hash). Then print the slides using the browser's (not the native) print
dialog. This seems to work in Chrome.
By default, paper size is set to match options in your reveal.json
file, falling back to a
default value 960x700 pixels. To override this behaviour, you can pass custom dimensions or format in a command line
option --print-size
:
reveal-md slides.md --print slides.pdf --print-size 1024x768 # in pixels when no unit is given
reveal-md slides.md --print slides.pdf --print-size 210x297mm # valid units are: px, in, cm, mm
reveal-md slides.md --print slides.pdf --print-size A4 # valid formats are: A0-6, Letter, Legal, Tabloid, Ledger
In case of an error, please try the following:
- Analyze debug output, e.g.
DEBUG=reveal-md reveal-md slides.md --print
- See
reveal-md help
for Puppeteer arguments (puppeteer-launch-args
andpuppeteer-chromium-executable
)
Static Website
This will export the provided Markdown file into a stand-alone HTML website including scripts and stylesheets. The files
are saved to the directory passed to the --static
parameter (default: ./_static
):
reveal-md slides.md --static _site
This should copy images along with the slides. Use --static-dirs
to copy directories with other static assets to the
target directory. Use a comma-separated list to copy multiple directories.
reveal-md slides.md --static --static-dirs=assets
Providing a directory will result in a stand-alone overview page with links to the presentations (similar to a directory listing):
reveal-md dir/ --static
Additional --absolute-url
and --featured-slide
parameters could be used to generate OpenGraph
metadata enabling more attractive rendering for slide deck links when shared in some social sites.
reveal-md slides.md --static _site --absolute-url https://example.com --featured-slide 5
Disable Auto-open Browser
To disable auto-opening the browser:
reveal-md slides.md --disable-auto-open
Directory Listing
Show (recursive) directory listing of Markdown files:
reveal-md dir/
Show directory listing of Markdown files in current directory:
reveal-md
Custom Port
Override port (default: 1948
):
reveal-md slides.md --port 8888
Custom Template
Override reveal.js HTML template (default template):
reveal-md slides.md --template my-reveal-template.html
Override listing HTML template (default template):
reveal-md slides.md --listing-template my-listing-template.html
Related Projects & Alternatives
- Slides is a place for creating, presenting and sharing slide decks.
- Sandstorm Hacker Slides is a simple app that combines Ace Editor and RevealJS.
- Tools in the Plugins, Tools and Hardware section of Reveal.js.
- Org-Reveal exports Org-mode contents to Reveal.js HTML presentation.
- DeckTape is a high-quality PDF exporter for HTML5 presentation frameworks.
- GitPitch generates slideshows from PITCHME.md found in hosted Git repos.
Thank You
Many thanks to all contributors!