docs: add docs for 0.15.0

docs/src/SUMMARY.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/configuration/introduction.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/options.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/settings.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/features/code/d2.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/execution.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.
 

docs/src/features/code/highlighting.md

@@ -65,8 +65,6 @@ Code highlighting is supported for the following languages:
 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 

docs/src/features/code/mermaid.md

@@ -38,8 +38,8 @@ cause the image to become blurry.
 
 ## Theme
 
-The theme of the rendered mermaid diagrams can be changed through the following 
-[theme](../themes/introduction.md#mermaid) parameters:
+The theme of the rendered mermaid diagrams can be changed through the following [theme](../themes/introduction.md) 
+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.

docs/src/features/commands.md

@@ -86,6 +86,34 @@ bullet point to appear only after you move to the next slide:
 * all at once
 ```
 
+## Number of lines in between list items
+
+The `list_item_newlines` option lets you configure the number of new lines in between list items in the remainder of a 
+slide. This can be helpful to "unpack" a list that only has a few entries and you want it to take up more space in a 
+slide. This can also be configured for all lists via the [`options.list_item_newlines` 
+option](../configuration/options.md#list_item_newlines).
+
+```markdown
+<!-- list_item_newlines: 2 -->
+
+* this
+* is
+* more
+* spaced
+```
+
+## Including external markdown files
+
+By using the `include` command you can include the contents of an external markdown file as if it was part of the 
+original presentation file:
+
+```markdown
+<!-- include: foo.md -->
+```
+
+Any files referenced by an included file will have their paths relative to that path. e.g. if you include `foo/bar.md` 
+and that file contains an image `tar.png`, that image will be looked up in `foo/tar.png`.
+
 ## 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:

src/presentation/builder/snippet.rs

@@ -469,6 +469,17 @@ echo hi
         assert_eq!(lines, expected);
     }
 
+    #[test]
+    fn validate() {
+        let input = "
+```bash +validate
+echo hi
+```";
+        let lines = Test::new(input).render().rows(4).columns(19).run_async_renders(false).into_lines();
+        let expected = &["                   ", "echo hi            ", "                   ", "                   "];
+        assert_eq!(lines, expected);
+    }
+
     #[test]
     fn exec_disabled() {
         let input = "