mirror of
https://github.com/mfontanini/presenterm.git
synced 2026-09-01 23:33:21 -06:00
docs: restructure docs mdbook
This commit is contained in:
Matias Fontanini
parent
f8e9ec6728
commit
3379d7a9cb
73
README.md
73
README.md
@ -25,52 +25,51 @@ Check the rest of the example presentations in the [examples directory](/example
|
||||
|
||||
# Documentation
|
||||
|
||||
Visit the [documentation][guide-introduction] to get started.
|
||||
Visit the [documentation][docs-introduction] to get started.
|
||||
|
||||
# Features
|
||||
|
||||
* Define your presentation in a single markdown file.
|
||||
* [Images and animated gifs][guide-images] on terminals like _kitty_, _iterm2_, and _wezterm_.
|
||||
* [Customizeable themes][guide-themes] including colors, margins, layout (left/center aligned content), footer for every
|
||||
slide, etc. Several [built-in themes][guide-builtin-themes] can give your presentation the look you want without
|
||||
* [Images and animated gifs][docs-images] on terminals like _kitty_, _iterm2_, and _wezterm_.
|
||||
* [Customizeable themes][docs-themes] including colors, margins, layout (left/center aligned content), footer for every
|
||||
slide, etc. Several [built-in themes][docs-builtin-themes] can give your presentation the look you want without
|
||||
having to define your own.
|
||||
* Code highlighting for a [wide list of programming languages][guide-code-highlight].
|
||||
* [Selective/dynamic][guide-selective-highlight] code highlighting that only highlights portions of code at a time.
|
||||
* [Column layouts][guide-layout].
|
||||
* [mermaid graph rendering][guide-mermaid].
|
||||
* [_LaTeX_ and _typst_ formula rendering][guide-latex].
|
||||
* [Introduction slide][guide-intro-slide] that displays the presentation title and your name.
|
||||
* [Slide titles][guide-slide-titles].
|
||||
* [Snippet execution][guide-code-execute] for various programming languages.
|
||||
* [Export presentations to PDF][guide-pdf-export].
|
||||
* [Pause][guide-pauses] portions of your slides.
|
||||
* [Custom key bindings][guide-key-bindings].
|
||||
* [Automatically reload your presentation][guide-hot-reload] every time it changes for a fast development loop.
|
||||
* [Define speaker notes][guide-speaker-notes] to aid you during presentations.
|
||||
* Code highlighting for a [wide list of programming languages][docs-code-highlight].
|
||||
* [Selective/dynamic][docs-selective-highlight] code highlighting that only highlights portions of code at a time.
|
||||
* [Column layouts][docs-layout].
|
||||
* [mermaid graph rendering][docs-mermaid].
|
||||
* [_LaTeX_ and _typst_ formula rendering][docs-latex].
|
||||
* [Introduction slide][docs-intro-slide] that displays the presentation title and your name.
|
||||
* [Slide titles][docs-slide-titles].
|
||||
* [Snippet execution][docs-code-execute] for various programming languages.
|
||||
* [Export presentations to PDF][docs-pdf-export].
|
||||
* [Pause][docs-pauses] portions of your slides.
|
||||
* [Custom key bindings][docs-key-bindings].
|
||||
* [Automatically reload your presentation][docs-hot-reload] every time it changes for a fast development loop.
|
||||
* [Define speaker notes][docs-speaker-notes] to aid you during presentations.
|
||||
|
||||
See the [introduction page][guide-introduction] to learn more.
|
||||
See the [introduction page][docs-introduction] to learn more.
|
||||
|
||||
<!-- links -->
|
||||
|
||||
[guide-introduction]: https://mfontanini.github.io/presenterm/
|
||||
[guide-installation]: https://mfontanini.github.io/presenterm/guides/installation.html
|
||||
[guide-basics]: https://mfontanini.github.io/presenterm/guides/basics.html
|
||||
[guide-intro-slide]: https://mfontanini.github.io/presenterm/guides/basics.html#introduction-slide
|
||||
[guide-slide-titles]: https://mfontanini.github.io/presenterm/guides/basics.html#slide-titles
|
||||
[guide-pauses]: https://mfontanini.github.io/presenterm/guides/basics.html#pauses
|
||||
[guide-images]: https://mfontanini.github.io/presenterm/guides/basics.html#images
|
||||
[guide-themes]: https://mfontanini.github.io/presenterm/guides/themes.html
|
||||
[guide-builtin-themes]: https://mfontanini.github.io/presenterm/guides/themes.html#built-in-themes
|
||||
[guide-code-highlight]: https://mfontanini.github.io/presenterm/guides/code-highlight.html
|
||||
[guide-code-execute]: https://mfontanini.github.io/presenterm/guides/code-highlight.html#executing-code
|
||||
[guide-selective-highlight]: https://mfontanini.github.io/presenterm/guides/code-highlight.html#selective-highlighting
|
||||
[guide-layout]: https://mfontanini.github.io/presenterm/guides/layout.html
|
||||
[guide-mermaid]: https://mfontanini.github.io/presenterm/guides/mermaid.html
|
||||
[guide-latex]: https://mfontanini.github.io/presenterm/guides/latex.html
|
||||
[guide-pdf-export]: https://mfontanini.github.io/presenterm/guides/pdf-export.html
|
||||
[guide-key-bindings]: https://mfontanini.github.io/presenterm/guides/configuration.html#key-bindings
|
||||
[guide-hot-reload]: https://mfontanini.github.io/presenterm/guides/basics.html#hot-reload
|
||||
[guide-speaker-notes]: https://mfontanini.github.io/presenterm/guides/speaker-notes.html
|
||||
[docs-introduction]: https://mfontanini.github.io/presenterm/
|
||||
[docs-basics]: https://mfontanini.github.io/presenterm/features/introduction.html
|
||||
[docs-intro-slide]: https://mfontanini.github.io/presenterm/features/introduction.html#introduction-slide
|
||||
[docs-slide-titles]: https://mfontanini.github.io/presenterm/features/introduction.html#slide-titles
|
||||
[docs-pauses]: https://mfontanini.github.io/presenterm/features/commands.html#pauses
|
||||
[docs-images]: https://mfontanini.github.io/presenterm/features/images.html
|
||||
[docs-themes]: https://mfontanini.github.io/presenterm/features/themes/introduction.html
|
||||
[docs-builtin-themes]: https://mfontanini.github.io/presenterm/features/themes/introduction.html#built-in-themes
|
||||
[docs-code-highlight]: https://mfontanini.github.io/presenterm/features/code/highlighting.html
|
||||
[docs-code-execute]: https://mfontanini.github.io/presenterm/features/code/execution.html
|
||||
[docs-selective-highlight]: https://mfontanini.github.io/presenterm/features/code/highlighting.html#selective-highlighting
|
||||
[docs-layout]: https://mfontanini.github.io/presenterm/features/layout.html
|
||||
[docs-mermaid]: https://mfontanini.github.io/presenterm/features/code/mermaid.html
|
||||
[docs-latex]: https://mfontanini.github.io/presenterm/features/code/latex.html
|
||||
[docs-pdf-export]: https://mfontanini.github.io/presenterm/features/pdf-export.html
|
||||
[docs-key-bindings]: https://mfontanini.github.io/presenterm/configuration/settings.html#key-bindings
|
||||
[docs-hot-reload]: https://mfontanini.github.io/presenterm/features/introduction.html#hot-reload
|
||||
[docs-speaker-notes]: https://mfontanini.github.io/presenterm/features/speaker-notes.html
|
||||
[bat]: https://github.com/sharkdp/bat
|
||||
[syntect]: https://github.com/trishume/syntect
|
||||
|
||||
|
||||
@ -2,18 +2,24 @@
|
||||
|
||||
[Introduction](./introduction.md)
|
||||
|
||||
# Guides
|
||||
# Docs
|
||||
|
||||
- [Installation](./guides/installation.md)
|
||||
- [Basics](./guides/basics.md)
|
||||
- [Themes](./guides/themes.md)
|
||||
- [Layout](./guides/layout.md)
|
||||
- [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)
|
||||
- [Install](./install.md)
|
||||
- [Features](./features/introduction.md)
|
||||
- [Images](./features/images.md).
|
||||
- [Commands](./features/commands.md).
|
||||
- [Layout](./features/layout.md).
|
||||
- [Code](./features/code/highlighting.md)
|
||||
- [Execution](./features/code/execution.md)
|
||||
- [Mermaid diagrams](./features/code/mermaid.md)
|
||||
- [LaTeX and typst](./features/code/latex.md)
|
||||
- [Themes](./features/themes/introduction.md)
|
||||
- [Definition](./features/themes/definition.md)
|
||||
- [PDF export](./features/pdf-export.md)
|
||||
- [Speaker notes](./features/speaker-notes.md)
|
||||
- [Configuration](./configuration/introduction.md)
|
||||
- [Options](./configuration/options.md)
|
||||
- [Settings](./configuration/settings.md)
|
||||
|
||||
# Internals
|
||||
|
||||
|
||||
28
docs/src/configuration/introduction.md
Normal file
28
docs/src/configuration/introduction.md
Normal file
@ -0,0 +1,28 @@
|
||||
# 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:
|
||||
|
||||
* `$XDG_CONFIG_HOME/presenterm/` if that environment variable is defined, otherwise:
|
||||
* `~/.config/presenterm/` in Linux.
|
||||
* `~/Library/Application Support/presenterm/` in macOS.
|
||||
* `~/AppData/Roaming/presenterm/config/` in Windows.
|
||||
|
||||
The configuration file will be looked up automatically in the directories above under the name `config.yaml`. e.g. on
|
||||
Linux you should create it under `~/.config/presenterm/config.yaml`. You can also specify a custom path to this file
|
||||
when running _presenterm_ via the `--config-path` parameter.
|
||||
|
||||
A [sample configuration file](https://github.com/mfontanini/presenterm/blob/master/config.sample.yaml) is provided in
|
||||
the repository that you can use as a base.
|
||||
|
||||
# Configuration schema
|
||||
|
||||
A JSON schema that defines the configuration file's schema is available to be used with YAML language servers such as
|
||||
[yaml-language-server](https://github.com/redhat-developer/yaml-language-server).
|
||||
|
||||
Include the following line at the beginning of your configuration file to have your editor pull in autocompletion
|
||||
suggestions and docs automatically:
|
||||
|
||||
```yaml
|
||||
# yaml-language-server: $schema=https://raw.githubusercontent.com/mfontanini/presenterm/master/config-file-schema.json
|
||||
```
|
||||
165
docs/src/configuration/options.md
Normal file
165
docs/src/configuration/options.md
Normal file
@ -0,0 +1,165 @@
|
||||
# Options
|
||||
|
||||
Options are special configuration parameters that can be set either in the configuration file under the `options` key,
|
||||
or in a presentation's front matter under the same key. This last one allows you to customize a single presentation so
|
||||
that it acts in a particular way. This can also be useful if you'd like to share the source files for your presentation
|
||||
with other people.
|
||||
|
||||
The supported configuration options are currently the following:
|
||||
|
||||
## implicit_slide_ends
|
||||
|
||||
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:
|
||||
|
||||
```markdown
|
||||
---
|
||||
options:
|
||||
implicit_slide_ends: true
|
||||
---
|
||||
|
||||
Tasty vegetables
|
||||
================
|
||||
|
||||
* Potato
|
||||
|
||||
Awful vegetables
|
||||
================
|
||||
|
||||
* Lettuce
|
||||
```
|
||||
|
||||
Is equivalent to this "vanilla" one that doesn't use implicit slide ends.
|
||||
|
||||
```markdown
|
||||
Tasty vegetables
|
||||
================
|
||||
|
||||
* Potato
|
||||
|
||||
<!-- end_slide -->
|
||||
|
||||
Awful vegetables
|
||||
================
|
||||
|
||||
* Lettuce
|
||||
```
|
||||
|
||||
## end_slide_shorthand
|
||||
|
||||
This option allows using thematic breaks (`---`) as a delimiter between slides. When enabling this option, you can still
|
||||
use `<!-- end_slide -->` but any thematic break will also be considered a slide terminator.
|
||||
|
||||
```
|
||||
---
|
||||
options:
|
||||
end_slide_shorthand: true
|
||||
---
|
||||
|
||||
this is a slide
|
||||
|
||||
---------------------
|
||||
|
||||
this is another slide
|
||||
```
|
||||
|
||||
## command_prefix
|
||||
|
||||
Because _presenterm_ uses HTML comments to represent commands, it is necessary to make some assumptions on _what_ is a
|
||||
command and what isn't. The current heuristic is:
|
||||
|
||||
* If an HTML comment is laid out on a single line, it is assumed to be a command. This means if you want to use a real
|
||||
HTML comment like `<!-- remember to say "potato" here -->`, this will raise an error.
|
||||
* If an HTML comment is multi-line, then it is assumed to be a comment and it can have anything inside it. This means
|
||||
you can't have a multi-line comment that contains a command like `pause` inside.
|
||||
|
||||
Depending on how you use HTML comments personally, this may be limiting to you: you cannot use any single line comments
|
||||
that are not commands. To get around this, the `command_prefix` option lets you configure a prefix that must be set in
|
||||
all commands for them to be configured as such. Any single line comment that doesn't start with this prefix will not be
|
||||
considered a command.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
---
|
||||
options:
|
||||
command_prefix: "cmd:"
|
||||
---
|
||||
|
||||
<!-- remember to say "potato here" -->
|
||||
|
||||
Tasty vegetables
|
||||
================
|
||||
|
||||
* Potato
|
||||
|
||||
<!-- cmd:pause -->
|
||||
|
||||
**That's it!**
|
||||
```
|
||||
|
||||
In the example above, the first comment is ignored because it doesn't start with "cmd:" and the second one is processed
|
||||
because it does.
|
||||
|
||||
## incremental_lists
|
||||
|
||||
If you'd like all bullet points in all lists to show up with pauses in between you can enable the `incremental_lists`
|
||||
option:
|
||||
|
||||
```
|
||||
---
|
||||
options:
|
||||
incremental_lists: true
|
||||
---
|
||||
|
||||
* pauses
|
||||
* in
|
||||
* between
|
||||
```
|
||||
|
||||
Keep in mind if you only want specific bullet points to show up with pauses in between, you can use the
|
||||
[`incremental_lists` comment command](../features/commands.md#incremental-lists).
|
||||
|
||||
## strict_front_matter_parsing
|
||||
|
||||
This option tells _presenterm_ you don't care about extra parameters in presentation's front matter. This can be useful
|
||||
if you're trying to load a presentation made for another tool. The following presentation would only be successfully
|
||||
loaded if you set `strict_front_matter_parsing` to `false` in your configuration file:
|
||||
|
||||
```markdown
|
||||
---
|
||||
potato: 42
|
||||
---
|
||||
|
||||
# Hi
|
||||
```
|
||||
|
||||
## image_attributes_prefix
|
||||
|
||||
The [image size](../features/images.md#image-size) prefix (by default `image:`) can be configured to be anything you
|
||||
would want in case you don't like the default one. For example, if you'd like to set the image size by simply doing
|
||||
`` you would need to set:
|
||||
|
||||
```yaml
|
||||
---
|
||||
options:
|
||||
image_attributes_prefix: ""
|
||||
---
|
||||
|
||||
|
||||
```
|
||||
|
||||
## 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
|
||||
---
|
||||
```
|
||||
|
||||
@ -1,190 +1,8 @@
|
||||
# Configuration
|
||||
# Settings
|
||||
|
||||
_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:
|
||||
As opposed to options, the rest of these settings **can only be configured via the configuration file**.
|
||||
|
||||
* `$XDG_CONFIG_HOME/presenterm/` if that environment variable is defined, otherwise:
|
||||
* `~/.config/presenterm/` in Linux.
|
||||
* `~/Library/Application Support/presenterm/` in macOS.
|
||||
* `~/AppData/Roaming/presenterm/config/` in Windows.
|
||||
|
||||
The configuration file will be looked up automatically in the directories above under the name `config.yaml`. e.g. on
|
||||
Linux you should create it under `~/.config/presenterm/config.yaml`. You can also specify a custom path to this file
|
||||
when running _presenterm_ via the `--config-path` parameter.
|
||||
|
||||
A [sample configuration file](https://github.com/mfontanini/presenterm/blob/master/config.sample.yaml) is provided in
|
||||
the repository that you can use as a base.
|
||||
|
||||
## Options
|
||||
|
||||
Options are special configuration parameters that can be set either in the configuration file under the `options` key,
|
||||
or in a presentation's front matter under the same key. This last one allows you to customize a single presentation so
|
||||
that it acts in a particular way. This can also be useful if you'd like to share the source files for your presentation
|
||||
with other people.
|
||||
|
||||
The supported configuration options are currently the following:
|
||||
|
||||
### implicit_slide_ends
|
||||
|
||||
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:
|
||||
|
||||
```markdown
|
||||
---
|
||||
options:
|
||||
implicit_slide_ends: true
|
||||
---
|
||||
|
||||
Tasty vegetables
|
||||
================
|
||||
|
||||
* Potato
|
||||
|
||||
Awful vegetables
|
||||
================
|
||||
|
||||
* Lettuce
|
||||
```
|
||||
|
||||
Is equivalent to this "vanilla" one that doesn't use implicit slide ends.
|
||||
|
||||
```markdown
|
||||
Tasty vegetables
|
||||
================
|
||||
|
||||
* Potato
|
||||
|
||||
<!-- end_slide -->
|
||||
|
||||
Awful vegetables
|
||||
================
|
||||
|
||||
* Lettuce
|
||||
```
|
||||
|
||||
### end_slide_shorthand
|
||||
|
||||
This option allows using thematic breaks (`---`) as a delimiter between slides. When enabling this option, you can still
|
||||
use `<!-- end_slide -->` but any thematic break will also be considered a slide terminator.
|
||||
|
||||
```
|
||||
---
|
||||
options:
|
||||
end_slide_shorthand: true
|
||||
---
|
||||
|
||||
this is a slide
|
||||
|
||||
---------------------
|
||||
|
||||
this is another slide
|
||||
```
|
||||
|
||||
### command_prefix
|
||||
|
||||
Because _presenterm_ uses HTML comments to represent commands, it is necessary to make some assumptions on _what_ is a
|
||||
command and what isn't. The current heuristic is:
|
||||
|
||||
* If an HTML comment is laid out on a single line, it is assumed to be a command. This means if you want to use a real
|
||||
HTML comment like `<!-- remember to say "potato" here -->`, this will raise an error.
|
||||
* If an HTML comment is multi-line, then it is assumed to be a comment and it can have anything inside it. This means
|
||||
you can't have a multi-line comment that contains a command like `pause` inside.
|
||||
|
||||
Depending on how you use HTML comments personally, this may be limiting to you: you cannot use any single line comments
|
||||
that are not commands. To get around this, the `command_prefix` option lets you configure a prefix that must be set in
|
||||
all commands for them to be configured as such. Any single line comment that doesn't start with this prefix will not be
|
||||
considered a command.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
---
|
||||
options:
|
||||
command_prefix: "cmd:"
|
||||
---
|
||||
|
||||
<!-- remember to say "potato here" -->
|
||||
|
||||
Tasty vegetables
|
||||
================
|
||||
|
||||
* Potato
|
||||
|
||||
<!-- cmd:pause -->
|
||||
|
||||
**That's it!**
|
||||
```
|
||||
|
||||
In the example above, the first comment is ignored because it doesn't start with "cmd:" and the second one is processed
|
||||
because it does.
|
||||
|
||||
### incremental_lists
|
||||
|
||||
If you'd like all bullet points in all lists to show up with pauses in between you can enable the `incremental_lists`
|
||||
option:
|
||||
|
||||
```
|
||||
---
|
||||
options:
|
||||
incremental_lists: true
|
||||
---
|
||||
|
||||
* pauses
|
||||
* in
|
||||
* between
|
||||
```
|
||||
|
||||
Keep in mind if you only want specific bullet points to show up with pauses in between, you can use the
|
||||
[`incremental_lists` comment command](basics.html#incremental-lists).
|
||||
|
||||
### strict_front_matter_parsing
|
||||
|
||||
This option tells _presenterm_ you don't care about extra parameters in presentation's front matter. This can be useful
|
||||
if you're trying to load a presentation made for another tool. The following presentation would only be successfully
|
||||
loaded if you set `strict_front_matter_parsing` to `false` in your configuration file:
|
||||
|
||||
```markdown
|
||||
---
|
||||
potato: 42
|
||||
---
|
||||
|
||||
# Hi
|
||||
```
|
||||
|
||||
### image_attributes_prefix
|
||||
|
||||
The [image size](basics.html#image-size) prefix (by default `image:`) can be configured to be anything you would want in
|
||||
case you don't like the default one. For example, if you'd like to set the image size by simply doing
|
||||
`` you would need to set:
|
||||
|
||||
```yaml
|
||||
---
|
||||
options:
|
||||
image_attributes_prefix: ""
|
||||
---
|
||||
|
||||
|
||||
```
|
||||
|
||||
### 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**.
|
||||
|
||||
### Default theme
|
||||
## Default theme
|
||||
|
||||
The default theme can be configured only via the config file. When this is set, every presentation that doesn't set a
|
||||
theme explicitly will use this one:
|
||||
@ -194,7 +12,7 @@ defaults:
|
||||
theme: light
|
||||
```
|
||||
|
||||
### Terminal font size
|
||||
## Terminal font size
|
||||
|
||||
This is a parameter that lets you explicitly set the terminal font size in use. This should not be used unless you are
|
||||
in Windows, given there's no (easy) way to get the terminal window size so we use this to figure out how large the
|
||||
@ -209,7 +27,7 @@ defaults:
|
||||
terminal_font_size: 16
|
||||
```
|
||||
|
||||
### 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 case
|
||||
detection for some reason fails in your setup or you'd like to force a different protocol to be used, you can explicitly
|
||||
@ -229,7 +47,7 @@ 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
|
||||
## 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
|
||||
@ -240,7 +58,7 @@ 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
|
||||
is the default configuration:
|
||||
@ -287,13 +105,13 @@ bindings:
|
||||
You can choose to override any of them. Keep in mind these are overrides so if for example you change `next`, the
|
||||
default won't apply anymore and only what you've defined will be used.
|
||||
|
||||
## Snippet configurations
|
||||
# Snippet configurations
|
||||
|
||||
### Snippet execution
|
||||
## Snippet execution
|
||||
|
||||
[Snippet execution](code-highlight.html#executing-code-blocks) is disabled by default for security reasons. Besides
|
||||
passing in the `-x` command line parameter every time you run _presenterm_, you can also configure this globally for all
|
||||
presentations by setting:
|
||||
[Snippet execution](../features/code/execution.md#executing-code-blocks) is disabled by default for security reasons.
|
||||
Besides passing in the `-x` command line parameter every time you run _presenterm_, you can also configure this globally
|
||||
for all presentations by setting:
|
||||
|
||||
```yaml
|
||||
snippet:
|
||||
@ -303,11 +121,11 @@ snippet:
|
||||
|
||||
**Use this at your own risk**, especially if you're running someone else's presentations!
|
||||
|
||||
### Snippet execution + replace
|
||||
## Snippet execution + replace
|
||||
|
||||
[Snippet execution + replace](code-highlight.html#executing-and-replacing) is disabled by default for security reasons.
|
||||
Similar to `+exec`, this can be enabled by passing in the `-X` command line parameter or configuring it globally by
|
||||
setting:
|
||||
[Snippet execution + replace](../features/code/execution.md#executing-and-replacing) is disabled by default for security
|
||||
reasons. Similar to `+exec`, this can be enabled by passing in the `-X` command line parameter or configuring it
|
||||
globally by setting:
|
||||
|
||||
```yaml
|
||||
snippet:
|
||||
@ -318,7 +136,7 @@ snippet:
|
||||
**Use this at your own risk**. This will cause _presenterm_ to execute code without user intervention so don't blindly
|
||||
enable this and open a presentation unless you trust its origin!
|
||||
|
||||
### Custom snippet executors
|
||||
## Custom snippet executors
|
||||
|
||||
If _presenterm_ doesn't support executing code snippets for your language of choice, please [create an
|
||||
issue](https://github.com/mfontanini/presenterm/issues/new)! Alternatively, you can configure this locally yourself by
|
||||
@ -358,7 +176,7 @@ example above).
|
||||
See more examples in the [executors.yaml](https://github.com/mfontanini/presenterm/blob/master/executors.yaml) file
|
||||
which defines all of the built-in executors.
|
||||
|
||||
### Snippet rendering threads
|
||||
## Snippet rendering threads
|
||||
|
||||
Because some `+render` code blocks can take some time to be rendered into an image, especially if you're using
|
||||
[mermaid](https://mermaid.js.org/) charts, this is run asychronously. The number of threads used to render these, which
|
||||
@ -370,7 +188,7 @@ snippet:
|
||||
threads: 2
|
||||
```
|
||||
|
||||
### Mermaid scaling
|
||||
## Mermaid scaling
|
||||
|
||||
[mermaid](https://mermaid.js.org/) graphs will use a default scaling of `2` when invoking the mermaid CLI. If you'd like
|
||||
to change this use:
|
||||
@ -381,7 +199,7 @@ mermaid:
|
||||
scale: 2
|
||||
```
|
||||
|
||||
### Enabling speaker note publishing
|
||||
## 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`.
|
||||
@ -391,3 +209,4 @@ speaker_notes:
|
||||
always_pubblish: true
|
||||
```
|
||||
|
||||
|
||||
@ -1,135 +1,3 @@
|
||||
# Code highlighting
|
||||
|
||||
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
|
||||
|
||||
## 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:
|
||||
|
||||
~~~markdown
|
||||
```rust +line_numbers
|
||||
fn hello_world() {
|
||||
println!("Hello world");
|
||||
}
|
||||
```
|
||||
~~~
|
||||
|
||||
## 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.
|
||||
|
||||
~~~markdown
|
||||
```rust {1,3,5-7}
|
||||
fn potato() -> u32 { // 1: highlighted
|
||||
// 2: not highlighted
|
||||
println!("Hello world"); // 3: highlighted
|
||||
let mut q = 42; // 4: not highlighted
|
||||
q = q * 1337; // 5: highlighted
|
||||
q // 6: highlighted
|
||||
} // 7: highlighted
|
||||
```
|
||||
~~~
|
||||
|
||||
## 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.
|
||||
|
||||
This is achieved by using the separator `|` to indicate what sections of the code will be highlighted at a given time.
|
||||
You can also use `all` to highlight all lines for a particular frame.
|
||||
|
||||
~~~markdown
|
||||
```rust {1,3|5-7}
|
||||
fn potato() -> u32 {
|
||||
|
||||
println!("Hello world");
|
||||
let mut q = 42;
|
||||
q = q * 1337;
|
||||
q
|
||||
}
|
||||
```
|
||||
~~~
|
||||
|
||||
In this example, lines 1 and 3 will be highlighted initially. Then once you press a key to move to the next slide, lines
|
||||
1 and 3 will no longer be highlighted and instead lines 5 through 7 will. This allows you to create more dynamic
|
||||
presentations where you can display sections of the code to explain something specific about each of them.
|
||||
|
||||
See this real example of how this looks like.
|
||||
|
||||
[](https://asciinema.org/a/iCf4f6how1Ux3H8GNzksFUczI)
|
||||
|
||||
## 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.
|
||||
|
||||
~~~markdown
|
||||
```file +exec +line_numbers
|
||||
path: snippet.rs
|
||||
language: rust
|
||||
```
|
||||
~~~
|
||||
|
||||
## 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
|
||||
|
||||
## Executing code blocks
|
||||
@ -149,7 +17,7 @@ Code execution **must be explicitly enabled** by using either:
|
||||
|
||||
* The `-x` command line parameter when running _presenterm_.
|
||||
* Setting the `snippet.exec.enable` property to `true` in your [_presenterm_ config
|
||||
file](configuration.html#snippet-execution).
|
||||
file](../../configuration/settings.md#snippet-execution).
|
||||
|
||||
---
|
||||
|
||||
@ -181,7 +49,7 @@ it lets you use dependencies.
|
||||
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.html#custom-snippet-executors).
|
||||
file](../../configuration/settings.md#custom-snippet-executors).
|
||||
|
||||
[](https://asciinema.org/a/BbAY817esxagCgPtnKUwgYnHr)
|
||||
|
||||
@ -280,7 +148,7 @@ is loaded. The languages that currently support this are _mermaid_, _LaTeX_, and
|
||||
block is transformed into an image, allowing you to define formulas as text in your presentation. This can be done by
|
||||
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.md) and [mermaid](mermaid.md) docs for more information.
|
||||
|
||||
## Adding highlighting syntaxes for new languages
|
||||
|
||||
@ -298,3 +166,5 @@ invoke _bat_ directly in a presentation:
|
||||
bat --color always script.py
|
||||
```
|
||||
~~~
|
||||
|
||||
|
||||
132
docs/src/features/code/highlighting.md
Normal file
132
docs/src/features/code/highlighting.md
Normal file
@ -0,0 +1,132 @@
|
||||
# Code highlighting
|
||||
|
||||
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
|
||||
|
||||
## 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:
|
||||
|
||||
~~~markdown
|
||||
```rust +line_numbers
|
||||
fn hello_world() {
|
||||
println!("Hello world");
|
||||
}
|
||||
```
|
||||
~~~
|
||||
|
||||
## 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.
|
||||
|
||||
~~~markdown
|
||||
```rust {1,3,5-7}
|
||||
fn potato() -> u32 { // 1: highlighted
|
||||
// 2: not highlighted
|
||||
println!("Hello world"); // 3: highlighted
|
||||
let mut q = 42; // 4: not highlighted
|
||||
q = q * 1337; // 5: highlighted
|
||||
q // 6: highlighted
|
||||
} // 7: highlighted
|
||||
```
|
||||
~~~
|
||||
|
||||
## 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.
|
||||
|
||||
This is achieved by using the separator `|` to indicate what sections of the code will be highlighted at a given time.
|
||||
You can also use `all` to highlight all lines for a particular frame.
|
||||
|
||||
~~~markdown
|
||||
```rust {1,3|5-7}
|
||||
fn potato() -> u32 {
|
||||
|
||||
println!("Hello world");
|
||||
let mut q = 42;
|
||||
q = q * 1337;
|
||||
q
|
||||
}
|
||||
```
|
||||
~~~
|
||||
|
||||
In this example, lines 1 and 3 will be highlighted initially. Then once you press a key to move to the next slide, lines
|
||||
1 and 3 will no longer be highlighted and instead lines 5 through 7 will. This allows you to create more dynamic
|
||||
presentations where you can display sections of the code to explain something specific about each of them.
|
||||
|
||||
See this real example of how this looks like.
|
||||
|
||||
[](https://asciinema.org/a/iCf4f6how1Ux3H8GNzksFUczI)
|
||||
|
||||
## 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.
|
||||
|
||||
~~~markdown
|
||||
```file +exec +line_numbers
|
||||
path: snippet.rs
|
||||
language: rust
|
||||
```
|
||||
~~~
|
||||
|
||||
## 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.
|
||||
|
||||
@ -1,8 +1,22 @@
|
||||
# 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.
|
||||
`latex` and `typst` code blocks can be marked with the `+render` attribute (see [highlighting](highlighting.md)) 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.
|
||||
|
||||
For example, the following presentation:
|
||||
|
||||
~~~
|
||||
# Formulas
|
||||
|
||||
```latex +render
|
||||
\[ \sum_{n=1}^{\infty} 2^{-n} = 1 \]
|
||||
```
|
||||
~~~
|
||||
|
||||
Would be rendered like this:
|
||||
|
||||
|
||||
|
||||
## Dependencies
|
||||
|
||||
@ -13,9 +27,9 @@ install, lightweight, and boilerplate free as compared to _LaTeX_.
|
||||
|
||||
### 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_.
|
||||
This lets us:
|
||||
For _LaTeX_ code rendering both _typst_ and [pandoc](https://github.com/jgm/pandoc) are required. How this works is the
|
||||
_LaTeX_ code you write gets transformed into _typst_ code via _pandoc_ and then rendered by using _typst_. This lets us:
|
||||
|
||||
* Have the same look/feel on generated formulas for both languages.
|
||||
* 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_.
|
||||
@ -28,7 +42,7 @@ generated on the fly will have a fixed size. Configuring the PPI used during the
|
||||
higher the PPI, the larger the generated images will be.
|
||||
|
||||
Because as opposed to most configurations this is a very environment-specific config, the PPI parameter is not part of
|
||||
the theme definition but is instead has to be set in [_presenterm_'s config file](configuration.html):
|
||||
the theme definition but is instead has to be set in _presenterm_'s [config file](../../configuration/introduction.md):
|
||||
|
||||
```yaml
|
||||
typst:
|
||||
@ -72,19 +86,3 @@ typst:
|
||||
horizontal_margin: 2
|
||||
vertical_margin: 2
|
||||
```
|
||||
|
||||
# Example
|
||||
|
||||
The following example:
|
||||
|
||||
~~~
|
||||
# Formulas
|
||||
|
||||
```latex +render
|
||||
\[ \sum_{n=1}^{\infty} 2^{-n} = 1 \]
|
||||
```
|
||||
~~~
|
||||
|
||||
Is rendered like this:
|
||||
|
||||
|
||||
@ -15,11 +15,11 @@ sequenceDiagram
|
||||
|
||||
Note that because the mermaid CLI will spin up a browser under the hood, this may not work in all environments and can
|
||||
also be a bit slow (e.g. ~2 seconds to generate every image). Mermaid graphs are rendered asynchronously by a number of
|
||||
threads that can be configured in the [configuration file](configuration.html#snippet-rendering-threads). This
|
||||
configuration value currently defaults to 2.
|
||||
threads that can be configured in the [configuration file](../../configuration/settings.md#snippet-rendering-threads).
|
||||
This configuration value currently defaults to 2.
|
||||
|
||||
The size of the rendered image can be configured by changing:
|
||||
* The `mermaid.scale` [configuration parameter](configuration.html#mermaid-scaling).
|
||||
* The `mermaid.scale` [configuration parameter](../../configuration/settings.md#mermaid-scaling).
|
||||
* Using the `+width:<number>%` attribute in the code snippet.
|
||||
|
||||
For example, this diagram will take up 50% of the width of the window and will preserve its aspect ratio:
|
||||
@ -38,12 +38,13 @@ cause the image to become blurry.
|
||||
|
||||
## Theme
|
||||
|
||||
The theme of the rendered mermaid diagrams can be changed through the following [theme](themes.html#mermaid) parameters:
|
||||
The theme of the rendered mermaid diagrams can be changed through the following
|
||||
[theme](../themes/introduction.md#mermaid) parameters:
|
||||
|
||||
* `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
|
||||
## Always render diagrams
|
||||
|
||||
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).
|
||||
file](../../configuration/settings.md#auto_render_languages).
|
||||
72
docs/src/features/commands.md
Normal file
72
docs/src/features/commands.md
Normal file
@ -0,0 +1,72 @@
|
||||
# Comment commands
|
||||
|
||||
_presenterm_ uses "comment commands" in the form of HTML comments to let the user specify certain behaviors that can't
|
||||
be specified by vanilla markdown.
|
||||
|
||||
## 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
|
||||
command:
|
||||
|
||||
```html
|
||||
<!-- pause -->
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
```markdown
|
||||
blablabla
|
||||
|
||||
<!-- end_slide -->
|
||||
|
||||
<!-- jump_to_middle -->
|
||||
|
||||
Farming potatoes
|
||||
===
|
||||
|
||||
<!-- end_slide -->
|
||||
```
|
||||
|
||||
This will create a slide with the text "Farming potatoes" in the center, rendered using the slide title style.
|
||||
|
||||
## 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:
|
||||
|
||||
```markdown
|
||||
hi
|
||||
|
||||
<!-- new_lines: 10 -->
|
||||
|
||||
mom
|
||||
|
||||
<!-- new_line -->
|
||||
|
||||
bye
|
||||
```
|
||||
|
||||
## Incremental lists
|
||||
|
||||
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
|
||||
bullet point to appear only after you move to the next slide:
|
||||
|
||||
```markdown
|
||||
<!-- incremental_lists: true -->
|
||||
|
||||
* this
|
||||
* appears
|
||||
* one after
|
||||
* the other
|
||||
|
||||
<!-- incremental_lists: false -->
|
||||
|
||||
* this appears
|
||||
* all at once
|
||||
```
|
||||
|
||||
51
docs/src/features/images.md
Normal file
51
docs/src/features/images.md
Normal file
@ -0,0 +1,51 @@
|
||||
# Images
|
||||
|
||||
Images are supported and will render in your terminal as long as it supports either the [iterm2 image
|
||||
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](https://sw.kovidgoyal.net/kitty/)
|
||||
* [iterm2](https://iterm2.com/)
|
||||
* [WezTerm](https://wezfurlong.org/wezterm/index.html)
|
||||
* [foot](https://codeberg.org/dnkl/foot)
|
||||
|
||||
Sixel support is experimental so it needs to be explicitly enabled via the `sixel` configuration flag:
|
||||
|
||||
```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 using this flag is often not required to get images to render successfully.
|
||||
|
||||
---
|
||||
|
||||
Things you should know when using image tags in your presentation's markdown are:
|
||||
* Image paths are relative to your presentation path. That is a tag like `` will be looked up at
|
||||
`$PRESENTATION_DIRECTORY/food/potato.png`.
|
||||
* Images will be rendered by default in their original size. That is, if your terminal is 300x200px and your image is
|
||||
200x100px, it will take up 66% of your horizontal space and 50% of your vertical space.
|
||||
* The exception to the point above is if the image does not fit in your terminal, it will be resized accordingly while
|
||||
preserving the aspect ratio.
|
||||
* 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
|
||||
|
||||
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:
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
The image will always be scaled to preserve its aspect ratio and it will not be allowed to overflow vertically nor
|
||||
horizontally.
|
||||
|
||||
## Protocol detection
|
||||
|
||||
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/settings.md#preferred-image-protocol).
|
||||
@ -1,7 +1,7 @@
|
||||
# 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.
|
||||
visit the [installation](../installation.md) guide to get started.
|
||||
|
||||
## Quick start
|
||||
|
||||
@ -25,81 +25,6 @@ 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.
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
|
||||
Images are supported and will render in your terminal as long as it supports either the [iterm2 image
|
||||
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](https://sw.kovidgoyal.net/kitty/)
|
||||
* [iterm2](https://iterm2.com/)
|
||||
* [WezTerm](https://wezfurlong.org/wezterm/index.html)
|
||||
* [foot](https://codeberg.org/dnkl/foot)
|
||||
|
||||
Sixel support is experimental so it needs to be explicitly enabled via the `sixel` configuration flag:
|
||||
|
||||
```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 using this flag is often not required to get images to render successfully.
|
||||
|
||||
---
|
||||
|
||||
Things you should know when using image tags in your presentation's markdown are:
|
||||
* Image paths are relative to your presentation path. That is a tag like `` will be looked up at
|
||||
`$PRESENTATION_DIRECTORY/food/potato.png`.
|
||||
* Images will be rendered by default in their original size. That is, if your terminal is 300x200px and your image is
|
||||
200x100px, it will take up 66% of your horizontal space and 50% of your vertical space.
|
||||
* The exception to the point above is if the image does not fit in your terminal, it will be resized accordingly while
|
||||
preserving the aspect ratio.
|
||||
* 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
|
||||
|
||||
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:
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
The image will always be scaled to preserve its aspect ratio and it will not be allowed to overflow vertically nor
|
||||
horizontally.
|
||||
|
||||
### Protocol detection
|
||||
|
||||
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
|
||||
|
||||
Besides the standard markdown elements, _presenterm_ supports a few extensions.
|
||||
|
||||
## Introduction slide
|
||||
|
||||
By setting a front matter at the beginning of your presentation, you can configure the title, sub title, and author of
|
||||
@ -141,18 +66,8 @@ Hello
|
||||
~~~
|
||||
|
||||
> [!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 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
|
||||
command:
|
||||
|
||||
```html
|
||||
<!-- pause -->
|
||||
```
|
||||
> See the [themes](themes/introduction.md) section on how to customize the looks of slide titles and any other element
|
||||
> in a presentation.
|
||||
|
||||
## Ending slides
|
||||
|
||||
@ -164,67 +79,27 @@ While other applications use a thematic break (`---`) to mark the end of a slide
|
||||
```
|
||||
|
||||
This makes the end of a slide more explicit and easy to spot while you're editing your presentation. See the
|
||||
[configuration](/docs/config.md#implicit_slide_ends) if you want to customize this behavior.
|
||||
[configuration](../configuration/options.md#implicit_slide_ends) if you want to customize this behavior.
|
||||
|
||||
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/options.md#end_slide_shorthand) options.
|
||||
|
||||
## Jumping to the vertical center
|
||||
## Colored text
|
||||
|
||||
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:
|
||||
`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.
|
||||
|
||||
For example, the following will use `ff0000` as the foreground color and whatever the active theme's palette defines as
|
||||
`foo`:
|
||||
|
||||
```markdown
|
||||
blablabla
|
||||
|
||||
<!-- end_slide -->
|
||||
|
||||
<!-- jump_to_middle -->
|
||||
|
||||
Farming potatoes
|
||||
===
|
||||
|
||||
<!-- end_slide -->
|
||||
<span style="color: #ff0000; background-color: palette:foo">colored text!</span>
|
||||
```
|
||||
|
||||
This will create a slide with the text "Farming potatoes" in the center, rendered using the slide title style.
|
||||
|
||||
## 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:
|
||||
|
||||
```markdown
|
||||
hi
|
||||
|
||||
<!-- new_lines: 10 -->
|
||||
|
||||
mom
|
||||
|
||||
<!-- new_line -->
|
||||
|
||||
bye
|
||||
```
|
||||
|
||||
## Incremental lists
|
||||
|
||||
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
|
||||
bullet point to appear only after you move to the next slide:
|
||||
|
||||
```markdown
|
||||
<!-- incremental_lists: true -->
|
||||
|
||||
* this
|
||||
* appears
|
||||
* one after
|
||||
* the other
|
||||
|
||||
<!-- incremental_lists: false -->
|
||||
|
||||
* this appears
|
||||
* all at once
|
||||
```
|
||||
> [!note]
|
||||
> Keep in mind **only `span` tags are supported**.
|
||||
|
||||
# Key bindings
|
||||
|
||||
@ -243,13 +118,13 @@ You can check all the configured keybindings by pressing `?` while running _pres
|
||||
## Configuring key bindings
|
||||
|
||||
If you don't like the default key bindings, you can override them in the [configuration
|
||||
file](configuration.html#key-bindings).
|
||||
file](../configuration/settings.md#key-bindings).
|
||||
|
||||
# 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).
|
||||
the [configuration file key bindings](../configuration/settings.md#key-bindings).
|
||||
|
||||
## Slide index modal
|
||||
|
||||
@ -93,7 +93,7 @@ Because we just reset the layout, this text is now below both of the columns.
|
||||
|
||||
This would render the following way:
|
||||
|
||||
|
||||
|
||||
|
||||
## Other uses
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# PDF export
|
||||
# Exporting presentations in PDF format
|
||||
|
||||
Presentations can be converted into PDF by using a [helper tool](https://github.com/mfontanini/presenterm-export). You
|
||||
can install it by running:
|
||||
@ -7,13 +7,15 @@ can install it by running:
|
||||
pip install presenterm-export
|
||||
```
|
||||
|
||||
> [!tip]
|
||||
> [!important]
|
||||
> 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:
|
||||
_presenterm-export_ uses [tmux](https://github.com/tmux/tmux/) to run _presenterm_ inside it and capture its output.
|
||||
|
||||
After you've installed both _presenterm-export_ and _tmux_, run _presenterm_ with the `--export-pdf` parameter to
|
||||
generate the output PDF:
|
||||
|
||||
```bash
|
||||
presenterm --export-pdf examples/demo.md
|
||||
@ -30,7 +32,7 @@ The output PDF will be placed in `examples/demo.pdf`.
|
||||
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
|
||||
## tmux <= 3.5a active 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
|
||||
@ -1,106 +1,7 @@
|
||||
# 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
|
||||
|
||||
There's various ways of setting the theme you want in your presentation:
|
||||
|
||||
### CLI
|
||||
|
||||
Passing in the `--theme` parameter when running _presenterm_ to select one of the built-in themes.
|
||||
|
||||
### 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
|
||||
|
||||
Using a built-in theme name makes your presentation use that one regardless of what the default or what the `--theme`
|
||||
option specifies:
|
||||
|
||||
```yaml
|
||||
---
|
||||
theme:
|
||||
name: dark
|
||||
---
|
||||
```
|
||||
|
||||
#### By path
|
||||
|
||||
You can define a theme file in yaml format somewhere in your filesystem and reference it within the presentation:
|
||||
|
||||
```yaml
|
||||
---
|
||||
theme:
|
||||
path: /home/me/Documents/epic-theme.yaml
|
||||
---
|
||||
```
|
||||
|
||||
#### Overrides
|
||||
|
||||
You can partially/completely override the theme in use from within the presentation:
|
||||
|
||||
```yaml
|
||||
---
|
||||
theme:
|
||||
override:
|
||||
default:
|
||||
colors:
|
||||
foreground: "beeeff"
|
||||
---
|
||||
```
|
||||
|
||||
This lets you:
|
||||
|
||||
1. Create a unique style for your presentation without having to go through the process of taking an existing theme,
|
||||
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
|
||||
|
||||
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
|
||||
demand only when used.
|
||||
|
||||
Currently, the following themes are supported:
|
||||
|
||||
* `dark`: A dark theme.
|
||||
* `light`: A light theme.
|
||||
* `tokyonight-storm`: A theme inspired by the colors used in [toyonight](https://github.com/folke/tokyonight.nvim).
|
||||
* A set of themes based on the [catppuccin](https://github.com/catppuccin/catppuccin) color palette:
|
||||
* `catppuccin-latte`
|
||||
* `catppuccin-frappe`
|
||||
* `catppuccin-macchiato`
|
||||
* `catppuccin-mocha`
|
||||
* `terminal-dark`: A theme that uses your terminals color and looks best if your terminal uses a dark color scheme. This
|
||||
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
|
||||
|
||||
All built-in themes can be tested by using the `--list-themes` parameter:
|
||||
|
||||
```bash
|
||||
presenterm --list-themes
|
||||
```
|
||||
|
||||
This will run a presentation where the same content is rendered using a different theme in each slide:
|
||||
|
||||
[](https://asciinema.org/a/zeV1QloyrLkfBp6rNltvX7Lle)
|
||||
|
||||
# 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
|
||||
|
||||
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.
|
||||
This section goes through the structure of the theme files. Have a look at some of the [existing
|
||||
themes](https://github.com/mfontanini/presenterm/tree/master/themes) to have an idea of how to structure themes.
|
||||
|
||||
## Root elements
|
||||
|
||||
@ -332,8 +233,8 @@ code:
|
||||
#### Custom highlighting themes
|
||||
|
||||
Besides the built-in highlighting themes, you can drop any `.tmTheme` theme in the `themes/highlighting` directory under
|
||||
your [configuration directory](configuration.html) (e.g. `~/.config/presenterm/themes/highlighting` in Linux) and they
|
||||
will be loaded automatically when _presenterm_ starts.
|
||||
your [configuration directory](../../configuration/introduction.md) (e.g. `~/.config/presenterm/themes/highlighting` in
|
||||
Linux) and they will be loaded automatically when _presenterm_ starts.
|
||||
|
||||
## Block quotes
|
||||
|
||||
@ -344,10 +245,6 @@ block_quote:
|
||||
prefix: "▍ "
|
||||
```
|
||||
|
||||
<!-- links -->
|
||||
[builtin-themes]: https://github.com/mfontanini/presenterm/tree/master/themes
|
||||
[build-rs]: https://github.com/mfontanini/presenterm/blob/master/build.rs
|
||||
|
||||
## Mermaid
|
||||
|
||||
The [mermaid](https://mermaid.js.org/) graphs can be customized using the following parameters:
|
||||
@ -438,3 +335,4 @@ Similarly, these colors can be used in `span` tags like:
|
||||
```html
|
||||
<span style="color: palette:red">this is red</span>
|
||||
```
|
||||
|
||||
101
docs/src/features/themes/introduction.md
Normal file
101
docs/src/features/themes/introduction.md
Normal file
@ -0,0 +1,101 @@
|
||||
# Themes
|
||||
|
||||
_presenterm_ tries to be as configurable as possible, allowing users to create presentations that look exactly how they
|
||||
want them to look like. The tool ships with a set of [built-in
|
||||
themes](https://github.com/mfontanini/presenterm/tree/master/themes) but users can be created by users in their local
|
||||
setup and imported in their presentations.
|
||||
|
||||
## Setting themes
|
||||
|
||||
There's various ways of setting the theme you want in your presentation:
|
||||
|
||||
### CLI
|
||||
|
||||
Passing in the `--theme` parameter when running _presenterm_ to select one of the built-in themes.
|
||||
|
||||
### 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
|
||||
|
||||
Using a built-in theme name makes your presentation use that one regardless of what the default or what the `--theme`
|
||||
option specifies:
|
||||
|
||||
```yaml
|
||||
---
|
||||
theme:
|
||||
name: dark
|
||||
---
|
||||
```
|
||||
|
||||
#### By path
|
||||
|
||||
You can define a theme file in yaml format somewhere in your filesystem and reference it within the presentation:
|
||||
|
||||
```yaml
|
||||
---
|
||||
theme:
|
||||
path: /home/me/Documents/epic-theme.yaml
|
||||
---
|
||||
```
|
||||
|
||||
#### Overrides
|
||||
|
||||
You can partially/completely override the theme in use from within the presentation:
|
||||
|
||||
```yaml
|
||||
---
|
||||
theme:
|
||||
override:
|
||||
default:
|
||||
colors:
|
||||
foreground: "beeeff"
|
||||
---
|
||||
```
|
||||
|
||||
This lets you:
|
||||
|
||||
1. Create a unique style for your presentation without having to go through the process of taking an existing theme,
|
||||
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
|
||||
|
||||
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](https://github.com/mfontanini/presenterm/blob/master/build.rs) as a binary blob and are decoded on demand only
|
||||
when used.
|
||||
|
||||
Currently, the following themes are supported:
|
||||
|
||||
* `dark`: A dark theme.
|
||||
* `light`: A light theme.
|
||||
* `tokyonight-storm`: A theme inspired by the colors used in [toyonight](https://github.com/folke/tokyonight.nvim).
|
||||
* A set of themes based on the [catppuccin](https://github.com/catppuccin/catppuccin) color palette:
|
||||
* `catppuccin-latte`
|
||||
* `catppuccin-frappe`
|
||||
* `catppuccin-macchiato`
|
||||
* `catppuccin-mocha`
|
||||
* `terminal-dark`: A theme that uses your terminals color and looks best if your terminal uses a dark color scheme. This
|
||||
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
|
||||
|
||||
All built-in themes can be tested by using the `--list-themes` parameter:
|
||||
|
||||
```bash
|
||||
presenterm --list-themes
|
||||
```
|
||||
|
||||
This will run a presentation where the same content is rendered using a different theme in each slide:
|
||||
|
||||
[](https://asciinema.org/a/zeV1QloyrLkfBp6rNltvX7Lle)
|
||||
|
||||
# Loading custom themes
|
||||
|
||||
On startup, _presenterm_ will look into the `themes` directory under the [configuration
|
||||
directory](../../configuration/introduction.md) (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.
|
||||
@ -1,4 +1,4 @@
|
||||
# Installation
|
||||
# Installing _presenterm_
|
||||
|
||||
_presenterm_ works on Linux, macOS, and Windows and can be installed in different ways:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user