chore: prepare for 0.15.0 changes (#686)

Author: mfontanini

CHANGELOG.md

@@ -1,3 +1,67 @@
+# v0.15.0 - 2025-07-13
+
+## Breaking changes
+
+* The behavior for "jump next fast" and "jump previous fast" keybindings (defaults to `n` and `p`) now jumps straight from one slide to the next/previous one ignoring pauses. Before this used to "reveal" all pauses when jumping forward before going to the next slide. This behavior was weird and unintuitive so now fast jumps go straight into the next/previous slides. The action of "showing all pauses on the current slide" can now be done by pressing `s` ([#678](https://github.com/mfontanini/presenterm/issues/678)).
+
+## New features
+
+* Allow specifying where a [snippet's execution output will go](https://mfontanini.github.io/presenterm/features/code/execution.html#output-placing) ([#658](https://github.com/mfontanini/presenterm/issues/658)).
+* Add `include` comment command to [import markdown files](https://mfontanini.github.io/presenterm/features/commands.html#including-external-markdown-files) ([#651](https://github.com/mfontanini/presenterm/issues/651)) ([#683](https://github.com/mfontanini/presenterm/issues/683)).
+* Allow [validating snippets without explicitly executing them](https://mfontanini.github.io/presenterm/features/code/execution.html#validating-snippets) by using `--validate-snippets` switch ([#645](https://github.com/mfontanini/presenterm/issues/645)) ([#637](https://github.com/mfontanini/presenterm/issues/637)).
+* Support iterm2 image protocol when running in tmux ([#661](https://github.com/mfontanini/presenterm/issues/661)).
+* Add support for [d2 diagrams](https://mfontanini.github.io/presenterm/features/code/d2.html) ([#657](https://github.com/mfontanini/presenterm/issues/657)).
+* Errors encountered when parsing markdown now always display the file, line, and column where the error was found, as well as the markdown line that caused the error ([#674](https://github.com/mfontanini/presenterm/issues/674)) ([#653](https://github.com/mfontanini/presenterm/issues/653)) ([#684](https://github.com/mfontanini/presenterm/issues/684)) ([#685](https://github.com/mfontanini/presenterm/issues/685)).
+* Superscript via `^this^` and `<sup>this</sup>` syntaxes is supported when using the kitty terminal. For other terminals we try to use unicode half block characters which cover a portion of the ASCII charset. ([#606](https://github.com/mfontanini/presenterm/issues/606))([#617](https://github.com/mfontanini/presenterm/issues/617) ) ([#665](https://github.com/mfontanini/presenterm/issues/665)).
+* Allow [alternative snippet executors](https://mfontanini.github.io/presenterm/features/code/execution.html#alternative-executors) for languages that support execution. This allows, for example, runnig rust code via `rust-script` or python code via `pytest` ([#614](https://github.com/mfontanini/presenterm/issues/614)).
+* Allow using env var `PRESENTERM_CONFIG_FILE` to point to the config file ([#663](https://github.com/mfontanini/presenterm/issues/663)) - thanks @Silver-Golden.
+* Set background color via OSC 11 to avoid having a colored edge around the presentation ([#623](https://github.com/mfontanini/presenterm/issues/623)) ([#624](https://github.com/mfontanini/presenterm/issues/624)) ([#627](https://github.com/mfontanini/presenterm/issues/627)).
+* Add support for markdown footnotes ([#616](https://github.com/mfontanini/presenterm/issues/616)).
+* Runtime errors are now centered rather than being left aligned with some fixed margin ([#638](https://github.com/mfontanini/presenterm/issues/638)).
+* Allow [configuring number of newlines](https://mfontanini.github.io/presenterm/features/commands.html#number-of-lines-in-between-list-items) in between list items ([#628](https://github.com/mfontanini/presenterm/issues/628)).
+* Allow 3 digit hex colors ([#609](https://github.com/mfontanini/presenterm/issues/609)) - thanks @peterc-s.
+* Allow [configuring font](https://mfontanini.github.io/presenterm/configuration/settings.html#pdf-font) used in PDF export ([#608](https://github.com/mfontanini/presenterm/issues/608)).
+* Added `uv` as an alternative executor for python code ([#662](https://github.com/mfontanini/presenterm/issues/662)) - thanks @JanNeuendorf.
+* Allow multiline slide titles ([#679](https://github.com/mfontanini/presenterm/issues/679)).
+* Add support for multiline slide titles ([#682](https://github.com/mfontanini/presenterm/issues/682)) - thanks @barr-israel.
+* Add support for multiline subtitle ([#680](https://github.com/mfontanini/presenterm/issues/680)) - thanks @barr-israel.
+* Add support for syntax highlighting and execution for F# ([#650](https://github.com/mfontanini/presenterm/issues/650)) - thanks @mnebes.
+* Use text style/colors in rust-script errors ([#644](https://github.com/mfontanini/presenterm/issues/644)).
+* Added `rust-script-pedantic` alternative executor for rust ([#640](https://github.com/mfontanini/presenterm/issues/640)).
+
+## Fixes
+
+* Consider rect start row when capping max terminal rows ([#656](https://github.com/mfontanini/presenterm/issues/656)).
+* Skip speaker notes slide on `skip_slide` ([#625](https://github.com/mfontanini/presenterm/issues/625)).
+* Don't loop on 0 bytes read when querying capabilities ([#620](https://github.com/mfontanini/presenterm/issues/620)).
+* Make code snippet language specifiers case insensitive ([#613](https://github.com/mfontanini/presenterm/issues/613)) - thanks @peterc-s.
+* Bump dependencies ([#681](https://github.com/mfontanini/presenterm/issues/681)) - thanks @barr-israel.
+
+## Chore
+
+* Refactored code to make it more easily testeable, and added lots of tests to ensure markdown is rendered as expected. This will hopefully reduce the number of errors found after each release ([#660](https://github.com/mfontanini/presenterm/issues/660)) ([#659](https://github.com/mfontanini/presenterm/issues/659)) ([#655](https://github.com/mfontanini/presenterm/issues/655)) ([#647](https://github.com/mfontanini/presenterm/issues/647)).
+* Bump rust version to 1.82 ([#611](https://github.com/mfontanini/presenterm/issues/611)).
+* Perform better validation around matching HTML tags ([#668](https://github.com/mfontanini/presenterm/issues/668)).
+* Don't run nightly job if the git hash hasn't changed ([#667](https://github.com/mfontanini/presenterm/issues/667)) ([#675](https://github.com/mfontanini/presenterm/issues/675)) ([#669](https://github.com/mfontanini/presenterm/issues/669)).
+* Display an error when using http(s) urls in image tags ([#666](https://github.com/mfontanini/presenterm/issues/666)).
+* Update Catppuccin themes to use palettes ([#672](https://github.com/mfontanini/presenterm/issues/672)) - thanks @jmcharter.
+
+## Docs
+
+* Add custom introduction slides example ([#633](https://github.com/mfontanini/presenterm/issues/633)).
+* Add mention of `winget` ([#621](https://github.com/mfontanini/presenterm/issues/621)) - thanks @DeveloperPaul123.
+* Fix incorrect note callout ([#610](https://github.com/mfontanini/presenterm/issues/610)) - thanks @Sacquer.
+* Add a note to export pdf using `uv` ([#646](https://github.com/mfontanini/presenterm/issues/646)) - thanks @PitiBouchon.
+* Clarify why no remote urls work with images ([#664](https://github.com/mfontanini/presenterm/issues/664)) - thanks @ryuheechul.
+
+## ❤️ Sponsors
+
+Thanks to the following users who supported _presenterm_ via a [github sponsorship](https://github.com/sponsors/mfontanini) in this release:
+
+* [@0atman](https://github.com/0atman)
+* [@orhun](https://github.com/orhun)
+* [@gwpl](https://github.com/gwpl)
+
 # v0.14.0 - 2025-05-17
 
 ## New features

Cargo.lock

@@ -4,7 +4,7 @@ authors = ["Matias Fontanini"]
 description = "A terminal slideshow presentation tool"
 repository = "https://github.com/mfontanini/presenterm"
 license = "BSD-2-Clause"
-version = "0.14.0"
+version = "0.15.0"
 edition = "2021"
 
 [dependencies]

Cargo.toml

@@ -30,7 +30,7 @@ Visit the [documentation][docs-introduction] to get started.
 
 # Features
 
-* Define your presentation in a single markdown file.
+* Presentations consist of one [or more][docs-include] markdown files.
 * [Images and animated gifs][docs-images] on terminals like _kitty_, _iterm2_, and _wezterm_.
 * [Customizable 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 
@@ -40,6 +40,7 @@ Visit the [documentation][docs-introduction] to get started.
 * [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].
+* [d2 graph rendering][docs-d2].
 * [_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].
@@ -53,7 +54,7 @@ Visit the [documentation][docs-introduction] to get started.
 
 See the [introduction page][docs-introduction] to learn more.
 
-# Presenterm in action
+# presenterm in action
 
 Here are some talks and demos that feature _presenterm_:
 
@@ -73,6 +74,7 @@ Gave a talk using _presenterm_? We would love to feature it here! Open a PR or i
 [docs-font-sizes]: https://mfontanini.github.io/presenterm/features/introduction.html#font-sizes
 [docs-pauses]: https://mfontanini.github.io/presenterm/features/commands.html#pauses
 [docs-images]: https://mfontanini.github.io/presenterm/features/images.html
+[docs-include]: https://mfontanini.github.io/presenterm/features/commands.html#including-external-markdown-files
 [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
@@ -81,6 +83,7 @@ Gave a talk using _presenterm_? We would love to feature it here! Open a PR or i
 [docs-slide-transitions]: https://mfontanini.github.io/presenterm/features/slide-transitions.html
 [docs-layout]: https://mfontanini.github.io/presenterm/features/layout.html
 [docs-mermaid]: https://mfontanini.github.io/presenterm/features/code/mermaid.html
+[docs-d2]: https://mfontanini.github.io/presenterm/features/code/d2.html
 [docs-latex]: https://mfontanini.github.io/presenterm/features/code/latex.html
 [docs-exports]: https://mfontanini.github.io/presenterm/features/exports.html
 [docs-key-bindings]: https://mfontanini.github.io/presenterm/configuration/settings.html#key-bindings

README.md

@@ -13,6 +13,7 @@
         - [Execution](./features/code/execution.md)
         - [Mermaid diagrams](./features/code/mermaid.md)
         - [LaTeX and typst](./features/code/latex.md)
+        - [D2](./features/code/d2.md)
     - [Themes](./features/themes/introduction.md)
         - [Definition](./features/themes/definition.md)
     - [Exports](./features/exports.md)

docs/src/SUMMARY.md

@@ -10,7 +10,7 @@ custom themes, in the following directories:
 
 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-file` parameter or via the ``PRESENTERM_CONFIG_FILE`` environment variable.
+when running _presenterm_ via the `--config-file` parameter or the `PRESENTERM_CONFIG_FILE` environment variable.
 
 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.

docs/src/configuration/introduction.md

@@ -163,3 +163,14 @@ options:
 ---
 ```
 
+## list_item_newlines
+
+The option allows configuring the number of newlines in between list items, the default being `1`. This cam also be set 
+via the `list_item_newlines` comment command.
+
+```yaml
+---
+options:
+    list_item_newlines: 2
+---
+```

docs/src/configuration/options.md

@@ -267,6 +267,17 @@ mermaid:
   scale: 2
 ```
 
+## D2 scaling
+
+[d2](https://d2lang.com/) graphs will use the default scaling when invoking the d2 CLI. If you'd like to change this 
+use:
+
+
+```yaml
+d2:
+  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 
@@ -313,3 +324,18 @@ executed sequentially, you can use the `export.snippets` parameter:
 export:
   snippets: sequential
 ```
+
+## PDF font 
+
+The PDF export can be configured to use a specific font installed in your system. Use the following keys to do so:
+
+```yaml
+export:
+  pdf:
+    fonts:
+      normal: /usr/share/fonts/truetype/tlwg/TlwgMono.ttf
+      italic: /usr/share/fonts/truetype/tlwg/TlwgMono-Oblique.ttf
+      bold: /usr/share/fonts/truetype/tlwg/TlwgMono-Bold.ttf
+      bold_italic: /usr/share/fonts/truetype/tlwg/TlwgMono-BoldOblique.ttf
+```
+

docs/src/configuration/settings.md

@@ -0,0 +1,28 @@
+# D2
+
+[D2](https://d2lang.com/) snippets can be converted into images automatically for any snippets tagged with the `d2` 
+language and using a `+render` attribute:
+
+~~~markdown
+```d2 +render
+my_table: {
+  shape: sql_table
+  id: int {constraint: primary_key}
+  last_updated: timestamp with time zone
+}
+```
+~~~
+
+
+**This requires having [d2](https://github.com/terrastruct/d2) installed**.
+
+Similar to [mermaid diagrams support](mermaid.md), d2 diagrams:
+
+* Will take some time because of how slow the d2 tool is.
+* Can be scaled by using a `+width:<number>%` attribute in the snippet or by setting the `d2.scale` property in the 
+config file, which is passed along to the `--scale` parameter to the d2 CLI.
+
+## Theme
+
+The theme of the rendered d2 diagrams can be changed through the `d2.theme` [theme](../themes/introduction.md) 
+parameter. See the available themes in the [d2 docs](https://d2lang.com/tour/themes/).

docs/src/features/code/d2.md

@@ -30,6 +30,56 @@ code execution is supported.
 > Run code in presentations at your own risk! Especially if you're running someone else's presentation. Don't blindly 
 > enable snippet execution!
 
+### Output placing
+
+By default a snippet's output will always show up right below the snippet. However, if you wanted to show the output in 
+a different place in a slide (e.g. another column) or even in another slide you can do this by:
+
+1. Defining a snippet's identifier:
+
+~~~markdown
+```bash +exec +id:foo
+echo hellow world
+```
+~~~
+
+2. Referencing that identifier where you want the output to appear by using the `snippet_output` comment command:
+
+~~~markdown
+<!-- snippet_output: foo -->
+~~~
+
+A single snippet can be referenced multiple times in multiple slides, as long as the slide you're referencing it in 
+comes after the snippet. The snippet will only be executed once, and every `snippet_output` command will display that 
+single execution's output.
+
+### Validating snippets
+
+While you're developing your presentation you probably want to make sure the executable snippets you write in it are 
+correct and don't contain any syntax errors. While you can do this by constantly pressing `<c-e>` every time you change 
+a snippet, this is automatically done by _presenterm_ if you pass in the `--validate-snippets` flag.
+
+When you pass in this flag, _presenterm_ will:
+
+* Automatically run all `+exec`, `+exec_replace`, and `+validate` snippets as soon as your presentation starts. Note 
+that the `+validate` flag is a special one that doesn't make a snippet executable but still validates it by running it 
+during development.
+* Report an error if any of the snippets returns an exit code other than 0.
+* Re-run all snippets `+exec` and `+exec_repalce` snippets every time the presentation is reloaded.
+
+In case you expect a snippet to return an exit code other than 0, you can use the `+expect:failure` flag. This will 
+cause _presenterm_ to display an error if the snippet does not fail.
+
+For example, the following defines a snippet that's not executable but that will be validated if `--validate-snippets` 
+is passed in and will display an error if the snippet does not fail.
+
+```rust +validate +expect:failure
+fn main() {
+    let q = 42;
+    let w = q + "foo"; // oops
+}
+```
+
 ## Executing and replacing
 
 Similar to `+exec`, `+exec_replace` causes a snippet to be executable but:
@@ -43,7 +93,33 @@ This can be useful to run programs that generate some form of ASCII art that you
 
 Because of the risk involved in `+exec_replace`, where code gets automatically executed when running a presentation, 
 this requires users to explicitly opt in to it. This can be done by either passing in the `-X` command line parameter
-or setting the `snippet.exec_replace.enable` flag in your configuration file to `true`. 
+or setting the `snippet.exec_replace.enable` flag in your configuration file to `true`.
+
+## Alternative executors
+
+Some languages support alternative executors. For example, `rust` code can be ran via 
+[`rust-script`](https://rust-script.org/), which allows you to use external crates. These executors can be used by 
+specifying `:<executor-name>` after `+exec` or `+exec_replace`.
+
+For example, the following `rust` snippet will be executed using `rust-script`:
+
+~~~markdown
+```rust +exec:rust-script
+# //! ```cargo
+# //! [dependencies]
+# //! time = "0.1.25"
+# //! ```
+# // The lines above will be hidden
+fn main() {
+    println!("the time is {}", time::now().rfc822z());
+}
+```
+~~~
+
+The supported alternative executors are:
+
+* `rust-script` for `rust` snippets.
+* `pytest` and `uv` for `python` snippets.
 
 ## Code to image conversions
 
@@ -121,5 +197,5 @@ 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.md) and [mermaid](mermaid.md) docs for more information.
+See the [LaTeX and typst](latex.md), [mermaid](mermaid.md), and [d2](d2.md) docs for more information.