From fd45d96e1c829cce79e5e4c9747c10ea0f7cc70c Mon Sep 17 00:00:00 2001 From: Matias Fontanini Date: Sat, 1 Feb 2025 14:30:44 -0800 Subject: [PATCH] docs: add docs on 0.10.0 features --- docs/src/SUMMARY.md | 1 + docs/src/guides/basics.md | 95 ++++++++++++++--------- docs/src/guides/code-highlight.md | 50 ++++++++---- docs/src/guides/configuration.md | 47 ++++++++++-- docs/src/guides/installation.md | 32 ++++---- docs/src/guides/latex.md | 18 ++--- docs/src/guides/layout.md | 14 ++-- docs/src/guides/mermaid.md | 7 +- docs/src/guides/pdf-export.md | 29 ++++--- docs/src/guides/speaker-notes.md | 57 ++++++++++++++ docs/src/guides/themes.md | 123 ++++++++++++++++++++++-------- docs/src/introduction.md | 4 +- 12 files changed, 341 insertions(+), 136 deletions(-) create mode 100644 docs/src/guides/speaker-notes.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 40ae8b1..b0d3ce6 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -11,6 +11,7 @@ - [Configuration](./guides/configuration.md) - [Code highlighting](./guides/code-highlight.md) - [PDF export](./guides/pdf-export.md) +- [Speaker notes](./guides/speaker-notes.md) - [Mermaid](./guides/mermaid.md) - [LaTeX and typst](./guides/latex.md) diff --git a/docs/src/guides/basics.md b/docs/src/guides/basics.md index b633b1e..3839076 100644 --- a/docs/src/guides/basics.md +++ b/docs/src/guides/basics.md @@ -1,19 +1,19 @@ -## Introduction +# Introduction 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. -### Quick start +## Quick start Download the demo presentation and run it using: -```shell +```bash git clone https://github.com/mfontanini/presenterm.git cd presenterm 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 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 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:` or `p:colored text! +``` + +> [!note] +> Keep in mind **only `span` tags are supported**. + +## Images ![](../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 the terminals where at least one of these is supported are: -* kitty -* iterm2 -* wezterm -* foot +* [kitty](https://sw.kovidgoyal.net/kitty/) +* [iterm2](https://iterm2.com/) +* [WezTerm](https://wezfurlong.org/wezterm/index.html) +* [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 ``` -> **Note**: this feature flag is only needed if your terminal emulator only supports sixel. Many terminals support the -> kitty or iterm2 protocols so this isn't necessary. +> [!note] +> 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 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 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 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 -running inside `tmux`), you can set it manually via the `--image-protocol` parameter or by setting it in the [config +By default the image protocol to be used will be automatically detected. In cases where this detection fails, you can +set it manually via the `--image-protocol` parameter or by setting it in the [config file](configuration.html#preferred-image-protocol). -## Extensions +# 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 your presentation and implicitly create an introduction slide: -```markdown +```yaml --- title: My first presentation 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. -#### 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` and list them all this way: -```markdown +```yaml --- title: Our first presentation 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 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. -~~~ +~~~markdown 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. -### Pauses +## Pauses 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 @@ -135,7 +154,7 @@ command: ``` -### Ending slides +## Ending slides While other applications use a thematic break (`---`) to mark the end of a slide, _presenterm_ uses a special `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 [`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 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. -### Explicit new lines +## Explicit new lines 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: @@ -187,7 +206,7 @@ mom bye ``` -### Incremental lists +## Incremental lists Using `` 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 @@ -207,7 +226,7 @@ bullet point to appear only after you move to the next slide: * 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 keys, _hjkl_, and page up/down keys. @@ -219,18 +238,20 @@ Besides this: * Jumping to a specific slide: `G`. * Exit the presentation: `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 file](configuration.html#key-bindings). -## Modals +# Modals _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 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 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) -### 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 presentation file every time you save it. _presenterm_ will also automatically detect which specific slide was modified diff --git a/docs/src/guides/code-highlight.md b/docs/src/guides/code-highlight.md index 081b082..c2fdd0b 100644 --- a/docs/src/guides/code-highlight.md +++ b/docs/src/guides/code-highlight.md @@ -1,4 +1,4 @@ -## Code highlighting +# Code highlighting Code highlighting is supported for the following languages: @@ -47,6 +47,7 @@ Code highlighting is supported for the following languages: * sql * swift * svelte +* tcl * toml * terraform * typescript @@ -55,7 +56,7 @@ Code highlighting is supported for the following languages: * vue * 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 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 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 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) -### 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. @@ -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 `+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 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 * fish * go +* haskell * java * js * kotlin @@ -167,12 +169,14 @@ The list of languages that support execution are: * perl * php * python +* r * ruby * rust * 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. * sh * zsh +* c# 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 @@ -181,9 +185,11 @@ file](configuration.html#custom-snippet-executors). [![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: @@ -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 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, 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) -### 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 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. -### 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 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 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 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. -### 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 languages supported by _bat_ natively can be added to _presenterm_ easily. Please create a ticket or use diff --git a/docs/src/guides/configuration.md b/docs/src/guides/configuration.md index 73bf798..1f38a5f 100644 --- a/docs/src/guides/configuration.md +++ b/docs/src/guides/configuration.md @@ -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 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 `` 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: -``` +```markdown --- options: 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 `![width:50%](path.png)` you would need to set: -``` +```yaml --- options: image_attributes_prefix: "" @@ -166,6 +166,20 @@ options: ![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 **can only be configured via the configuration file**. @@ -197,9 +211,9 @@ defaults: ### Preferred image protocol -By default _presenterm_ will try to detect which image protocol to use based on the terminal you are using. In some -cases this may fail, for example when using `tmux`. In those cases, you can explicitly set this via the -`--image-protocol` parameter or the configuration key `defaults.image_protocol`: +By default _presenterm_ will try to detect which image protocol to use based on the terminal you are using. In case +detection for some reason fails in your setup or you'd like to force a different protocol to be used, you can explicitly +set this via the `--image-protocol` parameter or the configuration key `defaults.image_protocol`: ```yaml defaults: @@ -215,6 +229,17 @@ Possible values are: * `iterm2`: use the iterm2 protocol. * `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 that _presenterm_ uses can be manually configured in the config file via the `bindings` key. The following @@ -356,3 +381,13 @@ mermaid: 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 +``` + diff --git a/docs/src/guides/installation.md b/docs/src/guides/installation.md index 61866e0..0026e33 100644 --- a/docs/src/guides/installation.md +++ b/docs/src/guides/installation.md @@ -1,41 +1,41 @@ -## Installation +# Installation _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 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: -```shell +```bash cargo install --locked presenterm ``` -### Latest unreleased version +## Latest unreleased version To install from the latest source code run: -```shell +```bash 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: -```shell +```bash brew install presenterm ``` -### Nix +## Nix To install _presenterm_ using the Nix package manager run: -```shell +```bash nix-env -iA nixos.presenterm # for 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 -[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: -```shell +```bash pacman -S presenterm ``` @@ -70,17 +70,17 @@ pacman -S presenterm Alternatively, you can use any AUR helper to install the upstream binaries: -```shell +```bash paru/yay -S presenterm-bin ``` #### Building from git -```shell +```bash 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: diff --git a/docs/src/guides/latex.md b/docs/src/guides/latex.md index 93e2389..50eb02b 100644 --- a/docs/src/guides/latex.md +++ b/docs/src/guides/latex.md @@ -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 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. -### Dependencies +## Dependencies -#### typst +### typst 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_. -#### pandoc +### pandoc 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_. @@ -20,7 +20,7 @@ This lets us: * 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_. -### Controlling PPI +## Controlling PPI _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 @@ -37,7 +37,7 @@ typst: 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: @@ -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 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 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: @@ -73,7 +73,7 @@ typst: vertical_margin: 2 ``` -## Example +# Example The following example: diff --git a/docs/src/guides/layout.md b/docs/src/guides/layout.md index 024bdf2..f570f48 100644 --- a/docs/src/guides/layout.md +++ b/docs/src/guides/layout.md @@ -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 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 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 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. -### 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 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: @@ -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 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 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. * 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 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) -### 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 you want a certain portion of your slide to be centered, you could define a column layout like `[1, 3, 1]` and then only diff --git a/docs/src/guides/mermaid.md b/docs/src/guides/mermaid.md index cd63b22..eef59b1 100644 --- a/docs/src/guides/mermaid.md +++ b/docs/src/guides/mermaid.md @@ -1,4 +1,4 @@ -# Mermaid +## Mermaid [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: @@ -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.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). diff --git a/docs/src/guides/pdf-export.md b/docs/src/guides/pdf-export.md index f2709e7..6da2570 100644 --- a/docs/src/guides/pdf-export.md +++ b/docs/src/guides/pdf-export.md @@ -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 can install it by running: -```shell +```bash pip install presenterm-export ``` -> **Note**: make sure that `presenterm-export` works by running `presenterm-export --version` before attempting to -> generate a PDF 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 +> [!tip] +> Make sure that `presenterm-export` works by running `presenterm-export --version` before attempting to generate a PDF +> 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. 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: -```shell +```bash 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** -so make sure to adjust accordingly before running the command above. +The output PDF will be placed in `examples/demo.pdf`. -> Note: 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. +> [!note] +> 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 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 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 [presenterm-export](https://github.com/mfontanini/presenterm-export)'s repo. diff --git a/docs/src/guides/speaker-notes.md b/docs/src/guides/speaker-notes.md new file mode 100644 index 0000000..f57b872 --- /dev/null +++ b/docs/src/guides/speaker-notes.md @@ -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 + + + +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 + +``` + +### 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. diff --git a/docs/src/guides/themes.md b/docs/src/guides/themes.md index 8b7ee05..ba43694 100644 --- a/docs/src/guides/themes.md +++ b/docs/src/guides/themes.md @@ -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] 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: -#### CLI +### CLI 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: -##### 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` 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: @@ -38,7 +38,7 @@ theme: --- ``` -##### Overrides +#### Overrides 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. 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 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. * `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: -```shell +```bash 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) -## Loading custom themes +# Loading custom themes 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 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. -## 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] to have an idea of how to structure themes. -### Root elements +## Root elements 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. * 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, 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. * 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/right terminal screen borders. The margin can be specified in two ways: -##### Fixed +#### Fixed A specific number of characters regardless of the terminal size. @@ -139,7 +139,7 @@ margin: fixed: 5 ``` -##### Percent +#### Percent 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 changes. -#### Center alignment +### Center alignment 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 @@ -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 you want to the left and right of your text. -### Colors +## Colors Every element can have its own background/foreground color using hex notation: @@ -172,7 +172,7 @@ default: background: "00ff00" ``` -### Default style +## Default style The default style specifies: @@ -188,7 +188,7 @@ default: 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. 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 ``` -### Footer +## Footer The footer currently comes in 3 flavors: -#### None +### None No footer at all! @@ -234,7 +234,7 @@ footer: 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 draw the progress bar but you can customize it: @@ -247,7 +247,7 @@ footer: character: 🚀 ``` -#### Template +### Template 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. @@ -269,7 +269,7 @@ footer: right: "{current_slide} / {total_slides}" ``` -### Slide title +## Slide title 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. @@ -283,7 +283,7 @@ slide_title: separator: true ``` -### Headings +## Headings Every header type (h1 through h6) can have its own style composed of: * The prefix you want to use. @@ -301,7 +301,7 @@ headings: 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 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 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: @@ -348,7 +348,7 @@ block_quote: [builtin-themes]: https://github.com/mfontanini/presenterm/tree/master/themes [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: @@ -361,7 +361,45 @@ mermaid: 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 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 _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:` or `p:`. 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 +this is red +``` diff --git a/docs/src/introduction.md b/docs/src/introduction.md index 12ca24b..040f91c 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -1,10 +1,10 @@ -## presenterm +# presenterm [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, and plenty of other features. -### Demo +## Demo This is how the [demo presentation][demo-source] looks like: