Bluesky Comments Extension

Enable Bluesky social discussions in your Quarto documents

Bluesky Comments is a Quarto shortcode extension that seamlessly integrates Bluesky post comments into your documents. This extension dynamically fetches and displays threaded conversations from Bluesky, creating an interactive bridge between your content and social discussions.

As an example, let’s use the following Bluesky post. Feel free to join the conversation by commenting on the post - your comment will appear below when you refresh the page!

Installation

You can install this extension using Quarto’s extension management system:

quarto add quarto-ext/bluesky-comments

This will install the extension under the _extensions directory of your Quarto project.

Requirements

  • Quarto version 1.5.0 or higher
  • A web browser with JavaScript enabled

Usage

To embed comments from a Bluesky post, use the bluesky-comments shortcode in your Quarto document, replacing post_url with the link to the Bluesky post that serves as the start of your comments.

{{< bluesky-comments post_url >}}

Here’s the shortcode we used in the example above:

{{< bluesky-comments https://bsky.app/profile/coatless.bsky.social/post/3lbtwdydxrk26 >}}

Alternatively, you can add your Bluesky profile handle to your document’s YAML frontmatter (or in the _quarto.yml configuration file). Then you can just use the post’s record key (the identifier at the end of the URL):

---
bluesky-comments:
  profile: coatless.bsky.social
---

{{< bluesky-comments 3lbtwdydxrk26 >}}

Durable Bluesky post links

Post record keys never change on Bluesky, but user handles may. If you change your Bluesky handle in the future (or if you link to a post by someone else and they update their handle), your comments may break.

To avoid breakage, you have a few choices:

  1. Use the full AT Protocol URL for the post. Anywhere that {{< bluesky-comments >}} takes a post URL, it also accepts an at:// atproto URI.

  2. Set your bluesky-comments.profile to the Decentralized Identifier (DID) for your profile and use only the post record key in the shortcode:

    ---
bluesky-comments:
  profile: did:plc:fgeozid7uyx2lfz3yo7zvm3b  # coatless.bsky.social
---

{{< bluesky-comments 3lbtwdydxrk26 >}}

  3. Or you can use your profile URL, knowing that if you change it in the future you may need to update your site again.

bluesky-comments will attempt to convert the post URL to an AT Protocol URI when rendering your document. If a post URL is successfully converted, you’ll find a message like the following in the output of quarto render:

[bluesky-comments] Resolved Bluesky post:
    source: https://bsky.app/profile/coatless.bsky.social/post/3lbtwdydxrk26
  resolved: at://did:plc:fgeozid7uyx2lfz3yo7zvm3b/app.bsky.feed.post/3lbtwdydxrk26

You can use this information to replace the source post URL with the resolved AT Protocol URI, or you can replace your profile handle with the DID from the resolved URI.

Configuration

How to configure Bluesky comments

The extension can be configured through your document’s YAML frontmatter or the _quarto.yml configuration file. Add configuration options under the bluesky-comments key:

---
title: "My Document"
bluesky-comments:
  profile: did:plc:fgeozid7uyx2lfz3yo7zvm3b  # coatless.bsky.social
  mute-patterns:
    - "📌"
    - "🔥"
    - "/\\bspam\\b/i"  # regex pattern
  mute-users:
    - "did:plc:1234abcd"
  filter-empty-replies: true
  n-show-init: 3
  n-show-more: 2
  n-show-depth: 3
---

Each of these options can also be set directly for a single comments section by providing the option as an inline attribute in the shortcode, e.g. {{< bluesky-comments n-show-init=3 >}}. These values take precedence over the above settings.

Available Options

mute-patterns
An array of strings or regex patterns (enclosed in /) to filter out comments containing specific text.
mute-users
An array of Bluesky DIDs to filter out comments from specific users.
filter-empty-replies
Boolean flag to filter out empty or very short replies, including bookmarking (📌) replies (default: true).
n-show-init
Number of top-level comments to show initially (default: 3).
n-show-more
Number of replies to reveal when the user clicks on the “Show more” button (default: 2).
n-show-depth
Maximum depth of replies to show initially. Additional nested replies are revealed when the user clicks on the “Show nested replies” button.
header
Whether or not to add a level-2 header above the comments. Use header="true" as a shortcut for header="Comments" (default: false).

Moderation

In addition to the mute-patterns and mute-users options, which can be set globally in _quarto.yml or in the front matter of an individual page, you can also use tools available on Bluesky to hide comments from your website without having to re-render your site for moderation changes to take effect.

To moderate unruly or disruptive commenters, navigate to your Bluesky post and find the unwanted comment(s) in the replies. Click the post menu ⋯ on the reply and select Hide reply for everyone. Hidden posts and their replies are immediately hidden for any new visitors.

Comments filtered due to moderation settings are not shown on your site or included in the reply counts, but users can still find the replies on the original thread on Bluesky.

Styling

The extension uses Bootstrap theme variables if set by default. For further customization, you can override these variables in your document’s or theme CSS. We also offer the ability to use component-specific variables to style the comments slightly different than your original website.

Using Bootstrap Variables

By default, the component inherits from Bootstrap’s theme. You can override the following variables to affect all Bootstrap-styled components:

:root {
  --bs-body-color: #333;
  --bs-link-color: #0070f3;
  --bs-border-color: #eaeaea;
}

Using Component Variables

For more targeted styling, override the component’s custom properties either in your document’s CSS or in a custom CSS file under the theme:

:root {
  --bc-text-color: #333;        /* Main text color */
  --bc-muted-text: #666;        /* Secondary text */
  --bc-link-color: #0070f3;     /* Links */
  --bc-border-color: #eaeaea;   /* Borders */
  --bc-thread-line: #e1e1e1;    /* Reply thread line color */
}

Available CSS Variables

You may specify these variables in your document’s CSS or in a custom CSS file under the theme to customize the appearance of the comments section.

Variable Purpose Default
--bc-text-color Primary text var(--bs-body-color)
--bc-muted-text Secondary text var(--bs-secondary-color)
--bc-link-color Link color var(--bs-link-color)
--bc-link-hover-color Link hover color var(--bs-link-hover-color)
--bc-avatar-bg Avatar placeholder var(--bs-secondary-bg)
--bc-avatar-size Avatar size 24px
--bc-border-color General borders var(--bs-border-color)
--bc-border-radius General border radius var(--bs-border-radius)
--bc-thread-line Reply thread lines var(--bs-border-color)
--bc-thread-line-width Reply thread line width 2px
--bc-warning-text Content warning text var(--bc-muted-fg)
--bc-warning-bg Warning background var(--bc-muted-bg)
--bc-warning-button Warning button var(--bs-primary)
--bc-muted-bg Muted background --bs-emphasis-color-rgb at 0.5% alpha
--bc-muted-fg Muted foreground --bs-emphasis-color-rgb at 65% alpha

Limitations

  • Only works in HTML output formats with JavaScript enabled
  • Subject to Bluesky’s API rate limits and availability

Acknowledgements

This extension builds upon the innovative work of: