docs: restructure docs mdbook

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
 

docs/src/SUMMARY.md

@@ -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
 

docs/src/configuration/introduction.md

@@ -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
+```

docs/src/configuration/options.md

@@ -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 
+`![width:50%](path.png)` you would need to set:
+
+```yaml
+---
+options:
+  image_attributes_prefix: ""
+---
+
+![width:50%](path.png)
+```
+
+## auto_render_languages
+
+This option allows indicating a list of languages for which the `+render` attribute can be omitted in their code 
+snippets and will be implicitly considered to be set. This can be used for languages like `mermaid` so that graphs are 
+always automatically rendered without the need to specify `+render` everywhere.
+
+```yaml
+---
+options:
+  auto_render_languages:
+    - mermaid
+---
+```
+