cybercyst/presenterm
1
0
Fork 0
mirror of https://github.com/mfontanini/presenterm.git synced 2025-05-05 23:42:59 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

docs: add docs on 0.10.0 features

Browse Source
This commit is contained in:
Matias Fontanini 2025-02-01 14:30:44 -08:00
parent 09e9f003ed
commit fd45d96e1c
12 changed files with 341 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/src/SUMMARY.md
View File

@ -11,6 +11,7 @@
- [Configuration](./guides/configuration.md) - [Configuration](./guides/configuration.md)
- [Code highlighting](./guides/code-highlight.md) - [Code highlighting](./guides/code-highlight.md)
- [PDF export](./guides/pdf-export.md) - [PDF export](./guides/pdf-export.md)
- [Speaker notes](./guides/speaker-notes.md)
- [Mermaid](./guides/mermaid.md) - [Mermaid](./guides/mermaid.md)
- [LaTeX and typst](./guides/latex.md) - [LaTeX and typst](./guides/latex.md)

95
docs/src/guides/basics.md
View File

@ -1,19 +1,19 @@
## Introduction # Introduction
This guide teaches you how to use _presenterm_. At this point you should have already installed _presenterm_, otherwise This guide teaches you how to use _presenterm_. At this point you should have already installed _presenterm_, otherwise
visit the [installation](installation.html) guide to get started. visit the [installation](installation.html) guide to get started.
### Quick start ## Quick start
Download the demo presentation and run it using: Download the demo presentation and run it using:
```shell ```bash
git clone https://github.com/mfontanini/presenterm.git git clone https://github.com/mfontanini/presenterm.git
cd presenterm cd presenterm
presenterm examples/demo.md presenterm examples/demo.md
``` ```
## Presentations # Presentations
A presentation in _presenterm_ is a single markdown file. Every slide in the presentation file is delimited by a line A presentation in _presenterm_ is a single markdown file. Every slide in the presentation file is delimited by a line
that contains a single HTML comment: that contains a single HTML comment:
@ -25,7 +25,24 @@ that contains a single HTML comment:
Presentations can contain most commonly used markdown elements such as ordered and unordered lists, headings, formatted Presentations can contain most commonly used markdown elements such as ordered and unordered lists, headings, formatted
text (**bold**, _italics_, ~strikethrough~, `inline code`, etc), code blocks, block quotes, tables, etc. text (**bold**, _italics_, ~strikethrough~, `inline code`, etc), code blocks, block quotes, tables, etc.
### Images ## Colored text
`span` HTML tags can be used to provide foreground and/or background colors to text. Currently only the `style`
attribute is supported, and only the CSS attributes `color` and `background-color` can be used to set the foreground and
background colors respectively. Colors used in both CSS attributes can refer to [theme palette
colors](themes.html#color-palette) by using the `palette:<name>` or `p:<name` syntaxes.
For example, the following will use `ff0000` as the foreground color and whatever the active theme's palette defines as
`foo`:
```markdown
<span style="color: #ff0000; background-color: palette:foo">colored text!</span>
```
> [!note]
> Keep in mind **only `span` tags are supported**.
## Images
![](../assets/demo-image.png) ![](../assets/demo-image.png)
@ -34,19 +51,20 @@ protocol](https://iterm2.com/documentation-images.html), the [kitty graphics
protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/), or [sixel](https://saitoha.github.io/libsixel/). Some of protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/), or [sixel](https://saitoha.github.io/libsixel/). Some of
the terminals where at least one of these is supported are: the terminals where at least one of these is supported are:
* kitty * [kitty](https://sw.kovidgoyal.net/kitty/)
* iterm2 * [iterm2](https://iterm2.com/)
* wezterm * [WezTerm](https://wezfurlong.org/wezterm/index.html)
* foot * [foot](https://codeberg.org/dnkl/foot)
Note that sixel support is experimental so it needs to be explicitly enabled via the `sixel` configuration flag: Sixel support is experimental so it needs to be explicitly enabled via the `sixel` configuration flag:
```shell ```bash
cargo build --release --features sixel cargo build --release --features sixel
``` ```
> **Note**: this feature flag is only needed if your terminal emulator only supports sixel. Many terminals support the > [!note]
> kitty or iterm2 protocols so this isn't necessary. > This feature flag is only needed if your terminal emulator _only_ supports sixel. Many terminals support the kitty or
> iterm2 protocols so using this flag is often not required to get images to render successfully.
--- ---
@ -60,7 +78,7 @@ Things you should know when using image tags in your presentation's markdown are
* If your terminal does not support any of the graphics protocol above, images will be rendered using ascii blocks. It * If your terminal does not support any of the graphics protocol above, images will be rendered using ascii blocks. It
ain't great but it's something! ain't great but it's something!
#### Image size ### Image size
The size of each image can be set by using the `image:width` or `image:w` attributes in the image tag. For example, the The size of each image can be set by using the `image:width` or `image:w` attributes in the image tag. For example, the
following will cause the image to take up 50% of the terminal width: following will cause the image to take up 50% of the terminal width:
@ -72,22 +90,22 @@ following will cause the image to take up 50% of the terminal width:
The image will always be scaled to preserve its aspect ratio and it will not be allowed to overflow vertically nor The image will always be scaled to preserve its aspect ratio and it will not be allowed to overflow vertically nor
horizontally. horizontally.
#### Protocol detection ### Protocol detection
By default the image protocol to be used will be automatically detected. In cases where this detection fails (e.g. when By default the image protocol to be used will be automatically detected. In cases where this detection fails, you can
running inside `tmux`), you can set it manually via the `--image-protocol` parameter or by setting it in the [config set it manually via the `--image-protocol` parameter or by setting it in the [config
file](configuration.html#preferred-image-protocol). file](configuration.html#preferred-image-protocol).
## Extensions # Extensions
Besides the standard markdown elements, _presenterm_ supports a few extensions. Besides the standard markdown elements, _presenterm_ supports a few extensions.
### Introduction slide ## Introduction slide
By setting a front matter at the beginning of your presentation, you can configure the title, sub title, and author of By setting a front matter at the beginning of your presentation, you can configure the title, sub title, and author of
your presentation and implicitly create an introduction slide: your presentation and implicitly create an introduction slide:
```markdown ```yaml
--- ---
title: My first presentation title: My first presentation
sub_title: (in presenterm!) sub_title: (in presenterm!)
@ -97,12 +115,12 @@ author: Myself
All of these attributes are optional so you're not forced to set them all. All of these attributes are optional so you're not forced to set them all.
#### Multiple authors ### Multiple authors
If you're creating a presentation in which there's multiple authors, you can use the `authors` key instead of `author` If you're creating a presentation in which there's multiple authors, you can use the `authors` key instead of `author`
and list them all this way: and list them all this way:
```markdown ```yaml
--- ---
title: Our first presentation title: Our first presentation
authors: authors:
@ -111,21 +129,22 @@ authors:
--- ---
``` ```
### Slide titles ## Slide titles
Any [setext header](https://spec.commonmark.org/0.30/#setext-headings) will be considered to be a slide title and will Any [setext header](https://spec.commonmark.org/0.30/#setext-headings) will be considered to be a slide title and will
be rendered in a more slide-title-looking way. By default this means it will be centered, some vertical padding will be be rendered in a more slide-title-looking way. By default this means it will be centered, some vertical padding will be
added and the text color will be different. added and the text color will be different.
~~~ ~~~markdown
Hello Hello
=== ===
~~~ ~~~
> Note: see the [themes](themes.html) section on how to customize the looks of slide titles and any other element in a > [!note]
> See the [themes](themes.html) section on how to customize the looks of slide titles and any other element in a
> presentation. > presentation.
### Pauses ## Pauses
Pauses allow the sections of the content in your slide to only show up when you advance in your presentation. That is, Pauses allow the sections of the content in your slide to only show up when you advance in your presentation. That is,
only after you press, say, the right arrow will a section of the slide show up. This can be done by the `pause` comment only after you press, say, the right arrow will a section of the slide show up. This can be done by the `pause` comment
@ -135,7 +154,7 @@ command:
<!-- pause --> <!-- pause -->
``` ```
### Ending slides ## Ending slides
While other applications use a thematic break (`---`) to mark the end of a slide, _presenterm_ uses a special While other applications use a thematic break (`---`) to mark the end of a slide, _presenterm_ uses a special
`end_slide` HTML comment: `end_slide` HTML comment:
@ -150,7 +169,7 @@ This makes the end of a slide more explicit and easy to spot while you're editin
If you really would prefer to use thematic breaks (`---`) to delimit slides, you can do that by enabling the If you really would prefer to use thematic breaks (`---`) to delimit slides, you can do that by enabling the
[`end_slide_shorthand`](configuration.html#end_slide_shorthand) options. [`end_slide_shorthand`](configuration.html#end_slide_shorthand) options.
### Jumping to the vertical center ## Jumping to the vertical center
The command `jump_to_middle` lets you jump to the middle of the page vertically. This is useful in combination The command `jump_to_middle` lets you jump to the middle of the page vertically. This is useful in combination
with slide titles to create separator slides: with slide titles to create separator slides:
@ -170,7 +189,7 @@ Farming potatoes
This will create a slide with the text "Farming potatoes" in the center, rendered using the slide title style. This will create a slide with the text "Farming potatoes" in the center, rendered using the slide title style.
### Explicit new lines ## Explicit new lines
The `newline`/`new_line` and `newlines`/`new_lines` commands allow you to explicitly create new lines. Because markdown The `newline`/`new_line` and `newlines`/`new_lines` commands allow you to explicitly create new lines. Because markdown
ignores multiple line breaks in a row, this is useful to create some spacing where necessary: ignores multiple line breaks in a row, this is useful to create some spacing where necessary:
@ -187,7 +206,7 @@ mom
bye bye
``` ```
### Incremental lists ## Incremental lists
Using `<!-- pause -->` in between each bullet point a list is a bit tedious so instead you can use the Using `<!-- pause -->` in between each bullet point a list is a bit tedious so instead you can use the
`incremental_lists` command to tell _presenterm_ that **until the end of the current slide** you want each individual `incremental_lists` command to tell _presenterm_ that **until the end of the current slide** you want each individual
@ -207,7 +226,7 @@ bullet point to appear only after you move to the next slide:
* all at once * all at once
``` ```
## Key bindings # Key bindings
Navigation within a presentation should be intuitive: jumping to the next/previous slide can be done by using the arrow Navigation within a presentation should be intuitive: jumping to the next/previous slide can be done by using the arrow
keys, _hjkl_, and page up/down keys. keys, _hjkl_, and page up/down keys.
@ -219,18 +238,20 @@ Besides this:
* Jumping to a specific slide: `<slide-number>G`. * Jumping to a specific slide: `<slide-number>G`.
* Exit the presentation: `<ctrl>c`. * Exit the presentation: `<ctrl>c`.
### Configuring key bindings You can check all the configured keybindings by pressing `?` while running _presenterm_.
## Configuring key bindings
If you don't like the default key bindings, you can override them in the [configuration If you don't like the default key bindings, you can override them in the [configuration
file](configuration.html#key-bindings). file](configuration.html#key-bindings).
## Modals # Modals
_presenterm_ currently has 2 modals that can provide some information while running the application. Modals can be _presenterm_ currently has 2 modals that can provide some information while running the application. Modals can be
toggled using some key combination and can be hidden using the escape key by default, but these can be configured via toggled using some key combination and can be hidden using the escape key by default, but these can be configured via
the [configuration file key bindings](configuration.html#key-bindings). the [configuration file key bindings](configuration.html#key-bindings).
### Slide index modal ## Slide index modal
This modal can be toggled by default using `control+p` and lets you see an index that contains a row for every slide in This modal can be toggled by default using `control+p` and lets you see an index that contains a row for every slide in
the presentation, including its title and slide index. This allows you to find a slide you're trying to jump to the presentation, including its title and slide index. This allows you to find a slide you're trying to jump to
@ -238,11 +259,11 @@ quicklier rather than scanning through each of them.
[![asciicast](https://asciinema.org/a/1VgRxVIEyLrMmq6OZ3oKx4PGi.svg)](https://asciinema.org/a/1VgRxVIEyLrMmq6OZ3oKx4PGi) [![asciicast](https://asciinema.org/a/1VgRxVIEyLrMmq6OZ3oKx4PGi.svg)](https://asciinema.org/a/1VgRxVIEyLrMmq6OZ3oKx4PGi)
### Key bindings modal ## Key bindings modal
The key bindings modal displays the key bindings for each of the supported actions. The key bindings modal displays the key bindings for each of the supported actions and can be opened by pressing `?`.
## Hot reload # Hot reload
Unless you run in presentation mode by passing in the `--present` parameter, _presenterm_ will automatically reload your Unless you run in presentation mode by passing in the `--present` parameter, _presenterm_ will automatically reload your
presentation file every time you save it. _presenterm_ will also automatically detect which specific slide was modified presentation file every time you save it. _presenterm_ will also automatically detect which specific slide was modified

50
docs/src/guides/code-highlight.md
View File

@ -1,4 +1,4 @@
## Code highlighting # Code highlighting
Code highlighting is supported for the following languages: Code highlighting is supported for the following languages:
@ -47,6 +47,7 @@ Code highlighting is supported for the following languages:
* sql * sql
* swift * swift
* svelte * svelte
* tcl
* toml * toml
* terraform * terraform
* typescript * typescript
@ -55,7 +56,7 @@ Code highlighting is supported for the following languages:
* vue * vue
* zig * zig
### Enabling line numbers ## Enabling line numbers
If you would like line numbers to be shown on the left of a code block use the `+line_numbers` switch after specifying If you would like line numbers to be shown on the left of a code block use the `+line_numbers` switch after specifying
the language in a code block: the language in a code block:
@ -68,7 +69,7 @@ the language in a code block:
``` ```
~~~ ~~~
### Selective highlighting ## Selective highlighting
By default, the entire code block will be syntax-highlighted. If instead you only wanted a subset of it to be By default, the entire code block will be syntax-highlighted. If instead you only wanted a subset of it to be
highlighted, you can use braces and a list of either individual lines, or line ranges that you'd want to highlight. highlighted, you can use braces and a list of either individual lines, or line ranges that you'd want to highlight.
@ -85,7 +86,7 @@ highlighted, you can use braces and a list of either individual lines, or line r
``` ```
~~~ ~~~
### Dynamic highlighting ## Dynamic highlighting
Similar to the syntax used for selective highlighting, dynamic highlighting will change which lines of the code in a Similar to the syntax used for selective highlighting, dynamic highlighting will change which lines of the code in a
code block are highlighted every time you move to the next/previous slide. code block are highlighted every time you move to the next/previous slide.
@ -113,7 +114,7 @@ See this real example of how this looks like.
[![asciicast](https://asciinema.org/a/iCf4f6how1Ux3H8GNzksFUczI.svg)](https://asciinema.org/a/iCf4f6how1Ux3H8GNzksFUczI) [![asciicast](https://asciinema.org/a/iCf4f6how1Ux3H8GNzksFUczI.svg)](https://asciinema.org/a/iCf4f6how1Ux3H8GNzksFUczI)
### Including external code snippets ## Including external code snippets
The `file` snippet type can be used to specify an external code snippet that will be included and highlighted as usual. The `file` snippet type can be used to specify an external code snippet that will be included and highlighted as usual.
@ -124,14 +125,14 @@ language: rust
``` ```
~~~ ~~~
### Showing a snippet without a background ## Showing a snippet without a background
Using the `+no_background` flag will cause the snippet to have no background. This is useful when combining it with the Using the `+no_background` flag will cause the snippet to have no background. This is useful when combining it with the
`+exec_replace` flag described further down. `+exec_replace` flag described further down.
## Snippet execution # Snippet execution
### Executing code blocks ## Executing code blocks
Annotating a code block with a `+exec` attribute will make it executable. Pressing `control+e` when viewing a slide that Annotating a code block with a `+exec` attribute will make it executable. Pressing `control+e` when viewing a slide that
contains an executable block, the code in the snippet will be executed and the output of the execution will be displayed contains an executable block, the code in the snippet will be executed and the output of the execution will be displayed
@ -159,6 +160,7 @@ The list of languages that support execution are:
* c * c
* fish * fish
* go * go
* haskell
* java * java
* js * js
* kotlin * kotlin
@ -167,12 +169,14 @@ The list of languages that support execution are:
* perl * perl
* php * php
* python * python
* r
* ruby * ruby
* rust * rust
* rust-script: this highlights as normal Rust but uses [rust-script](https://rust-script.org/) to execute the snippet so * rust-script: this highlights as normal Rust but uses [rust-script](https://rust-script.org/) to execute the snippet so
it lets you use dependencies. it lets you use dependencies.
* sh * sh
* zsh * zsh
* c#
If there's a language that is not in this list and you would like it to be supported, please [create an If there's a language that is not in this list and you would like it to be supported, please [create an
issue](https://github.com/mfontanini/presenterm/issues/new) providing details on how to compile (if necessary) and run issue](https://github.com/mfontanini/presenterm/issues/new) providing details on how to compile (if necessary) and run
@ -181,9 +185,11 @@ file](configuration.html#custom-snippet-executors).
[![asciicast](https://asciinema.org/a/BbAY817esxagCgPtnKUwgYnHr.svg)](https://asciinema.org/a/BbAY817esxagCgPtnKUwgYnHr) [![asciicast](https://asciinema.org/a/BbAY817esxagCgPtnKUwgYnHr.svg)](https://asciinema.org/a/BbAY817esxagCgPtnKUwgYnHr)
> **Note**: because this is spawning a process and executing code, you should use this at your own risk. > [!warning]
> Run code in presentations at your own risk! Especially if you're running someone else's presentation. Don't blindly
> enable snippet execution!
### Executing and replacing ## Executing and replacing
Similar to `+exec`, `+exec_replace` causes a snippet to be executable but: Similar to `+exec`, `+exec_replace` causes a snippet to be executable but:
@ -198,7 +204,21 @@ Because of the risk involved in `+exec_replace`, where code gets automatically e
this requires users to explicitly opt in to it. This can be done by either passing in the `-X` command line parameter this requires users to explicitly opt in to it. This can be done by either passing in the `-X` command line parameter
or setting the `snippet.exec_replace.enable` flag in your configuration file to `true`. or setting the `snippet.exec_replace.enable` flag in your configuration file to `true`.
### Executing snippets that need a TTY ## Code to image conversions
The `+image` attribute behaves like `+exec_replace` but also assumes the output of the executed snippet will be an
image, and it will render it as such. For this to work, the code **must only emit an image in jpg/png formats** and
nothing else.
For example, this would render the demo presentation's image:
```bash +image
cat examples/doge.png
```
This attribute carries the same risks as `+exec_replace` and therefore needs to be enabled via the same flags.
## Executing snippets that need a TTY
If you're trying to execute a program like `top` that needs to run on a TTY as it renders text, clears the screen, etc, If you're trying to execute a program like `top` that needs to run on a TTY as it renders text, clears the screen, etc,
you can use the `+acquire_terminal` modifier on a code already marked as executable with `+exec`. Executing snippets you can use the `+acquire_terminal` modifier on a code already marked as executable with `+exec`. Executing snippets
@ -207,7 +227,7 @@ raw terminal to do whatever it needs, and upon its completion _presenterm_ will
[![asciicast](https://asciinema.org/a/AHfuJorCNRR8ZEnfwQSDR5vPT.svg)](https://asciinema.org/a/AHfuJorCNRR8ZEnfwQSDR5vPT) [![asciicast](https://asciinema.org/a/AHfuJorCNRR8ZEnfwQSDR5vPT.svg)](https://asciinema.org/a/AHfuJorCNRR8ZEnfwQSDR5vPT)
### Styled execution output ## Styled execution output
Snippets that generate output which contains escape codes that change the colors or styling of the text will be parsed Snippets that generate output which contains escape codes that change the colors or styling of the text will be parsed
and displayed respecting those styles. Do note that you may need to force certain tools to use colored output as they and displayed respecting those styles. Do note that you may need to force certain tools to use colored output as they
@ -223,7 +243,7 @@ ls /tmp --color=always
The parameter or way to enable this will depend on the tool being invoked. The parameter or way to enable this will depend on the tool being invoked.
### Hiding code lines ## Hiding code lines
When you mark a code snippet as executable via the `+exec` flag, you may not be interested in showing _all the lines_ to When you mark a code snippet as executable via the `+exec` flag, you may not be interested in showing _all the lines_ to
your audience, as some of them may not be necessary to convey your point. For example, you may want to hide imports, your audience, as some of them may not be necessary to convey your point. For example, you may want to hide imports,
@ -251,7 +271,7 @@ basis. The languages that are supported and their prefix is:
This means that any line in a rust code snippet that starts with `# ` will be hidden, whereas all lines in, say, a This means that any line in a rust code snippet that starts with `# ` will be hidden, whereas all lines in, say, a
golang code snippet that starts with a `/// ` will be hidden. golang code snippet that starts with a `/// ` will be hidden.
### Pre-rendering ## Pre-rendering
Some languages support pre-rendering. This means the code block is transformed into something else when the presentation Some languages support pre-rendering. This means the code block is transformed into something else when the presentation
is loaded. The languages that currently support this are _mermaid_, _LaTeX_, and _typst_ where the contents of the code is loaded. The languages that currently support this are _mermaid_, _LaTeX_, and _typst_ where the contents of the code
@ -260,7 +280,7 @@ using the `+render` attribute on a code block.
See the [LaTeX and typst](latex.html) and [mermaid](mermaid.html) docs for more information. See the [LaTeX and typst](latex.html) and [mermaid](mermaid.html) docs for more information.
### Adding highlighting syntaxes for new languages ## Adding highlighting syntaxes for new languages
_presenterm_ uses the syntaxes supported by [bat](https://github.com/sharkdp/bat) to highlight code snippets, so any _presenterm_ uses the syntaxes supported by [bat](https://github.com/sharkdp/bat) to highlight code snippets, so any
languages supported by _bat_ natively can be added to _presenterm_ easily. Please create a ticket or use languages supported by _bat_ natively can be added to _presenterm_ easily. Please create a ticket or use

47
docs/src/guides/configuration.md
View File

@ -1,4 +1,4 @@
## Configuration # Configuration
_presenterm_ allows you to customize its behavior via a configuration file. This file is stored, along with all of your _presenterm_ allows you to customize its behavior via a configuration file. This file is stored, along with all of your
custom themes, in the following directories: custom themes, in the following directories:
@ -29,7 +29,7 @@ The supported configuration options are currently the following:
This option removes the need to use `<!-- end_slide -->` in between slides and instead assumes that if you use a slide This option removes the need to use `<!-- end_slide -->` in between slides and instead assumes that if you use a slide
title, then you're implying that the previous slide ended. For example, the following presentation: title, then you're implying that the previous slide ended. For example, the following presentation:
``` ```markdown
--- ---
options: options:
implicit_slide_ends: true implicit_slide_ends: true
@ -157,7 +157,7 @@ The [image size](basics.html#image-size) prefix (by default `image:`) can be con
case you don't like the default one. For example, if you'd like to set the image size by simply doing case you don't like the default one. For example, if you'd like to set the image size by simply doing
`![width:50%](path.png)` you would need to set: `![width:50%](path.png)` you would need to set:
``` ```yaml
--- ---
options: options:
image_attributes_prefix: "" image_attributes_prefix: ""
@ -166,6 +166,20 @@ options:
![width:50%](path.png) ![width:50%](path.png)
``` ```
### auto_render_languages
This option allows indicating a list of languages for which the `+render` attribute can be omitted in their code
snippets and will be implicitly considered to be set. This can be used for languages like `mermaid` so that graphs are
always automatically rendered without the need to specify `+render` everywhere.
```yaml
---
options:
auto_render_languages:
- mermaid
---
```
## Defaults ## Defaults
Defaults **can only be configured via the configuration file**. Defaults **can only be configured via the configuration file**.
@ -197,9 +211,9 @@ defaults:
### Preferred image protocol ### Preferred image protocol
By default _presenterm_ will try to detect which image protocol to use based on the terminal you are using. In some By default _presenterm_ will try to detect which image protocol to use based on the terminal you are using. In case
cases this may fail, for example when using `tmux`. In those cases, you can explicitly set this via the detection for some reason fails in your setup or you'd like to force a different protocol to be used, you can explicitly
`--image-protocol` parameter or the configuration key `defaults.image_protocol`: set this via the `--image-protocol` parameter or the configuration key `defaults.image_protocol`:
```yaml ```yaml
defaults: defaults:
@ -215,6 +229,17 @@ Possible values are:
* `iterm2`: use the iterm2 protocol. * `iterm2`: use the iterm2 protocol.
* `sixel`: use the sixel protocol. Note that this requires compiling _presenterm_ using the `--features sixel` flag. * `sixel`: use the sixel protocol. Note that this requires compiling _presenterm_ using the `--features sixel` flag.
### Maximum presentation width
The `max_columns` property can be set to specify the maximum number of columns that the presentation will stretch to. If
your terminal is larger than that, the presentation will stick to that size and will be centered, preventing it from
looking too stretched.
```yaml
defaults:
max_columns: 100
```
## Key bindings ## Key bindings
Key bindings that _presenterm_ uses can be manually configured in the config file via the `bindings` key. The following Key bindings that _presenterm_ uses can be manually configured in the config file via the `bindings` key. The following
@ -356,3 +381,13 @@ mermaid:
scale: 2 scale: 2
``` ```
### Enabling speaker note publishing
If you don't want to run _presenterm_ with `--publish-speaker-notes` every time you want to publish speaker notes, you
can set the `speaker_notes.always_publish` attribute to `true`.
```yaml
speaker_notes:
always_pubblish: true
```

32
docs/src/guides/installation.md
View File

@ -1,41 +1,41 @@
## Installation # Installation
_presenterm_ works on Linux, macOS, and Windows and can be installed in different ways: _presenterm_ works on Linux, macOS, and Windows and can be installed in different ways:
### Pre-built binaries (recommended) ## Pre-built binaries (recommended)
The recommended way to install _presenterm_ is to download the latest pre-built version for The recommended way to install _presenterm_ is to download the latest pre-built version for
your system from the [releases](https://github.com/mfontanini/presenterm/releases) page. your system from the [releases](https://github.com/mfontanini/presenterm/releases) page.
### Install via cargo ## Install via cargo
Alternatively, download [rust](https://www.rust-lang.org/) and run: Alternatively, download [rust](https://www.rust-lang.org/) and run:
```shell ```bash
cargo install --locked presenterm cargo install --locked presenterm
``` ```
### Latest unreleased version ## Latest unreleased version
To install from the latest source code run: To install from the latest source code run:
```shell ```bash
cargo install --git https://github.com/mfontanini/presenterm cargo install --git https://github.com/mfontanini/presenterm
``` ```
### macOS ## macOS
Install the latest version in macOS via [brew](https://formulae.brew.sh/formula/presenterm) by running: Install the latest version in macOS via [brew](https://formulae.brew.sh/formula/presenterm) by running:
```shell ```bash
brew install presenterm brew install presenterm
``` ```
### Nix ## Nix
To install _presenterm_ using the Nix package manager run: To install _presenterm_ using the Nix package manager run:
```shell ```bash
nix-env -iA nixos.presenterm # for nixos nix-env -iA nixos.presenterm # for nixos
nix-env -iA nixpkgs.presenterm # for non-nixos nix-env -iA nixpkgs.presenterm # for non-nixos
``` ```
@ -56,13 +56,13 @@ nix run github:mfontanini/presenterm # to run from github repo
``` ```
For more information see For more information see
[nixpkgs](https://search.nixos.org/packages?channel=unstable&show=presenterm&from=0&size=50&sort=relevance&type=packages&query=presenterm) [nixpkgs](https://search.nixos.org/packages?channel=unstable&show=presenterm&from=0&size=50&sort=relevance&type=packages&query=presenterm).
### Arch Linux ## Arch Linux
_presenterm_ is available in the [official repositories](https://archlinux.org/packages/extra/x86_64/presenterm/). You can use [pacman](https://wiki.archlinux.org/title/pacman) to install as follows: _presenterm_ is available in the [official repositories](https://archlinux.org/packages/extra/x86_64/presenterm/). You can use [pacman](https://wiki.archlinux.org/title/pacman) to install as follows:
```shell ```bash
pacman -S presenterm pacman -S presenterm
``` ```
@ -70,17 +70,17 @@ pacman -S presenterm
Alternatively, you can use any AUR helper to install the upstream binaries: Alternatively, you can use any AUR helper to install the upstream binaries:
```shell ```bash
paru/yay -S presenterm-bin paru/yay -S presenterm-bin
``` ```
#### Building from git #### Building from git
```shell ```bash
paru/yay -S presenterm-git paru/yay -S presenterm-git
``` ```
### Windows ## Windows
Install the latest version in Scoop via [Scoop](https://scoop.sh/#/apps?q=presenterm&id=a462290f824b50f180afbaa6d8c7c1e6e0952e3a) by running: Install the latest version in Scoop via [Scoop](https://scoop.sh/#/apps?q=presenterm&id=a462290f824b50f180afbaa6d8c7c1e6e0952e3a) by running:

18
docs/src/guides/latex.md
View File

@ -1,17 +1,17 @@
## LaTeX and typst # LaTeX and typst
`latex` and `typst` code blocks can be marked with the `+render` attribute (see [highlighting](code-highlight.html)) to `latex` and `typst` code blocks can be marked with the `+render` attribute (see [highlighting](code-highlight.html)) to
have them rendered into images when the presentation is loaded. This allows you to define formulas in text rather than have them rendered into images when the presentation is loaded. This allows you to define formulas in text rather than
having to define them somewhere else, transform them into an image, and them embed it. having to define them somewhere else, transform them into an image, and them embed it.
### Dependencies ## Dependencies
#### typst ### typst
The engine used to render both of these languages is [typst](https://github.com/typst/typst). _typst_ is easy to The engine used to render both of these languages is [typst](https://github.com/typst/typst). _typst_ is easy to
install, lightweight, and boilerplate free as compared to _LaTeX_. install, lightweight, and boilerplate free as compared to _LaTeX_.
#### pandoc ### pandoc
For _LaTeX_ code rendering, besides _typst_ you will need to install [pandoc](https://github.com/jgm/pandoc). How this For _LaTeX_ code rendering, besides _typst_ you will need to install [pandoc](https://github.com/jgm/pandoc). How this
works is the _LaTeX_ code you write gets transformed into _typst_ code via _pandoc_ and then rendered by using _typst_. works is the _LaTeX_ code you write gets transformed into _typst_ code via _pandoc_ and then rendered by using _typst_.
@ -20,7 +20,7 @@ This lets us:
* Avoid having to write lots of boilerplate _LaTeX_ to make rendering for that language work. * Avoid having to write lots of boilerplate _LaTeX_ to make rendering for that language work.
* Have the same logic to render formulas for both languages, except with a small preparation step for _LaTeX_. * Have the same logic to render formulas for both languages, except with a small preparation step for _LaTeX_.
### Controlling PPI ## Controlling PPI
_presenterm_ lets you define how many Pixels Per Inch (PPI) you want in the generated images. This is important because _presenterm_ lets you define how many Pixels Per Inch (PPI) you want in the generated images. This is important because
as opposed to images that you manually include in your presentation, where you control the exact dimensions, the images as opposed to images that you manually include in your presentation, where you control the exact dimensions, the images
@ -37,7 +37,7 @@ typst:
The default is 300 so adjust it and see what works for you. The default is 300 so adjust it and see what works for you.
### Image paths ## Image paths
If you're including an image inside a _typst_ snippet, you must: If you're including an image inside a _typst_ snippet, you must:
@ -47,7 +47,7 @@ at `/tmp/foo/presentation.md`, you can place images in `/tmp/foo`, and `/tmp/foo
because of the absolute path rule above: the path will be considered to be relative to the presentation file's because of the absolute path rule above: the path will be considered to be relative to the presentation file's
directory. directory.
### Controlling the image size ## Controlling the image size
You can also set the generated image's size on a per code snippet basis by using the `+width` modifier which specifies You can also set the generated image's size on a per code snippet basis by using the `+width` modifier which specifies
the width of the image as a percentage of the terminal size. the width of the image as a percentage of the terminal size.
@ -58,7 +58,7 @@ $f(x) = x + 1$
``` ```
~~~ ~~~
### Customizations ## Customizations
The colors and margin of the generated images can be defined in your theme: The colors and margin of the generated images can be defined in your theme:
@ -73,7 +73,7 @@ typst:
vertical_margin: 2 vertical_margin: 2
``` ```
## Example # Example
The following example: The following example:

14
docs/src/guides/layout.md
View File

@ -1,4 +1,4 @@
## Layouts # Layouts
_presenterm_ currently supports a column layout that lets you split parts of your slides into column. This allows you to _presenterm_ currently supports a column layout that lets you split parts of your slides into column. This allows you to
put text on one side, and code/images on the other, or really organize markdown into columns in any way you want. put text on one side, and code/images on the other, or really organize markdown into columns in any way you want.
@ -6,7 +6,7 @@ put text on one side, and code/images on the other, or really organize markdown
This is done by using commands, just like `pause` and `end_slide`, in the form of HTML comments. This section describes This is done by using commands, just like `pause` and `end_slide`, in the form of HTML comments. This section describes
how to use those. how to use those.
### Wait, why not HTML? ## Wait, why not HTML?
While markdown _can_ contain HTML tags (beyond comments!) and we _could_ represent this using divs with alignment, I While markdown _can_ contain HTML tags (beyond comments!) and we _could_ represent this using divs with alignment, I
don't really want to: don't really want to:
@ -17,12 +17,12 @@ don't really want to:
Because of this, _presenterm_ doesn't let you use HTML and instead has a custom way of specifying column layouts. Because of this, _presenterm_ doesn't let you use HTML and instead has a custom way of specifying column layouts.
### Column layout ## Column layout
The way to specify column layouts is by first creating a layout, and then telling _presenterm_ you want to enter each of The way to specify column layouts is by first creating a layout, and then telling _presenterm_ you want to enter each of
the column in it as you write your presentation. the column in it as you write your presentation.
#### Defining layouts ### Defining layouts
Defining a layout is done via the `column_layout` command, in the form of an HTML comment: Defining a layout is done via the `column_layout` command, in the form of an HTML comment:
@ -39,7 +39,7 @@ This defines a layout with 2 columns where:
You can use any number of columns and with as many units you want on each of them. This lets you decide how to structure You can use any number of columns and with as many units you want on each of them. This lets you decide how to structure
the presentation in a fairly straightforward way. the presentation in a fairly straightforward way.
#### Using columns ### Using columns
Once a layout is defined, you just need to specify that you want to enter a column before writing any text to it by Once a layout is defined, you just need to specify that you want to enter a column before writing any text to it by
using the `column` command: using the `column` command:
@ -54,7 +54,7 @@ Now all the markdown you write will be placed on the first column until you eith
* The slide ends. * The slide ends.
* You jump into another column by using the `column` command again. * You jump into another column by using the `column` command again.
### Example ## Example
The following example puts all of this together by defining 2 columns, one with some code and bullet points, another one The following example puts all of this together by defining 2 columns, one with some code and bullet points, another one
with an image, and some extra text at the bottom that's not tied to any columns. with an image, and some extra text at the bottom that's not tied to any columns.
@ -95,7 +95,7 @@ This would render the following way:
![](../assets/layouts.png) ![](../assets/layouts.png)
### Other uses ## Other uses
Besides organizing your slides into columns, you can use column layouts to center a piece of your slide. For example, if Besides organizing your slides into columns, you can use column layouts to center a piece of your slide. For example, if
you want a certain portion of your slide to be centered, you could define a column layout like `[1, 3, 1]` and then only you want a certain portion of your slide to be centered, you could define a column layout like `[1, 3, 1]` and then only

7
docs/src/guides/mermaid.md
View File

@ -1,4 +1,4 @@
# Mermaid ## Mermaid
[mermaid](https://mermaid.js.org/) snippets can be converted into images automatically in any code snippet tagged with [mermaid](https://mermaid.js.org/) snippets can be converted into images automatically in any code snippet tagged with
the `mermaid` language and a `+render` tag: the `mermaid` language and a `+render` tag:
@ -42,3 +42,8 @@ The theme of the rendered mermaid diagrams can be changed through the following
* `mermaid.background` the background color passed to the CLI (e.g., `transparent`, `red`, `#F0F0F0`). * `mermaid.background` the background color passed to the CLI (e.g., `transparent`, `red`, `#F0F0F0`).
* `mermaid.theme` the [mermaid theme](https://mermaid.js.org/config/theming.html#available-themes) to use. * `mermaid.theme` the [mermaid theme](https://mermaid.js.org/config/theming.html#available-themes) to use.
## Always rendering
If you don't want to use `+render` every time, you can configure which languages get this automatically via the [config
file](configuration.html#auto_render_languages).

29
docs/src/guides/pdf-export.md
View File

@ -1,38 +1,43 @@
## PDF export # PDF export
Presentations can be converted into PDF by using a [helper tool](https://github.com/mfontanini/presenterm-export). You Presentations can be converted into PDF by using a [helper tool](https://github.com/mfontanini/presenterm-export). You
can install it by running: can install it by running:
```shell ```bash
pip install presenterm-export pip install presenterm-export
``` ```
> **Note**: make sure that `presenterm-export` works by running `presenterm-export --version` before attempting to > [!tip]
> generate a PDF file. If you get errors related to _weasyprint_, follow their [installation > Make sure that `presenterm-export` works by running `presenterm-export --version` before attempting to generate a PDF
> instructions](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html) to ensure you meet all of their > file. If you get errors related to _weasyprint_, follow their [installation instructions](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html) to ensure you meet all of their
> dependencies. This has otherwise caused issues in macOS. > dependencies. This has otherwise caused issues in macOS.
The only external dependency you'll need is [tmux](https://github.com/tmux/tmux/). After you've installed both of these, The only external dependency you'll need is [tmux](https://github.com/tmux/tmux/). After you've installed both of these,
simply run _presenterm_ with the `--export-pdf` parameter to generate the output PDF: simply run _presenterm_ with the `--export-pdf` parameter to generate the output PDF:
```shell ```bash
presenterm --export-pdf examples/demo.md presenterm --export-pdf examples/demo.md
``` ```
The output PDF will be placed in `examples/demo.pdf`. **The size of each page will depend on the size of your terminal** The output PDF will be placed in `examples/demo.pdf`.
so make sure to adjust accordingly before running the command above.
> Note: if you're using a separate virtual env to install _presenterm-export_ just make sure you activate it before > [!note]
> running _presenterm_ with the `--export-pdf` parameter. > If you're using a separate virtual env to install _presenterm-export_ just make sure you activate it before running
> _presenterm_ with the `--export-pdf` parameter.
### Active tmux sessions bug ## Page sizes
The size of each page in the generated PDF will depend on the size of your terminal. Make sure to adjust accordingly
before running the command above, and not to resize it while the generation is happening to avoid issues.
## Active tmux sessions bug
Because of a [bug in tmux <= 3.5a](https://github.com/tmux/tmux/issues/4268), exporting a PDF while having other tmux Because of a [bug in tmux <= 3.5a](https://github.com/tmux/tmux/issues/4268), exporting a PDF while having other tmux
sessions running and attached will cause the size of the output PDF to match the size of those other sessions rather sessions running and attached will cause the size of the output PDF to match the size of those other sessions rather
than the size of the terminal you're running _presenterm_ in. The workaround is to only have one attached tmux session than the size of the terminal you're running _presenterm_ in. The workaround is to only have one attached tmux session
and to run the PDF export from that session. and to run the PDF export from that session.
### How it works ## How it works
The conversion into PDF format is pretty convoluted. If you'd like to learn more visit The conversion into PDF format is pretty convoluted. If you'd like to learn more visit
[presenterm-export](https://github.com/mfontanini/presenterm-export)'s repo. [presenterm-export](https://github.com/mfontanini/presenterm-export)'s repo.

57
docs/src/guides/speaker-notes.md Normal file
View File

@ -0,0 +1,57 @@
## Speaker notes
Starting on version 0.10.0, _presenterm_ allows presentations to define speaker notes. The way this works is:
* You start an instance of _presenterm_ using the `--publish-speaker-notes` parameter. This will be the main instance in
which you will present like you usually do.
* Another instance should be started using the `--listen-speaker-notes` parameter. This instance will only display
speaker notes in the presentation and will automatically change slides whenever the main instance does so.
For example:
```bash
# Start the main instance
presenterm demo.md --publish-speaker-notes
# In another shell: start the speaker notes instance
presenterm demo.md --listen-speaker-notes
```
### Defining speaker notes
In order to define speaker notes you can use the `speaker_notes` comment command:
```markdown
Normal text
<!-- speaker_note: this is a speaker note -->
More text
```
When running this two instance setup, the main one will show "normal text" and "more text", whereas the second one will
only show "this is a speaker note" on that slide.
### Multiline speaker notes
You can use multiline speaker notes by using the appropriate YAML syntax:
```yaml
<!--
speaker_note: |
something
something else
-->
```
### Multiple instances
On Linux and Windows, you can run multiple instances in publish mode and multiple instances in listen mode at the same
time. Each instance will only listen to events for the presentation it was started on.
On Mac this is not supported and only a single listener can be used at a time.
### Internals
This uses UDP sockets on localhost to communicate between instances. The main instance sends events every time a slide
is shown and the listener instances listen to them and displays the speaker notes for that specific slide.

123
docs/src/guides/themes.md
View File

@ -1,21 +1,21 @@
## Themes # Themes
Themes are defined in the form of yaml files. A few built-in themes are defined in the [themes][builtin-themes] Themes are defined in the form of yaml files. A few built-in themes are defined in the [themes][builtin-themes]
directory, but others can be created and referenced directly in every presentation. directory, but others can be created and referenced directly in every presentation.
### Setting themes ## Setting themes
There's various ways of setting the theme you want in your presentation: There's various ways of setting the theme you want in your presentation:
#### CLI ### CLI
Passing in the `--theme` parameter when running _presenterm_ to select one of the built-in themes. Passing in the `--theme` parameter when running _presenterm_ to select one of the built-in themes.
#### Within the presentation ### Within the presentation
The presentation's markdown file can contain a front matter that specifies the theme to use. This comes in 3 flavors: The presentation's markdown file can contain a front matter that specifies the theme to use. This comes in 3 flavors:
##### By name #### By name
Using a built-in theme name makes your presentation use that one regardless of what the default or what the `--theme` Using a built-in theme name makes your presentation use that one regardless of what the default or what the `--theme`
option specifies: option specifies:
@ -27,7 +27,7 @@ theme:
--- ---
``` ```
##### By path #### By path
You can define a theme file in yaml format somewhere in your filesystem and reference it within the presentation: You can define a theme file in yaml format somewhere in your filesystem and reference it within the presentation:
@ -38,7 +38,7 @@ theme:
--- ---
``` ```
##### Overrides #### Overrides
You can partially/completely override the theme in use from within the presentation: You can partially/completely override the theme in use from within the presentation:
@ -58,7 +58,7 @@ This lets you:
copying somewhere, and changing it when you only expect to use it for that one presentation. copying somewhere, and changing it when you only expect to use it for that one presentation.
2. Iterate quickly on styles given overrides are reloaded whenever you save your presentation file. 2. Iterate quickly on styles given overrides are reloaded whenever you save your presentation file.
## Built-in themes # Built-in themes
A few built-in themes are bundled with the application binary, meaning you don't need to have any external files A few built-in themes are bundled with the application binary, meaning you don't need to have any external files
available to use them. These are packed as part of the [build process][build-rs] as a binary blob and are decoded on available to use them. These are packed as part of the [build process][build-rs] as a binary blob and are decoded on
@ -78,11 +78,11 @@ Currently, the following themes are supported:
means if your terminal background is e.g. transparent, or uses an image, the presentation will inherit that. means if your terminal background is e.g. transparent, or uses an image, the presentation will inherit that.
* `terminal-light`: The same as `terminal-dark` but works best if your terminal uses a light color scheme. * `terminal-light`: The same as `terminal-dark` but works best if your terminal uses a light color scheme.
### Trying out built-in themes ## Trying out built-in themes
All built-in themes can be tested by using the `--list-themes` parameter: All built-in themes can be tested by using the `--list-themes` parameter:
```shell ```bash
presenterm --list-themes presenterm --list-themes
``` ```
@ -90,19 +90,19 @@ This will run a presentation where the same content is rendered using a differen
[![asciicast](https://asciinema.org/a/zeV1QloyrLkfBp6rNltvX7Lle.svg)](https://asciinema.org/a/zeV1QloyrLkfBp6rNltvX7Lle) [![asciicast](https://asciinema.org/a/zeV1QloyrLkfBp6rNltvX7Lle.svg)](https://asciinema.org/a/zeV1QloyrLkfBp6rNltvX7Lle)
## Loading custom themes # Loading custom themes
On startup, _presenterm_ will look into the `themes` directory under the [configuration directory](configuration.html) On startup, _presenterm_ will look into the `themes` directory under the [configuration directory](configuration.html)
(e.g. `~/.config/presenterm/themes` in Linux) and will load any `.yaml` file as a theme and make it available as if it (e.g. `~/.config/presenterm/themes` in Linux) and will load any `.yaml` file as a theme and make it available as if it
was a built-in theme. This means you can use it as an argument to the `--theme` parameter, use it in the `theme.name` was a built-in theme. This means you can use it as an argument to the `--theme` parameter, use it in the `theme.name`
property in a presentation's front matter, etc. property in a presentation's front matter, etc.
## Theme definition # Theme definition
This section goes through the structure of the theme files. Have a look at some of the [existing themes][builtin-themes] This section goes through the structure of the theme files. Have a look at some of the [existing themes][builtin-themes]
to have an idea of how to structure themes. to have an idea of how to structure themes.
### Root elements ## Root elements
The root attributes on the theme yaml files specify either: The root attributes on the theme yaml files specify either:
@ -110,7 +110,7 @@ The root attributes on the theme yaml files specify either:
etc. etc.
* A default to be applied as a fallback if no specific style is specified for a particular element. * A default to be applied as a fallback if no specific style is specified for a particular element.
### Alignment ## Alignment
_presenterm_ uses the notion of alignment, just like you would have in a GUI editor, to align text to the left, center, _presenterm_ uses the notion of alignment, just like you would have in a GUI editor, to align text to the left, center,
or right. You probably want most elements to be aligned left, _some_ to be aligned on the center, and probably none to or right. You probably want most elements to be aligned left, _some_ to be aligned on the center, and probably none to
@ -122,14 +122,14 @@ The following elements support alignment:
* The title, subtitle, and author elements in the intro slide. * The title, subtitle, and author elements in the intro slide.
* Tables. * Tables.
#### Left/right alignment ### Left/right alignment
Left and right alignments take a margin property which specifies the number of columns to keep between the text and the Left and right alignments take a margin property which specifies the number of columns to keep between the text and the
left/right terminal screen borders. left/right terminal screen borders.
The margin can be specified in two ways: The margin can be specified in two ways:
##### Fixed #### Fixed
A specific number of characters regardless of the terminal size. A specific number of characters regardless of the terminal size.
@ -139,7 +139,7 @@ margin:
fixed: 5 fixed: 5
``` ```
##### Percent #### Percent
A percentage over the total number of columns in the terminal. A percentage over the total number of columns in the terminal.
@ -152,7 +152,7 @@ margin:
Percent alignment tends to look a bit nicer as it won't change the presentation's look as much when the terminal size Percent alignment tends to look a bit nicer as it won't change the presentation's look as much when the terminal size
changes. changes.
#### Center alignment ### Center alignment
Center alignment has 2 properties: Center alignment has 2 properties:
* `minimum_size` which specifies the minimum size you want that element to have. This is normally useful for code blocks * `minimum_size` which specifies the minimum size you want that element to have. This is normally useful for code blocks
@ -161,7 +161,7 @@ Center alignment has 2 properties:
alignment. This doesn't play very well with `minimum_size` but in isolation it specifies the minimum number of columns alignment. This doesn't play very well with `minimum_size` but in isolation it specifies the minimum number of columns
you want to the left and right of your text. you want to the left and right of your text.
### Colors ## Colors
Every element can have its own background/foreground color using hex notation: Every element can have its own background/foreground color using hex notation:
@ -172,7 +172,7 @@ default:
background: "00ff00" background: "00ff00"
``` ```
### Default style ## Default style
The default style specifies: The default style specifies:
@ -188,7 +188,7 @@ default:
background: "040312" background: "040312"
``` ```
### Intro slide ## Intro slide
The introductory slide will be rendered if you specify a title, subtitle, or author in the presentation's front matter. The introductory slide will be rendered if you specify a title, subtitle, or author in the presentation's front matter.
This lets you have a less markdown-looking introductory slide that stands out so that it doesn't end up looking too This lets you have a less markdown-looking introductory slide that stands out so that it doesn't end up looking too
@ -221,11 +221,11 @@ intro_slide:
positioning: below_title positioning: below_title
``` ```
### Footer ## Footer
The footer currently comes in 3 flavors: The footer currently comes in 3 flavors:
#### None ### None
No footer at all! No footer at all!
@ -234,7 +234,7 @@ footer:
style: empty style: empty
``` ```
#### Progress bar ### Progress bar
A progress bar that will advance as you move in your presentation. This will by default use a block-looking character to A progress bar that will advance as you move in your presentation. This will by default use a block-looking character to
draw the progress bar but you can customize it: draw the progress bar but you can customize it:
@ -247,7 +247,7 @@ footer:
character: 🚀 character: 🚀
``` ```
#### Template ### Template
A template footer that lets you put something on the left, center and/or right of the screen. The template strings A template footer that lets you put something on the left, center and/or right of the screen. The template strings
can reference `{current_slide}` and `{total_slides}` which will be replaced with the current and total number of slides. can reference `{current_slide}` and `{total_slides}` which will be replaced with the current and total number of slides.
@ -269,7 +269,7 @@ footer:
right: "{current_slide} / {total_slides}" right: "{current_slide} / {total_slides}"
``` ```
### Slide title ## Slide title
Slide titles, as specified by using a setext header, has the following properties: Slide titles, as specified by using a setext header, has the following properties:
* `padding_top` which specifies the number of rows you want as padding before the text. * `padding_top` which specifies the number of rows you want as padding before the text.
@ -283,7 +283,7 @@ slide_title:
separator: true separator: true
``` ```
### Headings ## Headings
Every header type (h1 through h6) can have its own style composed of: Every header type (h1 through h6) can have its own style composed of:
* The prefix you want to use. * The prefix you want to use.
@ -301,7 +301,7 @@ headings:
foreground: "rgb_(168,223,142)" foreground: "rgb_(168,223,142)"
``` ```
### Code blocks ## Code blocks
The syntax highlighting for code blocks is done via the [syntect](https://github.com/trishume/syntect) crate. The list The syntax highlighting for code blocks is done via the [syntect](https://github.com/trishume/syntect) crate. The list
of all the supported built-in _syntect_ themes is the following: of all the supported built-in _syntect_ themes is the following:
@ -335,7 +335,7 @@ Besides the built-in highlighting themes, you can drop any `.tmTheme` theme in t
your [configuration directory](configuration.html) (e.g. `~/.config/presenterm/themes/highlighting` in Linux) and they your [configuration directory](configuration.html) (e.g. `~/.config/presenterm/themes/highlighting` in Linux) and they
will be loaded automatically when _presenterm_ starts. will be loaded automatically when _presenterm_ starts.
### Block quotes ## Block quotes
For block quotes you can specify a string to use as a prefix in every line of quoted text: For block quotes you can specify a string to use as a prefix in every line of quoted text:
@ -348,7 +348,7 @@ block_quote:
[builtin-themes]: https://github.com/mfontanini/presenterm/tree/master/themes [builtin-themes]: https://github.com/mfontanini/presenterm/tree/master/themes
[build-rs]: https://github.com/mfontanini/presenterm/blob/master/build.rs [build-rs]: https://github.com/mfontanini/presenterm/blob/master/build.rs
### Mermaid ## Mermaid
The [mermaid](https://mermaid.js.org/) graphs can be customized using the following parameters: The [mermaid](https://mermaid.js.org/) graphs can be customized using the following parameters:
@ -361,7 +361,45 @@ mermaid:
theme: dark theme: dark
``` ```
### Extending themes ## Alerts
GitHub style markdown alerts can be styled by setting the `alert` key:
```yaml
alert:
# the base colors used in all text in an alert
base_colors:
foreground: red
background: black
# the prefix used in every line in the alert
prefix: "▍ "
# the style for each alert type
styles:
note:
color: blue
title: Note
icon: I
tip:
color: green
title: Tip
icon: T
important:
color: cyan
title: Important
icon: I
warning:
color: orange
title: Warning
icon: W
caution:
color: red
title: Caution
icon: C
```
## Extending themes
Custom themes can extend other custom or built in themes. This means it will inherit all the properties of the theme Custom themes can extend other custom or built in themes. This means it will inherit all the properties of the theme
being extended by default. being extended by default.
@ -377,3 +415,26 @@ default:
This theme extends the built in _dark_ theme and overrides the background color. This is useful if you find yourself This theme extends the built in _dark_ theme and overrides the background color. This is useful if you find yourself
_almost_ liking a built in theme but there's only some properties you don't like. _almost_ liking a built in theme but there's only some properties you don't like.
## Color palette
Every theme can define a color palette, which is essentially a named list of colors. These can then be used both in
other parts of the theme, as well as when styling text via `span` HTML tags.
A palette can de defined as follows:
```yaml
palette:
colors:
red: "f78ca2"
purple: "986ee2"
```
Any palette color can be referenced using either `palette:<name>` or `p:<name>`. This means now any part of the theme
can use `p:red` and `p:purple` where a color is required.
Similarly, these colors can be used in `span` tags like:
```html
<span style="color: palette:red">this is red</span>
```

4
docs/src/introduction.md
View File

@ -1,10 +1,10 @@
## presenterm # presenterm
[presenterm][github] lets you create presentations in markdown format and run them from your terminal, with support for [presenterm][github] lets you create presentations in markdown format and run them from your terminal, with support for
image and animated gif support, highly customizable themes, code highlighting, exporting presentations into PDF format, image and animated gif support, highly customizable themes, code highlighting, exporting presentations into PDF format,
and plenty of other features. and plenty of other features.
### Demo ## Demo
This is how the [demo presentation][demo-source] looks like: This is how the [demo presentation][demo-source] looks like: