https://github.com/tkareine/hackers-tiny-slide-deck
Turn a Markdown document into a slide deck quickly
https://github.com/tkareine/hackers-tiny-slide-deck
css hacking javascript markdown minimalist npm-package presentation-framework slide-deck slideshow slideshow-maker
Last synced: 19 days ago
JSON representation
Turn a Markdown document into a slide deck quickly
- Host: GitHub
- URL: https://github.com/tkareine/hackers-tiny-slide-deck
- Owner: tkareine
- License: mit
- Created: 2019-11-18T23:04:39.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-05-25T18:33:23.000Z (12 months ago)
- Last Synced: 2024-09-29T13:16:04.662Z (8 months ago)
- Topics: css, hacking, javascript, markdown, minimalist, npm-package, presentation-framework, slide-deck, slideshow, slideshow-maker
- Language: JavaScript
- Homepage: https://tkareine.github.io/hackers-tiny-slide-deck/example.html
- Size: 987 KB
- Stars: 8
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Hacker's Tiny Slide Deck (HTSD)
[][HTSD-npm-package]
[][HTSD-CI]
Turn a Markdown document into a slide deck, in two steps:
1. Add a `` tag referring the HTSD JavaScript bundle to the end
of the Markdown document. For example, accessing the bundle from
[jsDelivr] service:
``` html
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/hackers-tiny-slide-deck@VERSION/build/htsd.min.js">
```
(Replace `VERSION` with the version of this [npm
package][HTSD-npm-package].)
2. Convert the Markdown document into html. For example, using [marked]:
``` shell
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][example.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 slide
* `End` 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 `` tag referring
`htsd.min.js`:
``` markdown
# 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">
```
Where `VERSION` in the ``'s `src` attribute refers to a version
of this [npm package][HTSD-npm-package].)
Convert the `.md` file prepared above to `.html`. Here, using [marked]:
``` shell
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
``` markdown
## 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
``` markdown
# 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:
``` css
@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:
``` html
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/hackers-tiny-slide-deck@VERSION/build/htsd.min.js" data-manual>
```
HTSD provides the following object in `window`:
``` javascript
window.htsd = {
// calls, in order:
//
// 1. installStyles
// 2. installSlides
// 3. installNavigation
// 4. markInstalled
installAll: () => undefined,
// apply CSS styles by injecting a 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:
``` html
<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].
[HTSD-CI]: https://github.com/tkareine/hackers-tiny-slide-deck/actions/workflows/ci.yml
[HTSD-npm-package]: https://www.npmjs.com/package/hackers-tiny-slide-deck
[LICENSE.txt]: https://raw.githubusercontent.com/tkareine/hackers-tiny-slide-deck/master/LICENSE.txt
[Prism.js]: https://prismjs.com/
[example.html]: https://tkareine.github.io/hackers-tiny-slide-deck/example.html
[example.md]: https://raw.githubusercontent.com/tkareine/hackers-tiny-slide-deck/master/example.md
[jsDelivr]: https://www.jsdelivr.com/
[markdown-mode]: https://jblevins.org/projects/markdown-mode/
[marked]: https://github.com/markedjs/marked