mirror of
https://github.com/mfontanini/presenterm.git
synced 2026-09-01 23:33:21 -06:00
chore: add docs for 0.11.0
This commit is contained in:
Matias Fontanini
parent
d5b172048a
commit
3b40c8fd3d
Binary file not shown.
|
Before Width: | Height: | Size: 477 KiB After Width: | Height: | Size: 655 KiB |
@ -58,6 +58,16 @@ defaults:
|
||||
max_columns: 100
|
||||
```
|
||||
|
||||
If you would like your presentation to be left or right aligned instead of centered when the terminal is too wide, you
|
||||
can use the `max_columns_alignment` key:
|
||||
|
||||
|
||||
```yaml
|
||||
defaults:
|
||||
max_columns: 100
|
||||
max_columns_alignment: left
|
||||
```
|
||||
|
||||
# Key bindings
|
||||
|
||||
Key bindings that _presenterm_ uses can be manually configured in the config file via the `bindings` key. The following
|
||||
|
||||
@ -19,38 +19,11 @@ Code execution **must be explicitly enabled** by using either:
|
||||
* Setting the `snippet.exec.enable` property to `true` in your [_presenterm_ config
|
||||
file](../../configuration/settings.md#snippet-execution).
|
||||
|
||||
Refer to [the table in the highlighting page](highlighting.md#code-highlighting) for the list of languages for which
|
||||
code execution is supported.
|
||||
|
||||
---
|
||||
|
||||
The list of languages that support execution are:
|
||||
|
||||
* bash
|
||||
* c++
|
||||
* c
|
||||
* fish
|
||||
* go
|
||||
* haskell
|
||||
* java
|
||||
* js
|
||||
* kotlin
|
||||
* lua
|
||||
* nushell
|
||||
* 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
|
||||
snippets for that language. You can also configure how to run code snippet for a language locally in your [config
|
||||
file](../../configuration/settings.md#custom-snippet-executors).
|
||||
|
||||
[](https://asciinema.org/a/BbAY817esxagCgPtnKUwgYnHr)
|
||||
|
||||
> [!warning]
|
||||
|
||||
@ -2,59 +2,74 @@
|
||||
|
||||
Code highlighting is supported for the following languages:
|
||||
|
||||
* ada
|
||||
* asp
|
||||
* awk
|
||||
* bash
|
||||
* batchfile
|
||||
* C
|
||||
* cmake
|
||||
* crontab
|
||||
* C#
|
||||
* clojure
|
||||
* C++
|
||||
* CSS
|
||||
* D
|
||||
* diff
|
||||
* docker
|
||||
* dotenv
|
||||
* elixir
|
||||
* elm
|
||||
* erlang
|
||||
* go
|
||||
* haskell
|
||||
* HTML
|
||||
* java
|
||||
* javascript
|
||||
* json
|
||||
* kotlin
|
||||
* latex
|
||||
* lua
|
||||
* makefile
|
||||
* markdown
|
||||
* nix
|
||||
* ocaml
|
||||
* perl
|
||||
* php
|
||||
* protobuf
|
||||
* puppet
|
||||
* python
|
||||
* R
|
||||
* ruby
|
||||
* rust
|
||||
* scala
|
||||
* shell
|
||||
* sql
|
||||
* swift
|
||||
* svelte
|
||||
* tcl
|
||||
* toml
|
||||
* terraform
|
||||
* typescript
|
||||
* xml
|
||||
* yaml
|
||||
* vue
|
||||
* zig
|
||||
| Language | Execution support |
|
||||
| -----------|-------------------|
|
||||
| ada | |
|
||||
| asp | |
|
||||
| awk | |
|
||||
| bash | ✓ |
|
||||
| batchfile | |
|
||||
| C | ✓ |
|
||||
| cmake | |
|
||||
| crontab | |
|
||||
| C# | ✓ |
|
||||
| clojure | |
|
||||
| C++ | ✓ |
|
||||
| CSS | |
|
||||
| D | |
|
||||
| diff | |
|
||||
| docker | |
|
||||
| dotenv | |
|
||||
| elixir | |
|
||||
| elm | |
|
||||
| erlang | |
|
||||
| fish | ✓ |
|
||||
| go | ✓ |
|
||||
| haskell | ✓ |
|
||||
| HTML | |
|
||||
| java | ✓ |
|
||||
| javascript | ✓ |
|
||||
| json | |
|
||||
| kotlin | ✓ |
|
||||
| latex | |
|
||||
| lua | ✓ |
|
||||
| makefile | |
|
||||
| markdown | |
|
||||
| nix | |
|
||||
| ocaml | |
|
||||
| perl | ✓ |
|
||||
| php | ✓ |
|
||||
| protobuf | |
|
||||
| puppet | |
|
||||
| python | ✓ |
|
||||
| R | ✓ |
|
||||
| ruby | ✓ |
|
||||
| rust | ✓ |
|
||||
| scala | |
|
||||
| shell | ✓ |
|
||||
| sql | |
|
||||
| swift | |
|
||||
| svelte | |
|
||||
| tcl | |
|
||||
| toml | |
|
||||
| terraform | |
|
||||
| typescript | |
|
||||
| xml | |
|
||||
| yaml | |
|
||||
| vue | |
|
||||
| zig | |
|
||||
| zsh | ✓ |
|
||||
|
||||
Other languages that are supported are:
|
||||
|
||||
* nushell, for which highlighting isn't supported but execution is.
|
||||
* rust-script, which is highlighted as rust but is executed via the [rust-script](https://rust-script.org/) tool,
|
||||
which lets you specify dependencies in your snippet.
|
||||
|
||||
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). If you'd also like code execution support, provide details
|
||||
on how to compile (if necessary) and run snippets for that language. You can also configure how to run code snippet for
|
||||
a language locally in your [config file](../../configuration/settings.md#custom-snippet-executors).
|
||||
|
||||
## Enabling line numbers
|
||||
|
||||
|
||||
@ -13,6 +13,22 @@ command:
|
||||
<!-- pause -->
|
||||
```
|
||||
|
||||
## Font size
|
||||
|
||||
The font size can be changed by using the `font_size` command:
|
||||
|
||||
```html
|
||||
<!-- font_size: 2 -->
|
||||
```
|
||||
|
||||
This causes the remainder of the slide to use the font size specified. The font size can range from 1 to 7, 1 being the
|
||||
default.
|
||||
|
||||
> ![note]
|
||||
> This is currently only supported in the [_kitty_](https://sw.kovidgoyal.net/kitty/) terminal and only as of version
|
||||
> 0.40.0. See the notes on font sizes on the [introduction page](introduction.md#font-sizes) for more information on
|
||||
> this.
|
||||
|
||||
## 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
|
||||
@ -70,3 +86,11 @@ bullet point to appear only after you move to the next slide:
|
||||
* all at once
|
||||
```
|
||||
|
||||
## No footer
|
||||
|
||||
If you don't want the footer to show up in some particular slide for some reason, you can use the `no_footer` command:
|
||||
|
||||
```html
|
||||
<!-- no_footer -->
|
||||
```
|
||||
|
||||
|
||||
@ -27,18 +27,19 @@ text (**bold**, _italics_, ~strikethrough~, `inline code`, etc), code blocks, bl
|
||||
|
||||
## 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:
|
||||
By setting a front matter at the beginning of your presentation you can configure the title, sub title, author and other
|
||||
metadata about your presentation. Doing so will cause _presenterm_ to create an introduction slide:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: My first presentation
|
||||
title: "My _first_ **presentation**"
|
||||
sub_title: (in presenterm!)
|
||||
author: Myself
|
||||
---
|
||||
```
|
||||
|
||||
All of these attributes are optional so you're not forced to set them all.
|
||||
All of these attributes are optional and should be avoided if an introduction slide is not needed. Note that the `title`
|
||||
key can contain arbitrary markdown so you can use bold, italics, `<span>` tags, etc.
|
||||
|
||||
### Multiple authors
|
||||
|
||||
@ -86,10 +87,15 @@ If you really would prefer to use thematic breaks (`---`) to delimit slides, you
|
||||
|
||||
## 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/definition.md#color-palette) by using the `palette:<name>` or `p:<name` syntaxes.
|
||||
`span` HTML tags can be used to provide foreground and/or background colors to text. There's currently two ways to
|
||||
specify colors:
|
||||
|
||||
* Via the `style` attribute, in which 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/definition.md#color-palette) by using the `palette:<name>` or `p:<name` syntaxes.
|
||||
* Via the `class` attribute, which must point to a class defined in the [theme
|
||||
palette](themes/definition.md#color-palette). Classes allow configuring foreground/background color combinations to be
|
||||
used across your presentation.
|
||||
|
||||
For example, the following will use `ff0000` as the foreground color and whatever the active theme's palette defines as
|
||||
`foo`:
|
||||
@ -98,9 +104,37 @@ For example, the following will use `ff0000` as the foreground color and whateve
|
||||
<span style="color: #ff0000; background-color: palette:foo">colored text!</span>
|
||||
```
|
||||
|
||||
Alternatively, can you can define a class that contains a foreground/background color combination in your theme's
|
||||
palette and use it:
|
||||
|
||||
```markdown
|
||||
<span class="my_class">colored text!</span>
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> Keep in mind **only `span` tags are supported**.
|
||||
|
||||
## Font sizes
|
||||
|
||||
The [_kitty_](https://sw.kovidgoyal.net/kitty/) terminal added in version 0.40.0 support for a new protocol that allows
|
||||
TUIs to specify the font size to be used when printing text. _presenterm_ is one of the first applications supports this
|
||||
protocol in various places:
|
||||
|
||||
* Themes can specify it in the presentation title in the introduction slide, in slide titles, and in headers by using
|
||||
the `font_size` property. All built in themes currently set font size to 2 (1 is the default) for these elements.
|
||||
* Explicitly by using the `font_size` comment command:
|
||||
|
||||
```markdown
|
||||
# Normal text
|
||||
|
||||
<!-- font_size: 2 -->
|
||||
|
||||
# Larger text
|
||||
```
|
||||
|
||||
Terminal support for this feature is verified when _presenterm_ starts and any attempt to change the font size, be it
|
||||
via the theme or via the comment command, will be ignored if it's not supported.
|
||||
|
||||
# Key bindings
|
||||
|
||||
Navigation within a presentation should be intuitive: jumping to the next/previous slide can be done by using the arrow
|
||||
|
||||
@ -126,16 +126,72 @@ intro_slide:
|
||||
|
||||
The footer currently comes in 3 flavors:
|
||||
|
||||
### None
|
||||
### Template footers
|
||||
|
||||
No footer at all!
|
||||
A template footer lets you put text 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.
|
||||
|
||||
Besides those special variables, any of the attributes defined in the front matter can also be used:
|
||||
|
||||
* `title`.
|
||||
* `sub_title`.
|
||||
* `event`.
|
||||
* `location`.
|
||||
* `date`.
|
||||
* `author`.
|
||||
|
||||
Strings used in template footers can contain arbitrary markdown, including `span` tags that let you use colored text. A
|
||||
`height` attribute allows specifying how tall, in terminal rows, the footer is. The text in the footer will always be
|
||||
placed at the center of the footer area. The default footer height is 2.
|
||||
|
||||
```yaml
|
||||
footer:
|
||||
style: empty
|
||||
style: template
|
||||
left: "My **name** is {author}"
|
||||
center: "_@myhandle_"
|
||||
right: "{current_slide} / {total_slides}"
|
||||
height: 3
|
||||
```
|
||||
|
||||
### Progress bar
|
||||
Do note that:
|
||||
|
||||
* Only existing attributes in the front matter can be referenced. That is, if you use `{date}` but the `date` isn't set,
|
||||
an error will be shown.
|
||||
* Similarly, referencing unsupported variables (e.g. `{potato}`) will cause an error to be displayed. If you'd like the
|
||||
`{}` characters to be used in contexts where you don't want to reference a variable, you will need to escape them by
|
||||
using another brace. e.g. `{{potato}} farms` will be displayed as `{potato} farms`.
|
||||
|
||||
#### Footer images
|
||||
|
||||
Besides text, images can also be used in the left and center positions. This can be done by specifying an `image` key
|
||||
under each of those attributes:
|
||||
|
||||
```yaml
|
||||
footer:
|
||||
style: template
|
||||
left:
|
||||
image: potato.png
|
||||
center:
|
||||
image: banana.png
|
||||
right: "{current_slide} / {total_slides}"
|
||||
# The height of the footer to adjust image sizes
|
||||
height: 5
|
||||
```
|
||||
|
||||
Images will be looked up:
|
||||
|
||||
* First, relative to the presentation file just like any other image.
|
||||
* If the image is not found, it will be looked up relative to the themes directory. e.g. `~/.config/presenterm/themes`.
|
||||
This allows you to define a custom theme in your themes directory that points to a local image within that same
|
||||
location.
|
||||
|
||||
Images will preserve their aspect ratio and expand vertically to take up as many terminal rows as `footer.height`
|
||||
specifies. This parameter should be adjusted accordingly if taller-than-wider images are used in a footer.
|
||||
|
||||
See the [footer example](https://github.com/mfontanini/presenterm/blob/master/examples/footer.md) as a showcase of how a
|
||||
footer can contain images and colored text.
|
||||
|
||||
### Progress bar footers
|
||||
|
||||
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:
|
||||
@ -148,28 +204,16 @@ footer:
|
||||
character: 🚀
|
||||
```
|
||||
|
||||
### Template
|
||||
### None
|
||||
|
||||
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.
|
||||
|
||||
Besides those special variables, any of the attributes defined in the front matter can also be used:
|
||||
|
||||
* `title`.
|
||||
* `sub_title`.
|
||||
* `event`.
|
||||
* `location`.
|
||||
* `date`.
|
||||
* `author`.
|
||||
No footer at all!
|
||||
|
||||
```yaml
|
||||
footer:
|
||||
style: template
|
||||
left: "My name is {author}"
|
||||
center: @myhandle
|
||||
right: "{current_slide} / {total_slides}"
|
||||
style: empty
|
||||
```
|
||||
|
||||
|
||||
## Slide title
|
||||
|
||||
Slide titles, as specified by using a setext header, has the following properties:
|
||||
@ -315,8 +359,9 @@ _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.
|
||||
Every theme can define a color palette, which includes a list of pre-defined colors and a list of background/foreground
|
||||
pairs called "classes". Colors and classes can be used when styling text via `<span>` HTML tags, whereas colors can also
|
||||
be used inside themes to avoid duplicating the same colors all over the theme definition.
|
||||
|
||||
A palette can de defined as follows:
|
||||
|
||||
@ -325,6 +370,10 @@ palette:
|
||||
colors:
|
||||
red: "f78ca2"
|
||||
purple: "986ee2"
|
||||
classes:
|
||||
foo:
|
||||
foreground: "ff0000"
|
||||
background: "00ff00"
|
||||
```
|
||||
|
||||
Any palette color can be referenced using either `palette:<name>` or `p:<name>`. This means now any part of the theme
|
||||
@ -334,5 +383,9 @@ Similarly, these colors can be used in `span` tags like:
|
||||
|
||||
```html
|
||||
<span style="color: palette:red">this is red</span>
|
||||
|
||||
<span class="foo">this is foo-colored</span>
|
||||
```
|
||||
|
||||
These colors can used anywhere in your presentation as well as in other places such as in
|
||||
[template footers](#template-footers) and [introduction slides](../introduction.md#introduction-slide).
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user