Skip to content

slidesk/slidesk

Repository files navigation

SliDesk

A complete documentation is available here: https://slidesk.github.io/slidesk-doc/

Write your talk/presentation in Markdown, generate it and visualize it in Web.

SliDesk is a new talk engine like RevealJS developped with Bun.

The example rendering is visible on slidesk.github.io/slidesk/.

Plugins & Components can be found here : https://github.com/slidesk/slidesk-extras

A VSCode extension is available too : https://github.com/slidesk/vscode-sdf-language

How to use?

macOS with Homebrew

Installation

brew tap gouz/tools && brew install slidesk

or

brew install gouz/tools/slidesk

Usage

Usage: slidesk [options] [command] [talk]

Your presentation companion

Arguments:
  talk                   the directory of your talk

Options:
  -v, --version            output the version number
  -d, --domain <string>    domain (default: "localhost")
  -p, --port <int>         port (default: 1337)
  -s, --save <path>        save the presentation
  -n, --notes              open with speakers notes
  -t, --timers             add checkpoint and slide maximum time on notes view
  -a, --transition <int>   transition timer (default: 300)
  -w, --watch              watch modification of files
  -g, --hidden             remove help information
  -c, --conf <name>        use a specific .env file (default: "")
  -o, --open <browser>     open a browser with the presentation or notes view (browser is : chrome, edge, firefox, browser, browserPrivate)
  -h, --help               display help for command

Commands:
  create <talk>

Docker

Slidesk now has a DockerHub repository ! https://hub.docker.com/r/gouz/slidesk

To use it with your current working directory as your slidesk directory

docker run -it -v "$(pwd)"/:/slidesk/ -p 1337:1337 gouz/slidesk:latest

Slidesk is now accessible through http://localhost:1337. If you need additional arguments, specify them after specifying the slidesk binary. Example :

docker run -it -v "$(pwd)"/:/slidesk/ -p 1337:1337 gouz/slidesk:latest slidesk -tn

Other systems

If you want to compile SliDesk, you must have Bun installed on your computer.

If not, you can install it through:

curl -fsSL https://bun.sh/install | bash

Then you can use it through:

Usage: bunx slidesk [options] [command] <talk>

Your presentation companion

Arguments:
  talk                     the directory of your talk

Options:
  -v, --version            output the version number
  -d, --domain <string>    domain (default: "localhost")
  -p, --port <int>         port (default: 1337)
  -s, --save <path>        save the presentation
  -n, --notes              open with speakers notes
  -t, --timers             add checkpoint and slide maximum time on notes view
  -a, --transition <int>   transition timer (default: 300)
  -w, --watch              watch modification of files
  -g, --hidden             remove help information
  -c, --conf <name>        use a specific .env file (default: "")
  -o, --open <browser>     open a browser with the presentation or notes view (browser is : chrome, edge, firefox, browser, browserPrivate)
  -h, --help               display help for command

Commands:
  create <talk>

How to build SliDesk?

Once you clone the repository, you can install the dependencies with:

bun install

And create the "exe" file with:

bun make:exe

Then you'll have a exe/slidesk file created.

You can also use Gitpod :

Open in Gitpod

How to create a presentation

In a directory, create a main.sdf file which is the entry point of your presentation.

bunx slidesk <yourdirectory>

or

slidesk <yourdirectory>

will convert the main.sdf into a HTML file and serve it, it will open the default browser too.

A livereload is activated per default.

See the example directory to understand how it works or run

bun example

Customize theme

In your custom.css file, you can override this variables:

:root {
  --sd-heading1-size: 8.5vw;
  --sd-heading1-line-height: 1;
  --sd-heading2-size: 5vw;
  --sd-heading2-line-height: 1;
  --sd-text-size: 2.2vw;
  --sd-text-line-height: 1.2;

  --sd-background-color: #242424;
  --sd-heading-color: rgba(255, 255, 255, 0.97);
  --sd-text-color: rgba(255, 255, 255, 0.87);
  --sd-primary-color: rgb(37, 186, 146);

  /* SpeakerView */
  --sd-sv-timer-size: 80px;
  --sd-sv-text-size: 40px;
  --sd-sv-text-line-height: 1.2;
  --sd-sv-background-color: #242424;
  --sd-sv-text-color: rgba(255, 255, 255, 0.87);
}

Then, in your main.sdf file you have to prepend this line:

/::
custom_css: location/of/your/custom.css
::/

Custom class on slides

## My title .[my-class my-other-class]

Speakers Notes

/*
A comment in a page correspond to the notes for the speaker.
*/

Timers

You can specify checkpoint timers in your slide. They are visibles in Speaker Note View.

This following syntax means that at this slide, if you're under 22 minutes of your presentation, you're good.

//@ < 22:00

This following syntax means that this slide must be done in 2 minutes.

//@ [] 2:00

.env file

SliDesk can load a .env file. The content will be available in JS (for your plugins) with the property window.slidesk.env.

Reserved keys:

  • PLUGINS, used to specify internal plugins to load.
  • HTTPS, set to true, the server will listen to a secured connection
  • KEY, to specify the key file for https
  • CERT, to specity the cert file for https
  • PASSPHRASE, to give the passphrase of cert/key files
  • WIDTH, to force the width based to calc the ratio of images

You can get a variable defined in this .env file with a shortcode ++.

If you add a variable in .env:

MYVAR="this text will be displayed"

Then in the presentation, ++MYVAR++ will render this text will be displayed.

Plugins

SliDesk has a plugin system.

To use it, you have to create a plugins directory into your main directory (where main.sdf is).

There is some samples in this repository.

A plugin is a directory with at least one file: plugin.json

This json file describes the comportement of the plugin. Each keys of the json correspond to a "hook":

  • addHTML: add some html at the end of the presentation
  • addHTMLFromFiles: an array of html files to append in the
  • addScripts: an array of ressources to load (will be convert to script tag with src value as each entry)
  • addSpeakerScripts: an array of ressources to load (will be convert to script tag with src value as each entry) but on speaker view
  • addStyles: an array of ressources to load (will be convert to link tag with href value as each entry)
  • addSpeakerStyles: an array of ressources to load (will be convert to link tag with href value as each entry) but on speaker view
  • onSlideChange: javascript code which will be executed after a slide is changed
  • onSpeakerViewSlideChange: javascript code which will be executed after a slide is changed
  • addWS: a .mjs file will be imported on Server launch
  • addRoutes: a .mjs file will be imported on Server launch

If you want to use one of the "core" plugins, available in this repository, you don't need to copy them. You have just to create a .env file in your root directory of the talk, and precise the plugins you need:

PLUGINS="source, qrcode"

Components

SliDesk has a component system.

To use it, you have to create a components directory into your main directory (where main.sdf is).

In this directory, you can add custom components with a .mjs file. One per component.

Example:

I want to have a !test(my text) which generate a Test: my text.

So I create a components/test.mjs with the following content.

export default (data) => {
  let newData = data;
  [...newData.matchAll(/!test\((.*)\)/g)].forEach((match) => {
    newData = newData.replace(match[0], `Test: ${match[1]}`);
  });
  return newData;
};

Then a dynamic call will be done when parsing a slide (at the end of default parsing).

Add scripts & styles without plugins

In the special header /:: ::/, you can specify files to includes (locals or distants), separated with a comma ,, with the following keys:

  • add_styles: to add css files, which will be inserted before custom_css.
  • add_scripts: to add js, which will be inserted before any script tag.

HTTPS

SliDesk is per default listening on port 1337 with an HTTP protocol.

You can enable HTTPS with the .env file:

HTTPS=true
KEY=absolute path of the key file
CERT=absolute path of the cert file
PASSPHRASE=the passphrase if needed

On Chromium-based browsers, in the Speaker view, you will see buttons that can open the Presentation view on the screen you want.

If the parameter "Fullscreen popup windows" is enabled in "chrome://flags/", then the presentation will be opened in fullscreen.

Why a new tool???

I decided to create my own tool for my talks, because:

  • It's fun to create something
  • I want to have a tool which do only the minimum
  • I want a very tiny light tool
  • I want it to be permissive a lot (you can add html tags in without any problem)