Getting started • quartodon

Introduction

This vignette explains how quartodon works. It does this as a Mastodon thread itself. That means that you can take the source code of this vignette (e.g. from this GitLab URL) and directly toot it as a thread. Note that by default, the text preceding the first toot separator (-----) is not included in the thread (i.e., this paragraph). That separator is rendered to a horizontal line in HTML, so everything up to the first horizontal line will be ignored by {quartodon} when extracting toots from this vignette.

We have some room here, therefore, to show how you can obtain the source code of this vignette and extract and preview the toots from it yourself. Normally, you will probably use the RStudio plugin - that allows you to preview or toot the thread with one click, as explained below in the “thread bits”.

For now, first let’s download the raw source of this vignette:

vignetteText <-
  readLines(
    paste0(
      "https://gitlab.com/r-packages/quartodon/-/raw/",
      "main/vignettes/quartodon.Rmd?inline=false"
    ),
    encoding = "UTF-8"
  );

Then, we run a convenience function to extract the toots:

vignetteToots <-
  quartodon::split_to_toots(
    vignetteText
  );

You will usually want to append a thread counter:

vignetteToots <-
  quartodon::append_thread_counter(
    vignetteToots
  );

And then we prepare this thread by locating the image files, checking the toot lengths, and performing some checks:

vignetteToots <-
  quartodon::prep_and_check_toot_df(
    vignetteToots
  );

Finally, we could toot the thread using quartodon::post_thread_from_df(), or preview the toots that would the posted but for now, we can preview the toots with:

htmlPreview <-
  quartodon::preview_toot_df(
    vignetteToots
  );

That command should open an HTML file with the preview in the viewer. It also returns the filename where that HTML is stored in case you want to use it again (you can also specify your own filename using argument filename).

For example, this is the third toot from the thread (note that the code is immediately followed by the toot preview, ending with the character count followed by a horizontal line):

quartodon::preview_toot_df(
  vignetteToots,
  select = 3,
  embed=TRUE
);

The basic use of {quartodon} is very simple.

1️⃣ You set up your credentiasl with {rtoot} in an environment variable 🔐

2️⃣ You structure your blog post as a thread of toots 🧵🐘

3️⃣ You preview the toot thread and double check everything ✅✅

4️⃣ You post your thread, et voila 👌

The first post will be posted as “public” 🌏

The other posts will be replies to each other, and will be posted as “unlisted” 🔓

🧵3/10

✅ [nchar=414, no image]

Normally, these are the commands executed by the RStudio Addin commands “Extract and preview all toots” and “Extract and post all toots”. The last of these needs the rtoot token to be stored in an environment variable, either with the default name (RTOOT_DEFAULT_TOKEN), or another name stored in option quartodon_tokenname.

If you do want to run them from the console, you can run all four functions with the convenience function quartodon::get_prep_check_toots(). This will show the preview and return the toot_df that you can then pass to quartodon::post_thread_from_df() (or again to quartodon::post_thread_from_df()):

toot_df <-
  quartodon::vignetteText(
    vignetteToots
  );

That’s pretty much it. The rest of this vignette is an introductory toot thread about {quartodon} - the one used in the examples above, as well as the examples in the package’s manual.

Thread example

Note that I’m cheating a little bit because of CRAN’s restriction on vignette file sizes. I’ve therefore removed all GIF images from this example, only including two screenshots from {quartodon} in action. To see the full thread, check the Quarto blog post at https://gjyp.nl/posts/2023-01-converting-a-quarto-blog-post-to-a-mastodon-thread-and-posting-it.html. You can check the source code for that file at https://gitlab.com/matherion/personal-website/-/blob/master/posts/2023-01-converting-a-quarto-blog-post-to-a-mastodon-thread-and-posting-it.qmd.

This thread explains the {quartodon} R 📦 (see https://quartodon.opens.science).

The #rstats quartodon 📦 allows you to post a Mastodon thread from a plain text file (e.g., a blog post from a Quarto, {blogdown}, or {distill} website, another Quarto or R Markdown file, or just a plain text file).

This effectively allows you to post blog posts to Mastodon in a thread of toots 📑➡️🪄➡️🐘🐘🐘

The {quartodon} package comes with an RStudio addin with two commands

🚀 “Extract and preview all toots”

🚀 “Extract and post all toots”

These take the currently active document, extract all toots, add thread counters, and do some preparation and checking (toot lengths, image sizes, and alt texts) 🔍🧐

When previewing, the thread will be shown in the viewer with character counts and showing any errors 🪟

When posting, the thread will be posted to Mastodon 📬

The basic use of {quartodon} is very simple.

1️⃣ You set up your credentiasl with {rtoot} in an environment variable 🔐

2️⃣ You structure your blog post as a thread of toots 🧵🐘

3️⃣ You preview the toot thread and double check everything ✅✅

4️⃣ You post your thread, et voila 👌

The first post will be posted as “public” 🌏

The other posts will be replies to each other, and will be posted as “unlisted” 🔓

Some details about how it works (this describes the default settings, most are customizable):

🤖 Basics 💫

👉 The text is separated into toots by looking for lines containing only “-----” (five dashes).

👉 The first fragment (before the first five dashes) is ignored, allowing you to add stuff to your post that won’t be part of the toot thread.

👉 It automatically adds thread counters to the end of every toot, like this one 👇

🤖 Images 💫

👉 It checks whether images can be found, and I didn’t implement a check for URLs yet, so images have to be local for now.

👉 Image alt texts are checked for minimum lenght (currently, 10 characters)

👉 For now, only one image can be included (if multiple are included, only the first one is retained

🤖 Cleaning 💫

👉 All headings will be removed (all lines starting with #)

👉 All backticks will also be removed (since Markdown uses that to display code, but Mastodon doens’t).

👉 All strings of more than three consequtive newline characters will be replaced by two newline characters

🤖 URLs 💫

👉 {quartodon} replaces all URLs with their title, which means that hyperlinks where the title (the part between the square brackets in Markdown) isn’t the URL will just disappear in the toot.

👉 Note that relative URLs will not work from Mastodon; all URLs have to start with “https?://”, because {quartodon} processes the raw .qmd, .rmd, or .md file, before {Quarto} (or rmarkdown or knitr) did any replacement work.

🤖 Toot character counts 💫

👉 When counting toot lengths, {quartodon} counts all URLs as 23 characters, conform the Mastodon defaults.

👉 When counting toot lengths, it also corrects usernames, stripping the instance information (i.e., the last @ and everything following it (see https://docs.joinmastodon.org/user/posting/).

You can find the {quartodon} documentation at https://quartodon.opens.science

The vignette from which this Mastodon thread was extracted and posted is located at https://quartodon.opens.science/articles/quartodon.html

If you would like to check out the GitLab repo with the source code, check https://gitlab.com/r-packages/quartodon

Finally, you can check out the Quarto blog post with the same information at https://gjyp.nl/posts/2023-01-converting-a-quarto-blog-post-to-a-mastodon-thread-and-posting-it.html

For now - have fun!

These are the basics. Of course, this is the first version of the package: who knows what we can add in the future? 🚀

This package was fun to create, and will hopefully be useful. Hopefully many others can use this to let Quarto (or other) blog posts do double duty as threads of toots posted to Mastodon 🐘

At the same time I’m not sure how much time I’ll have to extend and maintain this, so if this seems like a fun project to you, please drop a line!