hackers-tiny-slide-deck
v0.4.2
Published
Turn a Markdown document into a slide deck quickly.
Downloads
121
Maintainers
Readme
Hacker's Tiny Slide Deck (HTSD)
Turn a Markdown document into a slide deck, in two steps:
Add a
<script>
tag referring the HTSD JavaScript bundle to the end of the Markdown document. For example, accessing the bundle from jsDelivr service:<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/hackers-tiny-slide-deck@VERSION/build/htsd.min.js"></script>
(Replace
VERSION
with the version of this npm package.)Convert the Markdown document into html. For example, using marked:
marked -i example.md > example.html
This might be the preferable option for preparing a quick presentation.
Use an editor plugin to make step 2 easier, preferably via a keyboard
shortcut. For example, markdown-mode for Emacs has the
markdown-export-and-preview
(C-c C-c v
) command, which converts the
.md
file in the current buffer to a .html
file and opens the html in
the default browser.
To demonstrate the features quickly, see the sources of example.md and the converted html.
Features
- Responsive CSS, with automatically scaling text size.
- You can still adjust text size with the browser's zoom function.
- Keyboard shortcuts to change slides:
- ⬅️ (left arrow) to show the previous slide
- ➡️ (right arrow) to show the next slide
Home
to show the first slideEnd
to show the last slide
- Keyboard shortcut to toggle fullscreen,
Shift+F
. - Swipe left and right gestures to change slides on mobile browsers.
- Built for modern browsers (no support for old browsers).
- Support browser history, remember current slide shown on reload.
- Easy slide specific CSS styles with id attributes generated from headers.
- Intentionally kept simple to allow easy hacking and customization. If you don't like something, download the source code and change it.
- Tiny, currently 12 KiB in size (bundled, minified, not compressed).
- Printing the html document is unaffected; CSS styles are for screen media only.
- Might be one of the fastest ways to prepare a slide deck!
Usage
Prepare a Markdown document, with a <script>
tag referring
htsd.min.js
:
# Title
I'm the first slide.
---
## Topic 1
I'm the second slide.
---
# End
Thank you!
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/hackers-tiny-slide-deck@VERSION/build/htsd.min.js"></script>
Where VERSION
in the <script>
's src
attribute refers to a version
of this npm package.)
Convert the .md
file prepared above to .html
. Here, using marked:
marked -i example.md > example.html
Conventions to turn Markdown into slides
This section lists the special conventions to turn the content of html generated from a Markdown document into slides.
Horizontal separators (<hr>
) separate slides
## Slide 1
---
## Slide 2
The contents of each slide get wrapped in a <div>
tag, with style
class htsd-slide
. Every slide will have that as the base class. In
addition, slides may have additional modifier classes and id attributes;
read below for more.
You can utilize the base class (htsd-slide
) for styling global to all
slides.
Modifier class for the highest level header in a slide
# Title
## Topic 1
I'm centered.
---
## Topic 2
I'm not centered.
Here, the slide with <h1>Title</h1>
will have the htsd-slide--h1
modifier class in addition to the htsd-slide
base class. HTSD includes
CSS styles to center the content having the htsd-slide--h1
class.
The slide with <h2>Topic 2</h2>
gets htsd-slide--h2
as the modifier
class. HTSD has no special CSS styles for header levels below level 2,
but you can add them yourself.
Id attribute for the highest level header in a slide
The text contents of the highest level header in each slide is used to generate the id attributes for them. You can use this in the CSS selectors to customize styles (see example.md).
Customization
Customize styles
Use a <style media="screen">
tag to customize styles. There are custom
CSS properties to help your tuning needs:
@import url(https://fonts.googleapis.com/css?family=Roboto:400,400i,700);
/* override css custom properties */
:root {
--htsd-sans-font-family: 'Roboto', sans-serif;
--htsd-slide-bg-color: #f6f6f6;
--htsd-header-color: #262626;
--htsd-text-color: #1a1a1a;
}
/* override rules with selectors */
.htsd-slide em {
font-weight: bold;
}
See the end of example.md for more examples.
Syntax highlighting inside <code>
tags
You can enable syntax highlighting inside <code>
tags with an external
JavaScript library, such as Prism.js.
See the end of example.md to see how to highlight code with Prism.js.
Install HTSD manually
By default, loading htsd.min.js
with the <script>
tag automatically
installs all features. If you want to install features manually, use the
data-manual
attribute in the <script>
tag. For example:
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/hackers-tiny-slide-deck@VERSION/build/htsd.min.js" data-manual></script>
HTSD provides the following object in window
:
window.htsd = {
// calls, in order:
//
// 1. installStyles
// 2. installSlides
// 3. installNavigation
// 4. markInstalled
installAll: () => undefined,
// apply CSS styles by injecting a <style> tag into <head>;
// this will make <body> invisible (the document goes blank)
installStyles: () => undefined,
// wrap content into <div class="htsd-slide"> tags, to be used as slides
installSlides: () => undefined,
// 1. enable handling the hash part of browser location
// 2. show the selected slide (requires <body> to be visible, see `markInstalled`)
// 3. make keyboard shortcuts and swipe gestures available
installNavigation: () => undefined,
// add `htsd--installed` class to the <body> tag, make <body> visible
markInstalled: () => undefined
// contains HTSD version number
version: string
}
Now, you can call installAll
manually:
<script type="text/javascript">htsd.installAll()</script>
Calling the install*
or markInstalled
functions more than once leads
to undefined behavior. The implementation is simpler without attempting
to handle the complexities in different call combinations.
License
MIT. See LICENSE.txt.