# Chatterbox Plugin for Obsidian
Chatterbox is an Obsidian plugin for rendering dialogues and conversations in the style of
messaging apps.
## Usage
Chatterbox conversations are written in code blocks with `chatterbox` as the block's language.
Below is an example conversation containing the major Chatterbox entry types.
The rest of this section describes each entry type in detail.
###### Input
````
```chatterbox
# This is an example conversation between Alice, Bob, and Carol. They are trying to decide on their weekend plans.
Alice | 12:00 pm > Hi everyone. What do you want to do this weekend?
Bob | 12:01 pm < How about we go watch a movie?
Carol | 12:02 pm < I'm in as long as I pick the movie!!!
Alice | 12:03 pm >@ 🙄
Alice | 12:03 pm >! Fine! What are we watching?
...
#() A few days later
Bob | 7:33 pm < I'm leaving the house now. Anyone need a ride?
```
````
###### Output
### Basic Entry Types
Below are the entry types supported by Chatterbox.
Any line that doesn't match one of these entry types is ignored.
All entry types that support custom text content allow you to use
[character references](https://developer.mozilla.org/en-US/docs/Glossary/Character_reference)
for encoding special characters in the supplied text.
#### Messages
Messages are the primary entry type and each has an **author**, a **direction** (_left_, _right_,
or _center_), and some text **content**.
The message direction is specified using either `>` for right, `<` for left, or `^` for center.
For example:
###### Input
````
```chatterbox
Alice > This is a message from Alice in the right direction.
Bob < This is a message from Bob in the left direction.
Carol ^ This is a message from Carol in the center.
```
````
###### Output
Optionally, messages can include some **subtext**.
You would usually place the send time of the message here.
You can add subtext to a message by adding a vertical bar `|` followed by the subtext content
between the author and the message direction marker.
For example:
###### Input
````
```chatterbox
Alice | 12:00 pm > Hi Bob! What are you doing today?
Bob | 12:01 pm < Hi Alice! Just visiting th family.
```
````
###### Output
> [!NOTE]
> To use a vertical bar as part of the author's name, you can escape it as `|`.
> Similarly, you can escape the message direction markers using `>` for `>`, `<` for `<`,
> and `^` for `^`.
> Alternatively, you can use these characters as part of the [`authorFull`]() config property.
By default, each message will display the author's name.
Sometimes, we want to hide the author's name (e.g. when displaying consecutive messages from the
same author).
We can do this either using the `!` modifier or by omitting the name author's name altogether.
For example:
###### Input
````
```chatterbox
Alice > This is the first message from Alice with her name showing.
Alice >! This is the second message from Alice without her name showing.
> This is a message from an anonymous author.
Bob < This is the first message from Bob without his name showing.
```
````
###### Output
> [!IMPORTANT]
>
> Avoid omitting the author's name if you would like to apply their
[author-specific configuration](#authors) to the message entry.
> Use the `!` modifier instead.
>
> Messages that have no author specified are considered to come from an _anonymous author_ which is
> a completely separate author altogether and can have their own author-specific configuration.
Finally, we can also render the content of a message entry as Markdown by using the `@` modifier.
For example:
###### Input
````
```chatterbox
Alice > This is some **Markdown content**
rendered as `plain text`.
Alice >@ This is some **Markdown content**
rendered as `Markdown`.
```
````
###### Output
> [!WARNING]
>
> Both the `!` and the `@` modifiers should come after the direction marker (`>`, `<`, or `^`)
> **WITHOUT** any spaces in between.
#### Comments
Comments allow you to interleave text commentary between messages.
They can be created by writing `#` at the beginning of a line followed by the comment content.
For example:
###### Input
````
```chatterbox
Alice > This is a message from Alice.
# This is a comment entry.
Bob < This is a message from Bob after a comment.
```
````
###### Output
#### Capsules
Capsules are special types of comments that are enclosed in a capsule.
They're usually used to demarcate a group of messages that occur in the same time frame.
They can be created by adding a `()` modifier to the comment marker `#` at the beginning of a line followed by the capsule content.
For example:
###### Input
````
```chatterbox
#() Yesterday
Alice > Do you want to meet today?
Bob < How about tomorrow morning? Coffee?
Alice > Sure thing!
#() Today
Bob < I'm heading to Starbucks.
Alice > I'll see you there.
```
````
###### Output
#### Delimiters
Delimiters can be used to show a break or a skip in a conversation.
You can add a delimiter by writing `...` on it's own line.
For example:
###### Input
````
```chatterbox
Alice > This is a message from Alice.
...
... This is not a valid delimiter line and will be ignored.
Bob < This is a message from Bob after a delimiter.
```
````
###### Output
### Multi-line Entries
Message, comment, and capsule entries can also be written as multi-line blocks by repeating their
respective entry markers three or more times to start the block, and using the **same** number of
markers excluding any modifiers on a **separate** line with no other content to close it.
For example:
###### Input
````
```chatterbox
Alice >>> This is a
multiline message
from
Alice.
>>>
Bob <<<<<@ This is a multiline
**Markdown message**
from Bob.
<<<<<
### This is a
multiline
comment.
###
####() This is a
multiline
capsule.
####
```
````
###### Output
#### Markdown Blocks
In addition to the other multi-line entries, Chatterbox provides a Markdown block entry type which
enables you to embed
[Obsidian Flavored Markdown](https://help.obsidian.md/obsidian-flavored-markdown) content within a
conversation.
This means anything you can do inside an Obsidian note should work inside a Chatterbox Markdown
block as well.
This can be useful to replicate certain scenarios such as conversations with an LLM.
You can insert Markdown blocks between two lines containing 3 or more `@` characters.
Like the other multi-line entries, the closing line should contain the same number of `@` characters
as the start of the block on a separate line with no other content.
For example:
###### Input
````
```chatterbox
> Can you list Maxwell's equations in differential form?
@@@
Sure — Maxwell’s equations in **differential form** (SI units), using fields $E$ (electric field), $B$ (magnetic flux density), $\rho$ (charge density), and $J$ (current density):
1. **Gauss’s law (electric):**
$$
\nabla \cdot \mathbf{E}=\frac{\rho}{\varepsilon_0}
$$
2. **Gauss’s law (magnetism):**
$$
\nabla \cdot \mathbf{B}=0
$$
3. **Faraday’s law of induction:**
$$
\nabla \times \mathbf{E}=-\frac{\partial \mathbf{B}}{\partial t}
$$
4. **Ampère–Maxwell law:**
$$
\nabla \times \mathbf{B}=\mu_0 \mathbf{J}+\mu_0 \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t}
$$
@@@
> Thanks!
```
````
###### Output
> [!NOTE]
>
> The above example was an actual conversation with ChatGPT with it's exact output copied and
> pasted.
> It has been slightly edited; most notably, the LaTeX math blocks were changed to use `$$`
> instead of `[` and `]` so that they render properly in Obsidian.
## Configuration
Each Chatterbox code block can be configured using a [YAML](https://yaml.org/) frontmatter block at
the very beginning.
Among other things, you can configure which rendering mode to use and customize the appearance of
message entries for specific authors.
For example:
###### Input
````
```chatterbox
---
mode: simple
authors:
a:
authorFull: "Alice Archer"
authorColor: "#c00e60"
bgColor: "#c00e6020"
subtextColor: yellow
b:
authorFull: "Bob Baker"
authorColor: teal
---
a | 12:00 pm > Hi, Bob!
b | 12:01 pm < Hi, Alice! Nice colors you have there!
a | 12:02 pm > Thanks!
```
````
###### Output
Below is a list of all available configuration options.
### **`authors`**
You can set author-specific configuration options that can influence how their associated message
entries are rendered.
The `authors` object uses an author's name as a key (**AFTER** unescaping/decoding any
[character references](https://developer.mozilla.org/en-US/docs/Glossary/Character_reference)) and
an author-specific configuration object as a value.
You can customize the anonymous author using `""` as the author key.
This includes giving the anonymous author a name using the `authorFull` property.
Below are the possible options that can be set
##### **`authorFull`**
Replaces the author's name with a full or alternate name in their associated message entries.
This makes writing long author names more convenient by using a smaller alias throughout a
conversation.
For example, instead of writing:
````
```chatterbox
Frodo Baggins > You're late.
Gandalf the Grey < A Wizard is never late, Frodo Baggins, nor is he early.
Gandalf the Grey You're late.
g < A Wizard is never late, Frodo Baggins, nor is he early.
g Hi everyone. What do you want to do this weekend?
Bob | 12:01 pm < How about we go watch a movie?
Carol | 12:02 pm < I'm in as long as I pick the movie!!!
Alice | 12:03 pm >@ 🙄
Alice | 12:03 pm >! Fine! What are we watching?
...
#() A few days later
Bob | 7:33 pm < I'm leaving the house now. Anyone need a ride?
```
````
The examples below display the same content rendered in the different available modes.
##### `"bubble"`
##### `"simple"`
## Plugin Settings
> [!NOTE]
> You may need to restart the Chatterbox plugin or close and reopen notes containing a Chatterbox
> block for changes to take effect.
#### Default configuration
If you have some configuration options that you use frequently, you can place them in the text area
provided for this option.
These will be applied automatically to all Chatterbox blocks and can be overwritten in the
configuration of each individual block.
## Styling
Chatterbox was designed to be easily customizable through CSS snippets.
First, you can provide custom CSS classes to a Chatterbox block using the `classes` config option.
For example,
````
```chatterbox
---
classes: "my-class"
---
...
```
````
or
````
```chatterbox
---
classes:
- "my-class-1"
- "my-class-2"
- "my-class-3"
---
...
```
````
You can then refer to them in CSS as:
```css
.chatterbox.my-class {
...
}
/* or */
.chatterbox.my-class-1 {
...
}
.chatterbox.my-class-2 {
...
}
.chatterbox.my-class-3 {
...
}
```
Additionally, each message entry is provided the following
[data attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/data-*)
to allow styling messages by specific authors across all Chatterbox blocks:
- **`data-cbx-author`:** The author name of the current message.
- **`data-cbx-author-full`:** The author's full name of the current message as set using the
[`authorFull`](#authorfull) config option.
If `authorFull` is not specified then this will have the same value as `data-cbx-author`.
- **`data-cbx-author-order`:** The order of appearance of the author of the current message.
The anonymous author always has a value of "0" while all other authors have an integer value
starting from "1" onwards depending on the order of their appearance in a conversation.
These can be used as follows:
```css
.message-container[data-cbx-author="bilbo"] {
...
}
/* or */
.message-container[data-cbx-author-full="Bilbo Baggins"] {
...
}
/* or */
.message-container[data-cbx-author-order="1"] {
...
}
```
## License
This project is available under the MIT license. See the [LICENSE file](LICENSE) for more
information.