Text

The Text object is a mini-language for representing rich text formatting commonly used in the fediverse. For example, you can emphasize some part of the text, or include a mention to another fediverse account.

Template string tag

First of all, BotKit provides a template string tag text() to format your text. Here's how you can use it:

import { text } from "@fedify/botkit";

const yourText = text`Your text goes here!`;  

For example, if you want to publish a message with the text Hello, world! to the fediverse, you can write:

import { strong, text } from "@fedify/botkit";
import { bot } from "./bot.ts";  // A hypothetical bot object

const session = bot.getSession("https://mydomain");
await session.publish(
  text`Hello, ${strong("world")}!`
);

As you can see in the example above, you can compose other Text objects together using the template string tag. In this document, we will discuss various formatting constructs that you can use in the Text object.

Interpolation

You can put any JavaScript object inside the ${} interpolation. Those objects will be expanded or converted to a string according to their types:

Text object

If you put another Text object inside the interpolation, it will be concatenated to the parent Text object. For example:

text`Hello, ${em("world")}.`

The above code will create a text like this:

Hello, world.

There are other formatting constructs that you can use in the Text object. See the below sections for more information.

Actor object

If you put an Actor object (provided by Fedify) inside the interpolation, it will be rendered as a mention. For example:

text`Hello, ${message.actor}.`

The above code will create a text like this:

Hello, @fedify@hollo.social.

URL object

If you put a URL object inside the interpolation, it will be rendered as a link. For example:

text`Here's a link: ${new URL("https://botkit.fedify.dev/")}.`

The above code will create a text like this:

Here's a link: https://botkit.fedify.dev/.

Anything else

If you put any other JavaScript object inside the interpolation, it will be converted to a string—it's the same as calling String() on the object. For example:

text`The number is ${42}.`

The above code will create a text like this:

The number is 42.

If an interpolated string has line breaks, they will be preserved in the text. For example:

text`Here's a multiline text:

${"First line.\nSecond line."}`

The above code will create a text like this:

Here's a multiline text:

First line.
Second line.

NOTE

Even if you put an HTML string inside the interpolation, it will be escaped automatically:

text`The following HTML will be escaped: ${"<strong>bold</strong>"}.`

The above code will create a text like this:

The following HTML will be escaped: <strong>bold</strong>.

Only way to format the text is to use the formatting constructs described in the following sections.

Paragraphs

You can create a paragraph by simply writing a text. If you want to create multiple paragraphs, you can split them with two or more consecutive line breaks. For example:

text`This is the first paragraph.

This is the second paragraph.\n\nThis is the last paragraph.`

The above code will create three paragraphs like this:

This is the first paragraph.

This is the second paragraph.

This is the last paragraph.

Paragraphs are separated by the <p> HTML element.

Hard line breaks

If you want to insert a hard line break, put a single line break (\n) between the lines. For example:

text`This is the first line of the first paragraph.
This is the second line of the first paragraph.

This is the second paragraph.`

The above code will create two paragraphs like this:

This is the first line of the first paragraph.
This is the second line of the first paragraph.

This is the second paragraph.

It corresponds to the <br> HTML element.

Emphases

BotKit provides two kinds of emphasis: strong() emphasizes which is usually rendered as bold, and em() emphasizes which is usually rendered as italic. For example:

text`You can emphasize ${strong("this")} or ${em("this")}!`

The above code will create a text like this:

You can emphasize this or this!

You can nest the emphasis constructs:

text`You can emphasize ${strong(em("this"))}!`

The above code will create a text like this:

You can emphasize this!

Links

You can make a link to a URL. For example:

text`Here's a link: ${link("https://fedify.dev/")}.`

The above code will create a text like this:

Here's a link: https://fedify.dev/.

You can customize the label of the link if you provide two arguments:

text`Here's a link: ${link("Fedify", "https://fedify.dev/")}.`

The above code will create a text like this:

Here's a link: Fedify.

The label can have other formatting constructs:

text`Here's a link: ${link(em("Fedify"), "https://fedify.dev/")}.`

The above code will create a text like this:

Here's a link: Fedify.

Mentions

You can mention another fediverse account by using the mention() function. For example:

text`Hello, ${mention("@fedify@hollo.social")}!`

The above code will create a text like this:

Hello, @fedify@hollo.social!

Or you can mention an account by its actor URI:

text`Hello, ${mention(new URL("https://hollo.social/@fedify"))}!`

The result is equivalent to the previous example:

Hello, @fedify@hollo.social!

You can customize the label of the mention:

text`Hello, ${mention("Fedify", new URL("https://hollo.social/@fedify"))}!`

The above code will create a text like this:

Hello, Fedify!

NOTE

The mention() construct does not only format the text but also notifies the mentioned account. The mentioned account will receive a notification about the mention. If you want to just link to the account without notifying, use the link() construct instead.

Code

You can include a code in the text using the code() function, which is usually rendered as monospaced font. For example:

text`Here's a code: ${code("console.log('Hello, world!')")}.`

The above code will create a text like this:

Here's a code: console.log('Hello, world!').

CAUTION

It is not a code block, but an inline code.