Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/slidesk/slidesk

Speaker companion
https://github.com/slidesk/slidesk

bun slideshow

Last synced: about 1 month ago
JSON representation

Speaker companion

Host: GitHub
URL: https://github.com/slidesk/slidesk
Owner: slidesk
License: mit
Created: 2023-04-04T21:23:54.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2024-05-14T16:05:42.000Z (4 months ago)
Last Synced: 2024-05-15T14:24:04.600Z (4 months ago)
Topics: bun, slideshow
Language: TypeScript
Homepage: https://slidesk.github.io/slidesk/
Size: 27.7 MB
Stars: 47
Watchers: 1
Forks: 5
Open Issues: 4
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

# 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](https://bun.sh).

The `example` rendering is visible on [slidesk.github.io/slidesk/](https://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

```sh
brew tap gouz/tools && brew install slidesk
```

```sh
brew install gouz/tools/slidesk
```

#### Usage

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

Your presentation companion

Arguments:
talk the directory of your talk

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

Commands:
create
```

### 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

```sh
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 :

```sh
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:

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

Then you can use it through:

```sh
Usage: bunx slidesk [options] [command]

Your presentation companion

Arguments:
talk the directory of your talk

Commands:
create
```

## How to build SliDesk?

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

```sh
bun install
```

And create the "exe" file with:

```sh
bun make:exe
```

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

You can also use Gitpod :

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io#https://github.com/slidesk/slidesk/-/tree/main/)

## How to create a presentation

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

```
bunx slidesk
```

```
slidesk
```

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:

```css
: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.

```js
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)