# Bluesky Docusaurus component

A series of 2 article(s), in reading order.

<!--
  canonical-url: https://www.avonture.be/blog/docusaurus-bluesky-share
  published:     2025-08-13
  This is a static plain-Markdown mirror generated at build time.
  Visit the canonical URL above for the fully rendered page, with images and interactive components.
-->

# Create our own Docusaurus React component and provide a "Share on Bluesky" button

> Build a custom Docusaurus React component that adds a “Share on Bluesky” button to your blog posts.

---
![Create our own Docusaurus React component and provide a "Share on Bluesky" button](/img/v2/docusaurus_bluesky.webp)

**TL;DR**

This post guides you through creating a 'Share on Bluesky' button for your
Docusaurus blog. You'll learn how to use Docusaurus's swizzle feature to
override the default blog post theme, create a custom React component for the
button, and then integrate it into your blog posts. We'll build the component
step-by-step, including the necessary CSS and SVG icon.

Nine months ago, I had enabled the feature to write comments under my articles by using **Giscus** (see [Adding a comment area](/blog/site-creation)) but only people having a GitHub account were eligible to use that feature and so, almost no one did it.

So I went nearly nine months without giving readers of this blog the opportunity to interact with me, which is a bit frustrating and prevents us from exchanging ideas and enriching each other's lives.

For a few weeks now, I've been present on [Bluesky](https://bsky.app/profile/avonture.be) and ... why not adding a *Share on Bluesky* button below each article?

This idea is neither revolutionary nor complicated so, let's play...

In this first article in a series of two, we'll see how we can create our Docusaurus React component. Before writing this article, I just didn't know how and now, yes, it's so easy.

**Quick Jump:** [See it in Action](#result) | [All Files at a Glance](#all-files-at-a-glance)

## Result

And, tadaaa 🎉🎉🎉, here is a "Share on Bluesky" button in action, below a blog post:

> Screenshot — http\://localhost/
>
> ![The Bluesky Share button](./images/share_button.webp)

That's the whole point of this article: a small custom React component, swizzled into Docusaurus's `BlogPostItem`, with nothing more exotic than a `<button>` and an SVG icon. Let's build it.

> **Information:**
>
> In a second article (see [Show Bluesky comments on Docusaurus and, too, number of likes/reposts](/blog/docusaurus-bluesky-comments)), we went further: retrieving the number of likes, reposts and comments posted on Bluesky and displaying them below our articles as a single, unified "engagement facepile".

This is what this very button looks like today, live on this blog, for a fresh article that hasn't collected any Bluesky interaction yet:

> Screenshot — http\://localhost/
>
> ![The Share button, live on the blog today](./images/share_button_live.webp)

Because I had absolutely no idea on how to start; let's ask some AI to generate a skeleton. I've asked something like "*Hello my friend, I would like to show a Bluesky share button below my article on my Docusaurus blog. Give me a skeleton; please.*"

Once generated by the AI, it's now time to read, understand and make some tests.

## We need to override how the article is rendered by Docusaurus

So I learned I have to create a file called `src/theme/BlogPostItem/index.js` and just put some content to it.

The AI gives me the content but ... hey my friend, from where comes that content? After some research, I learn it's an override of the standard `@docusaurus/theme-classic` template.

I also learn we can **extract** the original file by using the so-called **Swizzle** action.

> **Information:**
>
> In the Docusaurus terminology, Swizzle can be understood as override: we'll extract, here, a template so we can then override it.

The `src/theme/BlogPostItem/index.js` file will **customize the layout and content of individual blog posts** so, by updating that file, I can override then change how every single post of my blog will look.

Since I want to add a **Share button**; it's the perfect candidate. The AI is right.

## Extract the original file

Start a console and make sure you're in the root folder of your blog.

In your console, run `yarn docusaurus swizzle @docusaurus/theme-classic BlogPostItem`.

When prompted, select `Javascript`, then **`Eject`** and finally `YES`.

![Swizzle the BlogPostItem layout](./images/swizzle_blogpostitem.webp)

As you can see, a lot of files will be created in our Docusaurus directory's structure.

### Keep things under control

As you can see on the screen, you'll extract a lot of files. **Let's keep things under control: we just want to add a share button below our article; we don't want to do more than that.**

Look at your Docusaurus site now; go to the `src/theme/BlogPostItem` folder and see that, yes, you've now a lot of files and sub folders. Just remove every sub folders; we don't want to update them i.e. we want to keep the original ones. So next time you'll install a newer version of Docusaurus, you'll stay up to date.

Just keep the `index.js` file created by the `swizzle` command. Here is the one I just got on my current Docusaurus version:

**src/theme/BlogPostItem/index.js**

```javascript
import React from "react";
import clsx from "clsx";
import { useBlogPost } from "@docusaurus/plugin-content-blog/client";
import BlogPostItemContainer from "@theme/BlogPostItem/Container";
import BlogPostItemHeader from "@theme/BlogPostItem/Header";
import BlogPostItemContent from "@theme/BlogPostItem/Content";
import BlogPostItemFooter from "@theme/BlogPostItem/Footer";
// apply a bottom margin in list view
function useContainerClassName() {
  const { isBlogPostPage } = useBlogPost();
  return !isBlogPostPage ? "margin-bottom--xl" : undefined;
}
export default function BlogPostItem({ children, className }) {
  const containerClassName = useContainerClassName();
  return (
    <BlogPostItemContainer className={clsx(containerClassName, className)}>
      <BlogPostItemHeader />
      <BlogPostItemContent>{children}</BlogPostItemContent>
      <BlogPostItemFooter />
    </BlogPostItemContainer>
  );
}
```

## Playing and adding a stupid message to every blog post

Before proceeding, let us conduct a test: is this the correct file to modify for our need?

Let's play and add a line just after our post title. Look at the example below; I've just added a new line:

**src/theme/BlogPostItem/index.js**

```javascript
import React from "react";
import clsx from "clsx";
import { useBlogPost } from "@docusaurus/plugin-content-blog/client";
import BlogPostItemContainer from "@theme/BlogPostItem/Container";
import BlogPostItemHeader from "@theme/BlogPostItem/Header";
import BlogPostItemContent from "@theme/BlogPostItem/Content";
import BlogPostItemFooter from "@theme/BlogPostItem/Footer";
// apply a bottom margin in list view
function useContainerClassName() {
  const { isBlogPostPage } = useBlogPost();
  return !isBlogPostPage ? "margin-bottom--xl" : undefined;
}
export default function BlogPostItem({ children, className }) {
  const containerClassName = useContainerClassName();
  return (
    <BlogPostItemContainer className={clsx(containerClassName, className)}>
      <BlogPostItemHeader />
      // highlight-next-line
      {/* Just after the blog post title, we'll add a "Are you ready" text */}
      // highlight-next-line
      <strong style={{ color: "red" }}>
        Are you ready to update your BlogPostItem layout?
      </strong>
      <BlogPostItemContent>{children}</BlogPostItemContent>
      <BlogPostItemFooter />
    </BlogPostItemContainer>
  );
}
```

Save the file and refresh your page using your browser and tadaaa 🎉🎉🎉... Yes, we can see that text on each blog post.

On the image here above, we can see our stupid message:

> Screenshot — http\://localhost/
>
> ![Are you ready?](./images/are_you_ready.webp)

> **Note:**
>
> If it didn't work, please stop and restart your Docusaurus server. On my case (I'm using Docker), I just need to stop and restart my container.

So, as you can see, it's now quite easy. We can change the layout of our Docusaurus page just by manipulating the `index.js` file.

## Time to create our Bluesky Docusaurus component

We'll proceed step by step and keeping in mind a few things:

**Things to Remember**

* We should minimize our changes on the original `src/theme/BlogPostItem/index.js`; the less updates the best;

* We will create a Docusaurus component in `src/components/` to allow interactions with Bluesky (think about the evolution of the component) so, for this reason, we'll put everything (code, image, css) together and

* We will try to keep things clean and maintainable for the developer and configurable for the user.

### 1/5 The layout of our Bluesky generic component

The first file we'll create will be our `index.tsx` file i.e. our global Bluesky component.

In this article, we'll just foresee a "Share on Bluesky" button but in the second article, we'll add some more features.

This `index.tsx` will be the **entry point** of the component.

Please create the `src/components/Bluesky/index.tsx` file with this content:

**src/components/Bluesky/index.tsx**

```typescript
import BlueskyShare from "./share";
import styles from "./styles.module.css";

interface Props {
  metadata: {
    frontMatter?: {
      blueskyRecordKey?: string;
    };
  };
}

export default function Bluesky({ metadata }: Props) {
  return (
    <div className={styles.blueskyContainer}>
      <BlueskyShare metadata={metadata} />
    </div>
  );
}
```

**This is our React `<Bluesky />` component! Simple no? Right now, it's just a div containing another component called `<BlueskyShare />`**.

If you look at the code here above, we have to create two new files: `share.tsx` and `styles.module.css`.

### 2/5 Our "Share on Bluesky" button

Ok, now, we have to create a second file called `src/components/Bluesky/share.tsx` and to copy/paste this content in it:

**src/components/Bluesky/share.tsx**

```typescript
import Icon from "./bluesky.svg";
import styles from "./styles.module.css";
import Translate, { translate } from "@docusaurus/Translate";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";

// Declared locally rather than imported from useBlueskyEngagement — this file (built in the
// series' first article) stands on its own before that hook exists in the tutorial's timeline.
interface Props {
  metadata: {
    title?: string;
    permalink?: string;
    frontMatter?: {
      blueskyRecordKey?: string;
    };
  };
}

export default function BlueskyShare({ metadata }: Props) {
  const { siteConfig } = useDocusaurusContext();
  const blueskyRecordKey = metadata?.frontMatter?.blueskyRecordKey;

  if (blueskyRecordKey) return null;

  if (!metadata.title || !metadata.permalink) {
    console.debug("<BlueskyShare> Missing required properties", { metadata });
    return null;
  }

  const shareLink =
    `https://bsky.app/intent/compose?text=` +
    `${encodeURIComponent(metadata.title)}%20${siteConfig.url}${encodeURIComponent(
      metadata.permalink,
    )}`;

  return (
    <a
      href={shareLink}
      target="_blank"
      rel="noopener noreferrer"
      className={styles.blueskyButton}
      aria-label={translate({
        id: "bluesky.share.ariaLabel",
        message: "Share this post on Bluesky",
      })}
    >
      {/* alt dropped: SVGProps has no such prop — was a no-op DOM attribute even before this
          migration, and the link's own aria-label already names the icon. */}
      <Icon className={styles.blueskyLogo} />
      <Translate id="bluesky.share.label">Share on Bluesky</Translate>
    </a>
  );
}
```

As you can see, we've defined a function called `BlueskyShare` and that function ask a parameter called `metadata`.

> **Information:**
>
> Look back in the `src/components/Bluesky/index.tsx` we've just created before. We had this line: `<BlueskyShare metadata={metadata} />` so, yes, we're well passing that parameter.
>
> The `metadata` parameter is an object initialized by Docusaurus and that will contain all the front matter data from the Markdown file of the current blog post. It includes properties like title, description, date, tags, and any other custom fields you've defined in the front matter.

What does the `BlueskyShare` function? In fact, we'll just provide a button with a url like `https://bsky.app/intent/compose?text=<title>%20<url>` (where we'll inject the blog post title and url).

If you look at the code here above, we have to create another file called: `bluesky.svg`.

### 3/5 The Bluesky logo

For sure, we need the Bluesky logo somewhere.

Please create a third file called `src/components/Bluesky/bluesky.svg` and copy/paste this content in it:

**src/components/Bluesky/bluesky.svg**

```svg
<?xml version="1.0" encoding="UTF-8"?>
<svg viewBox="0 0 600 530" xmlns="http://www.w3.org/2000/svg">
  <path d="m135.72 44.03c66.496 49.921 138.02 151.14 164.28 205.46 26.262-54.316 97.782-155.54 164.28-205.46 47.98-36.021 125.72-63.892 125.72 24.795 0 17.712-10.155 148.79-16.111 170.07-20.703 73.984-96.144 92.854-163.25 81.433 117.3 19.964 147.14 86.092 82.697 152.22-122.39 125.59-175.91-31.511-189.63-71.766-2.514-7.3797-3.6904-10.832-3.7077-7.8964-0.0174-2.9357-1.1937 0.51669-3.7077 7.8964-13.714 40.255-67.233 197.36-189.63 71.766-64.444-66.128-34.605-132.26 82.697-152.22-67.108 11.421-142.55-7.4491-163.25-81.433-5.9562-21.282-16.111-152.36-16.111-170.07 0-88.687 77.742-60.816 125.72-24.795z" fill="#1185fe"/>
</svg>
```

### 4/5 And finally our CSS

And, very important, we need a CSS. Please create a fourth file called `src/components/Bluesky/styles.module.css` and copy/paste this content in it:

**src/components/Bluesky/styles.module.css**

```css
.blueskyLogo {
  width: 20px;
  height: 20px;
}

.blueskyContainer {
  margin: 2rem 0 0.5rem;
  padding: 1.1rem 1.25rem 1.4rem;
  border: 1px solid var(--ifm-color-emphasis-200);
  border-radius: 8px;
  background: var(--ifm-background-surface-color);
}

.blueskyHeadline {
  display: block;
  font-weight: 500;
  color: var(--ifm-color-content);
  margin-bottom: 0.75rem;
}

.blueskyAccountNote {
  display: block;
  margin-top: 0.6rem;
  font-size: smaller;
  color: var(--ifm-color-emphasis-600);
}

.blueskyCommentsContainer {
  border: 1px solid var(--ifm-color-emphasis-200);
  margin-top: 1rem;
  padding: 0.4rem 0.9rem;
  margin-bottom: 1.25rem;
}

.blueskyCommentContainer {
  margin-bottom: 1rem;
  background-color: var(--ifm-color-emphasis-100);
  padding: 0.8rem;
  border-radius: 6px;
  border-left: 2px solid var(--ifm-color-emphasis-300);
  color: var(--ifm-font-color-base);
}

.blueskyCommentHeader {
  display: flex;
  align-items: center;
  gap: 10px;
}

.blueskyCommentAuthorInfos {
  display: flex;
  flex-direction: column;
}

.blueskyCommentAvatar {
  width: 32px;
  height: 32px;
  border-radius: 50%;
  margin-right: 0.5rem;
}

.blueskyCommentAuthorDisplayName {
  margin: 0;
  font-weight: bold;
}

.blueskyCommentAuthorHandle {
  margin: 0;
  font-size: smaller;
  font-weight: normal;
  color: var(--ifm-color-emphasis-600);
  display: block;
}

.blueskyCommentDate {
  margin-left: auto;
  font-size: smaller;
  color: var(--ifm-color-emphasis-600);
}

.blueskyCommentText {
  margin: 0.3rem 0 0;
}

.blueskyCommentLikes::before {
  content: "❤️\a0";
}

.blueskyCommentLikes::after {
  content: " ";
}

.blueskyCommentReposts::before {
  content: "🔁\a0";
}

.blueskyCommentReposts::after {
  content: " ";
}

.blueskyCommentLink::before {
  content: "→\a0";
}

.blueskyCommentLink::after {
  content: " ";
}

.blueskyCommentLink {
  margin-right: 0.25rem;
  display: inline-flex;
  align-items: center;
  color: var(--ifm-color-emphasis-600);
  text-decoration: none;
  margin-top: 0.25rem;
}

img.blueskyCommentEmbedThumb {
  max-height: 250px;
}

.blueskyCommentImages {
  margin-top: 0.5rem;
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
}

.blueskyCommentImage {
  max-width: 100%;
  height: auto;
  border-radius: 0.25rem;
  border: 1px solid var(--ifm-color-emphasis-300);
}

.blueskyNoCommentYet {
  color: var(--ifm-color-emphasis-600);
  font-size: 1rem;
  line-height: 1.5;
  text-align: center;
  padding: 20px;
  background-color: var(--ifm-color-emphasis-100);
  border: 1px solid var(--ifm-color-emphasis-300);
  border-radius: 8px;
  margin: 20px 0;
}

.blueskyNoCommentYetCTA {
  font-weight: bold;
  color: var(--ifm-color-primary-dark);
  cursor: pointer;
  text-decoration: underline;
}

[data-theme="dark"] .blueskyNoCommentYetCTA {
  color: var(--ifm-color-primary-light);
}

.blueskyPostLikes {
  display: inline-flex;
  align-items: center;
  gap: 0.4rem;
}

.blueskyLikersAvatars {
  display: inline-flex;
  align-items: center;
  margin-left: 0.4rem;
}

.blueskyLikersAvatarLink {
  margin-left: -1rem;
  line-height: 0;
}

.blueskyLikersAvatarLink:first-child {
  margin-left: 0;
}

.blueskyLikersAvatar {
  width: 40px;
  height: 40px;
  border-radius: 50%;
  border: 2px solid var(--ifm-background-color);
  display: block;
}

.blueskyLikersAvatarMore {
  margin-left: 0.4rem;
  font-size: smaller;
  color: var(--ifm-color-emphasis-600);
}

.blueskyEngagementRow {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
}

.blueskyButton {
  align-items: center;
  background-color: var(--ifm-color-emphasis-200);
  border-radius: 6px;
  border: 1px solid var(--ifm-color-emphasis-300);
  box-shadow: none;
  color: var(--ifm-font-color-base);
  display: inline-flex;
  font-size: 0.9rem;
  font-weight: 400;
  gap: 0.4rem;
  margin-bottom: 0.8rem;
  margin-right: 0.4rem;
  padding: 0.4rem 0.9rem;
  text-decoration: none;
  transition:
    background-color 0.2s ease,
    color 0.2s ease;
}

.blueskyButton:hover {
  background-color: var(--ifm-color-primary);
  border-color: var(--ifm-color-primary);
  color: white;
}
```

### 5/5 Last thing, we need to implement our component in Docusaurus

Our Bluesky component is ready. We have created our four files.

You should have this:

```tree expanded=true showJSX=false debug=false title="src"
.
├── components/Bluesky
│   ├── bluesky.svg
│   ├── index.tsx
│   ├── share.tsx
│   └── styles.module.css
...
└── theme/BlogPostItem
    ├── index.js
```

Let's go back to what was said earlier: in order to adapt the page layout, Docusaurus uses the file `src/theme/BlogPostItem/index.js`. So it's time to inject our newly-created component in that script.

**src/theme/BlogPostItem/index.js**

```javascript
import React from "react";
import clsx from "clsx";
import { useBlogPost } from "@docusaurus/plugin-content-blog/client";
import BlogPostItemContainer from "@theme/BlogPostItem/Container";
import BlogPostItemHeader from "@theme/BlogPostItem/Header";
import BlogPostItemContent from "@theme/BlogPostItem/Content";
import BlogPostItemFooter from "@theme/BlogPostItem/Footer";

// highlight-next-line
// import our Bluesky component
// highlight-next-line
import Bluesky from "@site/src/components/Bluesky";

// apply a bottom margin in list view
function useContainerClassName() {
  const { isBlogPostPage } = useBlogPost();
  return !isBlogPostPage ? "margin-bottom--xl" : undefined;
}

export default function BlogPostItem({ children, className }) {
  // highlight-next-line
  // We need to retrieve the isBlogPostPage flag
  // highlight-next-line
  const { metadata, isBlogPostPage } = useBlogPost();
  const containerClassName = useContainerClassName();
  return (
    <BlogPostItemContainer className={clsx(containerClassName, className)}>
      <BlogPostItemHeader />
      <BlogPostItemContent>{children}</BlogPostItemContent>
      <BlogPostItemFooter />
      // highlight-next-line
      {/* Only display Bluesky components on the post page; not the blog view */}
      // highlight-next-line
      {isBlogPostPage && <Bluesky metadata={metadata} />}
    </BlogPostItemContainer>
  );
}
```

Congratulations! If you go to a page on your blog and refresh the page, you will see the Bluesky button at the bottom of the page.

> **Note:**
>
> If it didn't work, please stop and restart your Docusaurus server. On my case (I'm using Docker), I just need to stop and restart my container.

Refresh a blog post page and you'll see the same button we already teased at the top of this article, now live on your own site.

## All Files at a Glance

Here is the full set of files created in this article. Use the button below to copy them all at once, or download them as a ready-to-extract ZIP:

**Project: Bluesky share button**

> **Note:**
>
> Add these files to your existing Docusaurus site, then restart your dev server so the
> swizzled `BlogPostItem` picks up the new component.

**src/theme/BlogPostItem/index.js**

```javascript
import React from "react";
import clsx from "clsx";
import { useBlogPost } from "@docusaurus/plugin-content-blog/client";
import BlogPostItemContainer from "@theme/BlogPostItem/Container";
import BlogPostItemHeader from "@theme/BlogPostItem/Header";
import BlogPostItemContent from "@theme/BlogPostItem/Content";
import BlogPostItemFooter from "@theme/BlogPostItem/Footer";

// highlight-next-line
// import our Bluesky component
// highlight-next-line
import Bluesky from "@site/src/components/Bluesky";

// apply a bottom margin in list view
function useContainerClassName() {
  const { isBlogPostPage } = useBlogPost();
  return !isBlogPostPage ? "margin-bottom--xl" : undefined;
}

export default function BlogPostItem({ children, className }) {
  // highlight-next-line
  // We need to retrieve the isBlogPostPage flag
  // highlight-next-line
  const { metadata, isBlogPostPage } = useBlogPost();
  const containerClassName = useContainerClassName();
  return (
    <BlogPostItemContainer className={clsx(containerClassName, className)}>
      <BlogPostItemHeader />
      <BlogPostItemContent>{children}</BlogPostItemContent>
      <BlogPostItemFooter />
      // highlight-next-line
      {/* Only display Bluesky components on the post page; not the blog view */}
      // highlight-next-line
      {isBlogPostPage && <Bluesky metadata={metadata} />}
    </BlogPostItemContainer>
  );
}
```

**src/components/Bluesky/index.tsx**

```typescript
import BlueskyShare from "./share";
import styles from "./styles.module.css";

interface Props {
  metadata: {
    frontMatter?: {
      blueskyRecordKey?: string;
    };
  };
}

export default function Bluesky({ metadata }: Props) {
  return (
    <div className={styles.blueskyContainer}>
      <BlueskyShare metadata={metadata} />
    </div>
  );
}
```

**src/components/Bluesky/share.tsx**

```typescript
import Icon from "./bluesky.svg";
import styles from "./styles.module.css";
import Translate, { translate } from "@docusaurus/Translate";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";

// Declared locally rather than imported from useBlueskyEngagement — this file (built in the
// series' first article) stands on its own before that hook exists in the tutorial's timeline.
interface Props {
  metadata: {
    title?: string;
    permalink?: string;
    frontMatter?: {
      blueskyRecordKey?: string;
    };
  };
}

export default function BlueskyShare({ metadata }: Props) {
  const { siteConfig } = useDocusaurusContext();
  const blueskyRecordKey = metadata?.frontMatter?.blueskyRecordKey;

  if (blueskyRecordKey) return null;

  if (!metadata.title || !metadata.permalink) {
    console.debug("<BlueskyShare> Missing required properties", { metadata });
    return null;
  }

  const shareLink =
    `https://bsky.app/intent/compose?text=` +
    `${encodeURIComponent(metadata.title)}%20${siteConfig.url}${encodeURIComponent(
      metadata.permalink,
    )}`;

  return (
    <a
      href={shareLink}
      target="_blank"
      rel="noopener noreferrer"
      className={styles.blueskyButton}
      aria-label={translate({
        id: "bluesky.share.ariaLabel",
        message: "Share this post on Bluesky",
      })}
    >
      {/* alt dropped: SVGProps has no such prop — was a no-op DOM attribute even before this
          migration, and the link's own aria-label already names the icon. */}
      <Icon className={styles.blueskyLogo} />
      <Translate id="bluesky.share.label">Share on Bluesky</Translate>
    </a>
  );
}
```

**src/components/Bluesky/bluesky.svg**

```svg
<?xml version="1.0" encoding="UTF-8"?>
<svg viewBox="0 0 600 530" xmlns="http://www.w3.org/2000/svg">
  <path d="m135.72 44.03c66.496 49.921 138.02 151.14 164.28 205.46 26.262-54.316 97.782-155.54 164.28-205.46 47.98-36.021 125.72-63.892 125.72 24.795 0 17.712-10.155 148.79-16.111 170.07-20.703 73.984-96.144 92.854-163.25 81.433 117.3 19.964 147.14 86.092 82.697 152.22-122.39 125.59-175.91-31.511-189.63-71.766-2.514-7.3797-3.6904-10.832-3.7077-7.8964-0.0174-2.9357-1.1937 0.51669-3.7077 7.8964-13.714 40.255-67.233 197.36-189.63 71.766-64.444-66.128-34.605-132.26 82.697-152.22-67.108 11.421-142.55-7.4491-163.25-81.433-5.9562-21.282-16.111-152.36-16.111-170.07 0-88.687 77.742-60.816 125.72-24.795z" fill="#1185fe"/>
</svg>
```

**src/components/Bluesky/styles.module.css**

```css
.blueskyLogo {
  width: 20px;
  height: 20px;
}

.blueskyContainer {
  margin: 2rem 0 0.5rem;
  padding: 1.1rem 1.25rem 1.4rem;
  border: 1px solid var(--ifm-color-emphasis-200);
  border-radius: 8px;
  background: var(--ifm-background-surface-color);
}

.blueskyHeadline {
  display: block;
  font-weight: 500;
  color: var(--ifm-color-content);
  margin-bottom: 0.75rem;
}

.blueskyAccountNote {
  display: block;
  margin-top: 0.6rem;
  font-size: smaller;
  color: var(--ifm-color-emphasis-600);
}

.blueskyCommentsContainer {
  border: 1px solid var(--ifm-color-emphasis-200);
  margin-top: 1rem;
  padding: 0.4rem 0.9rem;
  margin-bottom: 1.25rem;
}

.blueskyCommentContainer {
  margin-bottom: 1rem;
  background-color: var(--ifm-color-emphasis-100);
  padding: 0.8rem;
  border-radius: 6px;
  border-left: 2px solid var(--ifm-color-emphasis-300);
  color: var(--ifm-font-color-base);
}

.blueskyCommentHeader {
  display: flex;
  align-items: center;
  gap: 10px;
}

.blueskyCommentAuthorInfos {
  display: flex;
  flex-direction: column;
}

.blueskyCommentAvatar {
  width: 32px;
  height: 32px;
  border-radius: 50%;
  margin-right: 0.5rem;
}

.blueskyCommentAuthorDisplayName {
  margin: 0;
  font-weight: bold;
}

.blueskyCommentAuthorHandle {
  margin: 0;
  font-size: smaller;
  font-weight: normal;
  color: var(--ifm-color-emphasis-600);
  display: block;
}

.blueskyCommentDate {
  margin-left: auto;
  font-size: smaller;
  color: var(--ifm-color-emphasis-600);
}

.blueskyCommentText {
  margin: 0.3rem 0 0;
}

.blueskyCommentLikes::before {
  content: "❤️\a0";
}

.blueskyCommentLikes::after {
  content: " ";
}

.blueskyCommentReposts::before {
  content: "🔁\a0";
}

.blueskyCommentReposts::after {
  content: " ";
}

.blueskyCommentLink::before {
  content: "→\a0";
}

.blueskyCommentLink::after {
  content: " ";
}

.blueskyCommentLink {
  margin-right: 0.25rem;
  display: inline-flex;
  align-items: center;
  color: var(--ifm-color-emphasis-600);
  text-decoration: none;
  margin-top: 0.25rem;
}

img.blueskyCommentEmbedThumb {
  max-height: 250px;
}

.blueskyCommentImages {
  margin-top: 0.5rem;
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
}

.blueskyCommentImage {
  max-width: 100%;
  height: auto;
  border-radius: 0.25rem;
  border: 1px solid var(--ifm-color-emphasis-300);
}

.blueskyNoCommentYet {
  color: var(--ifm-color-emphasis-600);
  font-size: 1rem;
  line-height: 1.5;
  text-align: center;
  padding: 20px;
  background-color: var(--ifm-color-emphasis-100);
  border: 1px solid var(--ifm-color-emphasis-300);
  border-radius: 8px;
  margin: 20px 0;
}

.blueskyNoCommentYetCTA {
  font-weight: bold;
  color: var(--ifm-color-primary-dark);
  cursor: pointer;
  text-decoration: underline;
}

[data-theme="dark"] .blueskyNoCommentYetCTA {
  color: var(--ifm-color-primary-light);
}

.blueskyPostLikes {
  display: inline-flex;
  align-items: center;
  gap: 0.4rem;
}

.blueskyLikersAvatars {
  display: inline-flex;
  align-items: center;
  margin-left: 0.4rem;
}

.blueskyLikersAvatarLink {
  margin-left: -1rem;
  line-height: 0;
}

.blueskyLikersAvatarLink:first-child {
  margin-left: 0;
}

.blueskyLikersAvatar {
  width: 40px;
  height: 40px;
  border-radius: 50%;
  border: 2px solid var(--ifm-background-color);
  display: block;
}

.blueskyLikersAvatarMore {
  margin-left: 0.4rem;
  font-size: smaller;
  color: var(--ifm-color-emphasis-600);
}

.blueskyEngagementRow {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
}

.blueskyButton {
  align-items: center;
  background-color: var(--ifm-color-emphasis-200);
  border-radius: 6px;
  border: 1px solid var(--ifm-color-emphasis-300);
  box-shadow: none;
  color: var(--ifm-font-color-base);
  display: inline-flex;
  font-size: 0.9rem;
  font-weight: 400;
  gap: 0.4rem;
  margin-bottom: 0.8rem;
  margin-right: 0.4rem;
  padding: 0.4rem 0.9rem;
  text-decoration: none;
  transition:
    background-color 0.2s ease,
    color 0.2s ease;
}

.blueskyButton:hover {
  background-color: var(--ifm-color-primary);
  border-color: var(--ifm-color-primary);
  color: white;
}
```

In a next article, we'll learn how to interact with Bluesky:

* Providing a button below the article to jump to the Bluesky posts so your visitors will be able to:
  * Like your article (which is always nice, isn't it?),
  * Share your article (even better) and
  * Start or participate to a discussion
* We'll also show the number of likes and reposts on the Bluesky post and
* Retrieve all comments posted on Bluesky and display them on your blog; this will undoubtedly increase your visitors' engagement.

## Final remarks - Take care about the swizzle command

You need to understand that, by swizzling (overriding) the BlogPostItem layout, you're no more *aligned* with the standard layout of Docusaurus.

**If, in a next release, new features will be added by Docusaurus; you'll not have them!** since you're no more using the default layout for your post.

Just keep that in mind and, perhaps, from time to time (after a major release f.i.), think to run the swizzle command again and restart your customization.

This is why our changes to the index.js file were kept to a minimum.


---

<!--
  canonical-url: https://www.avonture.be/blog/docusaurus-bluesky-comments
  published:     2025-08-18
  This is a static plain-Markdown mirror generated at build time.
  Visit the canonical URL above for the fully rendered page, with images and interactive components.
-->

# Show Bluesky comments on Docusaurus and, too, number of likes/reposts

> Integrate Bluesky comments, likes, and repost counts directly into your Docusaurus blog posts.

---
![Show Bluesky comments on Docusaurus and, too, number of likes/reposts](/img/v2/docusaurus_bluesky.webp)

**TL;DR**

This article is the second part of the 'Bluesky Docusaurus component' series.
It enhances the component created in the first part by adding features to
display Bluesky comments, likes, and repost counts directly on your Docusaurus
blog. To achieve this, you'll learn how to link your blog posts to Bluesky
posts using a frontmatter key, update the React component to fetch and display
this information, and configure your Docusaurus site with your Bluesky handle.

In a [previous article](/blog/docusaurus-bluesky-share), we've seen how we can, simply said, provide a "Share the article on Bluesky".

This is not really interactive right? Let's see in this article how to make the link between a Docusaurus blog post and Bluesky.

**Quick Jump:** [What You'll Get](#what-youll-get) | [All Files at a Glance](#all-files-at-a-glance)

## What You'll Get

Once wired up, every article gets a "Like, share or comment on Bluesky" button, a single **engagement facepile** merging likes, reposts and commenters into one deduplicated avatar stack, and the list of comments straight from your Bluesky post — right below the article, no separate comment system to host.

Here is that block, live on three different articles of this very blog, at three different levels of engagement:

> Screenshot — http\://localhost/
>
> ![Engagement facepile with five people involved: likes, reposts and avatars stacked](./images/engagement_facepile_many.webp)

> Screenshot — http\://localhost/
>
> ![Engagement facepile together with the comments thread it links to](./images/engagement_facepile_comments.webp)

> Screenshot — http\://localhost/
>
> ![A smaller engagement facepile: two likes, one repost](./images/engagement_facepile_repost.webp)

> **Information:**
>
> Notice there's no separate "likers" row and "commenters" row: a person who both liked **and** commented on the post shows up as a single avatar, sorted first — that's the whole point of the facepile merge described below.

**The workflow will be:**

1. You publish your article on your blog,

2. You share the article on Bluesky (by using the "Share the article" feature of course),

3. You retrieve the **Bluesky Record key** i.e. the very last part of Bluesky post URL (something like `3lun2qjuxc22r`),

4. You edit back your Docusaurus article and you add a key in your YAML front matter (the YAML block at the top of your article). The key to add is `blueskyRecordKey: xxxx` where `xxxx` is your **Bluesky Record key**.

5. You publish your updated article on your blog again.

So, from now, you've clearly made the link between your article and your Bluesky post.

**Thanks to this link, we can:**

1. Display a button "Like, share or comment on Bluesky": the visitor can then jump to your Bluesky post and like, share or comment your article,

2. Display the number of likes and reposts below your article and,

3. Display the list of comments you've received on your Bluesky post and, if none, display a *Call to action* area to encourage your reader to share their thoughts

In the previous article (see [Create our own Docusaurus React component and provide a "Share on Bluesky" button](/blog/docusaurus-bluesky-share)), we've created the `src/components/Bluesky/index.tsx` file. Please edit that file and use this new content:

## 1/6 The layout of our Bluesky generic component

Here is our new Bluesky layout for our component:

**src/components/Bluesky/index.tsx**

```typescript
import BlueskyComments from "./comments";
import BlueskyLikes from "./likes";
import BlueskyPost from "./post";
import BlueskyShare from "./share";
import styles from "./styles.module.css";
import Translate, { translate } from "@docusaurus/Translate";
import useBlueskyEngagement, { useBlueskyRecordKey } from "./useBlueskyEngagement";
import type { BlueskyMetadata, EngagedPerson } from "./useBlueskyEngagement";

function engagementHeadline({
  blueskyRecordKey,
  loading,
  unavailable,
  engaged,
}: {
  blueskyRecordKey: string | null;
  loading: boolean;
  unavailable: boolean;
  engaged: EngagedPerson[];
}): string {
  if (!blueskyRecordKey) {
    return translate({
      id: "bluesky.heading.share",
      message: "🦋 Enjoyed this article? Share it on Bluesky",
    });
  }
  if (loading || unavailable) {
    // Same neutral copy for "still fetching" and "couldn't fetch" — never claim
    // "no one reacted yet" when the truth is just "couldn't check".
    return translate({
      id: "bluesky.heading.join",
      message: "🦋 Join the conversation on Bluesky",
    });
  }
  if (engaged.length === 0) {
    return translate({
      id: "bluesky.heading.first",
      message: "🦋 Be the first to react on Bluesky",
    });
  }
  const count = engaged.length;
  // Two whole sentences rather than a spliced "person is" / "people are": French agreement
  // reaches further than the verb ("personne en parle" / "personnes en parlent").
  return count === 1
    ? translate({
        id: "bluesky.heading.talkingOne",
        message: "🦋 1 person is already talking about this on Bluesky — join them",
      })
    : translate(
        {
          id: "bluesky.heading.talkingOther",
          message:
            "🦋 {count} people are already talking about this on Bluesky — join them",
        },
        { count },
      );
}

interface Props {
  metadata: BlueskyMetadata;
}

export default function Bluesky({ metadata }: Props) {
  // The frontmatter key always wins (manual override); otherwise it's looked up
  // from the account's own Bluesky post history, matched against this article's
  // URL — see useBlueskyRecordKey for why and how.
  const { recordKey, resolving } = useBlueskyRecordKey(metadata);
  const effectiveMetadata: BlueskyMetadata = {
    ...metadata,
    frontMatter: { ...metadata.frontMatter, blueskyRecordKey: recordKey ?? undefined },
  };
  const stats = useBlueskyEngagement(effectiveMetadata);

  // Still checking whether this article was already promoted — skip the frame
  // rather than flash a "Share on Bluesky" button that may disappear a moment
  // later once a match is found.
  if (resolving) return null;

  return (
    <div className={styles.blueskyContainer}>
      <span className={styles.blueskyHeadline}>
        {engagementHeadline({
          blueskyRecordKey: recordKey,
          loading: stats.loading,
          unavailable: stats.unavailable,
          engaged: stats.engaged,
        })}
      </span>

      {/* No Bluesky post found for this article: show a share button */}
      <BlueskyShare metadata={effectiveMetadata} />

      {/* A Bluesky post was found and its data actually loaded: show engagement UI.
          Hiding BlueskyPost too when unavailable — a resolved key can point to a
          post that was since deleted, and a link straight to a 404 is worse than
          no link. */}
      {!stats.unavailable && (
        <div className={styles.blueskyEngagementRow}>
          <BlueskyPost metadata={effectiveMetadata} />
          <BlueskyLikes stats={stats} />
        </div>
      )}

      <span className={styles.blueskyAccountNote}>
        <Translate id="bluesky.accountNote">
          {
            "Requires a free Bluesky account to like, repost or comment. This block talks to Bluesky's public API directly from your browser (no cookies, no sign-in) — that means your IP address reaches Bluesky's servers just by this section loading."
          }
        </Translate>
      </span>

      <BlueskyComments metadata={effectiveMetadata} />
    </div>
  );
}
```

> **Information:**
>
> The highlighted lines are the new ones compared to the previous version of the file if you've already followed the first tutorial.

**As you can see, this time, we'll foresee four components:**

1. A Share button,

2. A Post button (to jump to your post on Bluesky),

3. A likes area (to show the number of likes and reposts of your post on Bluesky) and

4. An area for displaying comments you've on Bluesky

## 2/6 The shared data-fetching hook

Both `index.tsx` (for the headline copy) and `likes.tsx` (for the counts and the facepile) need the same Bluesky data, so instead of fetching it twice, we centralize everything in one custom hook: `useBlueskyEngagement.ts`. It resolves the `blueskyRecordKey` (from your front matter or, if you didn't set one, by matching the article's URL against your own Bluesky post history) and fetches likes, reposts and comments in a single pass.

**src/components/Bluesky/useBlueskyEngagement.ts**

```typescript
import { useState, useEffect } from "react";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import { useSourceLocaleUrls } from "@site/src/components/Blog/utils/localeUrls";

const MAX_ACTORS_PER_ENDPOINT = 20;
const FEED_CACHE_PREFIX = "bluesky-feed-cache:";
const FEED_CACHE_TTL_MS = 5 * 60 * 1000;
const MAX_FEED_PAGES = 5;
const BLOCKED_LIST_CACHE_PREFIX = "bluesky-blocked-list-cache:";
const BLOCKED_LIST_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour — list changes rarely

/** `docusaurus.config.js`'s `customFields.bluesky` — a custom field, typed `unknown` by
 * Docusaurus itself, so every reader casts against this shape. */
export interface BlueskySiteConfig {
  handle?: string;
  /**
   * AT URI of a Bluesky moderation list whose members are hidden from comments and the facepile.
   * Fetched at runtime from the public API (no auth required) and cached 1 h in sessionStorage —
   * adding a handle to the list takes effect on the next page load with no deploy needed.
   * Create a list at bsky.app → Lists, then copy its URI (at://did:plc:…/app.bsky.graph.list/…).
   */
  blockedList?: string;
  /** Compile-time override: handles blocked regardless of the Bluesky list (e.g. during deploy). */
  blockedHandles?: string[];
}

/** The subset of a blog post's `useBlogPost().metadata` every Bluesky file actually reads. */
export interface BlueskyMetadata {
  title?: string;
  permalink?: string;
  frontMatter?: {
    blueskyRecordKey?: string;
  };
}

export type EngagementAction = "liked" | "reposted" | "commented";

export interface EngagedPerson {
  did: string;
  handle: string;
  displayName: string;
  avatar?: string;
  actions: Set<EngagementAction>;
}

export interface EngagementStats {
  likes: number | null;
  reposts: number | null;
  engaged: EngagedPerson[];
  loading: boolean;
  unavailable: boolean;
}

export interface RecordKeyState {
  recordKey: string | null;
  resolving: boolean;
}

export interface BlueskyActor {
  did: string;
  handle: string;
  displayName?: string;
  avatar?: string;
}

export interface BlueskyFacetFeature {
  $type: string;
  uri?: string;
}

export interface BlueskyFacet {
  index: { byteStart: number; byteEnd: number };
  features: BlueskyFacetFeature[];
}

export interface BlueskyPostRecord {
  text: string;
  facets?: BlueskyFacet[];
}

export interface BlueskyEmbedExternal {
  $type: "app.bsky.embed.external#view";
  external: { uri: string; title: string; thumb?: string };
}

export interface BlueskyEmbedImages {
  $type: "app.bsky.embed.images#view";
  images: { fullsize: string; alt?: string }[];
}

export type BlueskyEmbed = BlueskyEmbedExternal | BlueskyEmbedImages | { $type: string };

export interface BlueskyPostView {
  uri: string;
  indexedAt: string;
  likeCount: number;
  repostCount?: number;
  author: BlueskyActor & { displayName: string };
  record: BlueskyPostRecord;
  embed?: BlueskyEmbed | null;
}

export interface BlueskyReplyNode {
  post: BlueskyPostView;
  replies?: BlueskyReplyNode[];
}

function flattenReplyAuthors(replies: BlueskyReplyNode[] | undefined): BlueskyActor[] {
  const authors: BlueskyActor[] = [];
  const walk = (arr: BlueskyReplyNode[] | undefined) => {
    if (!arr) return;
    for (const reply of arr) {
      authors.push(reply.post.author);
      walk(reply.replies);
    }
  };
  walk(replies);
  return authors;
}

function mergeEngagement(
  {
    likers = [],
    reposters = [],
    commenters = [],
  }: { likers?: BlueskyActor[]; reposters?: BlueskyActor[]; commenters?: BlueskyActor[] },
  ownerHandle: string | undefined,
  blockedHandles: Set<string> = new Set(),
): EngagedPerson[] {
  const byDid = new Map<string, EngagedPerson>();

  const record = (actor: BlueskyActor | undefined, action: EngagementAction) => {
    // Replying to your own readers isn't reader engagement — exclude the blog's own account.
    // Also exclude any handle explicitly blocked in the site config (e.g. spammers).
    if (!actor?.did || actor.handle === ownerHandle || blockedHandles.has(actor.handle))
      return;
    const entry = byDid.get(actor.did) || {
      did: actor.did,
      handle: actor.handle,
      displayName: actor.displayName || actor.handle,
      avatar: actor.avatar,
      actions: new Set<EngagementAction>(),
    };
    entry.actions.add(action);
    byDid.set(actor.did, entry);
  };

  likers.forEach((actor) => record(actor, "liked"));
  reposters.forEach((actor) => record(actor, "reposted"));
  commenters.forEach((actor) => record(actor, "commented"));

  // People engaged in more than one way surface first — they're the strongest social proof.
  return [...byDid.values()].sort((a, b) => b.actions.size - a.actions.size);
}

function normalizeUrl(url: string | null | undefined): string | null {
  if (!url) return null;
  return url.split("?")[0].replace(/\/+$/, "");
}

interface BlockedListResponse {
  items?: { subject?: { handle?: string } }[];
  cursor?: string;
}

// Fetches every handle in a Bluesky moderation list (pagination-aware) and caches
// the result in sessionStorage for 1 hour so browsing many articles doesn't re-fetch.
// Exported so BlueskyComments can share the same cache without a duplicate request.
export async function fetchBlockedList(listUri: string): Promise<Set<string>> {
  const cacheKey = BLOCKED_LIST_CACHE_PREFIX + listUri;
  try {
    const raw = sessionStorage.getItem(cacheKey);
    if (raw) {
      const { timestamp, handles } = JSON.parse(raw) as {
        timestamp: number;
        handles: string[];
      };
      if (Date.now() - timestamp <= BLOCKED_LIST_CACHE_TTL_MS) return new Set(handles);
    }
  } catch {
    /* private browsing or corrupt entry — just refetch */
  }

  const handles: string[] = [];
  let cursor: string | undefined;

  for (let page = 0; page < 10; page++) {
    const params = new URLSearchParams({ list: listUri, limit: "100" });
    if (cursor) params.set("cursor", cursor);
    const res = await fetch(
      `https://public.api.bsky.app/xrpc/app.bsky.graph.getList?${params}`,
    );
    if (!res.ok) break;
    const data = (await res.json()) as BlockedListResponse;
    for (const item of data.items ?? []) {
      if (item.subject?.handle) handles.push(item.subject.handle);
    }
    cursor = data.cursor;
    if (!cursor) break;
  }

  try {
    sessionStorage.setItem(cacheKey, JSON.stringify({ timestamp: Date.now(), handles }));
  } catch {
    /* private browsing — cache miss next time, that's fine */
  }

  return new Set(handles);
}

type FeedIndex = Record<string, string>;

function readFeedCache(handle: string): FeedIndex | null {
  try {
    const raw = sessionStorage.getItem(FEED_CACHE_PREFIX + handle);
    if (!raw) return null;
    const { timestamp, urlToRecordKey } = JSON.parse(raw) as {
      timestamp: number;
      urlToRecordKey: FeedIndex;
    };
    if (Date.now() - timestamp > FEED_CACHE_TTL_MS) return null;
    return urlToRecordKey;
  } catch {
    return null;
  }
}

function writeFeedCache(handle: string, urlToRecordKey: FeedIndex): void {
  try {
    sessionStorage.setItem(
      FEED_CACHE_PREFIX + handle,
      JSON.stringify({ timestamp: Date.now(), urlToRecordKey }),
    );
  } catch {
    // Private browsing / storage disabled — resolution still works, just uncached.
  }
}

interface AuthorFeedItem {
  post: {
    uri: string;
    record?: {
      embed?: {
        $type?: string;
        external?: { uri?: string };
      };
    };
  };
}

interface AuthorFeedResponse {
  feed?: AuthorFeedItem[];
  cursor?: string;
}

// Builds a { normalizedArticleUrl: recordKey } map from the account's own post
// history, matching on the "external" link-card embed Bluesky attaches when a
// post links out (the same card the Share button in this component produces).
// Cached per tab session so browsing several un-tagged articles doesn't re-fetch
// the whole feed each time.
async function buildFeedIndex(handle: string): Promise<FeedIndex> {
  const cached = readFeedCache(handle);
  if (cached) return cached;

  const urlToRecordKey: FeedIndex = {};
  let cursor: string | undefined;

  for (let page = 0; page < MAX_FEED_PAGES; page += 1) {
    const params = new URLSearchParams({
      actor: handle,
      limit: "100",
      filter: "posts_no_replies",
    });
    if (cursor) params.set("cursor", cursor);

    const res = await fetch(
      `https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?${params}`,
    );
    if (!res.ok) throw new Error("Failed to fetch author feed");
    const data = (await res.json()) as AuthorFeedResponse;

    for (const item of data.feed || []) {
      const embed = item.post?.record?.embed;
      const externalUri =
        embed?.$type === "app.bsky.embed.external" ? (embed.external?.uri ?? null) : null;
      const normalized = normalizeUrl(externalUri);
      if (normalized) urlToRecordKey[normalized] = item.post.uri.split("/").pop()!;
    }

    cursor = data.cursor;
    if (!cursor || !data.feed?.length) break;
  }

  writeFeedCache(handle, urlToRecordKey);
  return urlToRecordKey;
}

// Resolves the Bluesky record key for the current article. The frontmatter value
// always wins — it's the manual override needed after a slug rename, or to
// disambiguate an article re-promoted with a second post. Otherwise the key is
// looked up from the account's own post history. In a translated locale the
// article's own URL (`/fr/blog/x/`) is tried first, then the source-language one
// (`/blog/x/`): the author usually promotes only the English article, and French
// readers should join that conversation rather than see a "Share" button. A
// dedicated French post, if one exists, still wins. Never throws: any failure here
// (offline, blocked, no match found) just means no engagement UI is shown, the
// same as an article that was never promoted at all.
export function useBlueskyRecordKey(
  metadata: BlueskyMetadata | undefined,
): RecordKeyState {
  const { siteConfig } = useDocusaurusContext();
  const blueSkyConfig = siteConfig?.customFields?.bluesky as
    BlueskySiteConfig | undefined;
  const frontMatterKey = metadata?.frontMatter?.blueskyRecordKey;
  const { isDefaultLocale, sourceAbsoluteUrl } = useSourceLocaleUrls();

  // `permalink` comes from Docusaurus and already carries the locale's baseUrl
  // (`/fr/blog/x/`) — so `siteConfig.url + permalink` is correct as is and must
  // NOT be prefixed again. The source URL is the reverse: strip that baseUrl,
  // then resolve the rest against the source locale. Slugs are never translated,
  // so the remainder is the same in both locales.
  const permalink = metadata?.permalink;
  const currentUrl = permalink ? normalizeUrl(`${siteConfig.url}${permalink}`) : null;
  const sourceUrl =
    permalink && !isDefaultLocale && permalink.startsWith(siteConfig.baseUrl)
      ? normalizeUrl(sourceAbsoluteUrl(permalink.slice(siteConfig.baseUrl.length)))
      : null;

  const [state, setState] = useState<RecordKeyState>({
    recordKey: frontMatterKey || null,
    resolving: !frontMatterKey,
  });

  useEffect(() => {
    if (frontMatterKey) {
      // eslint-disable-next-line react-hooks/set-state-in-effect -- mirrors a prop change (article navigation), not derivable at render time
      setState({ recordKey: frontMatterKey, resolving: false });
      return;
    }
    if (!blueSkyConfig?.handle || !currentUrl) {
      setState({ recordKey: null, resolving: false });
      return;
    }

    let cancelled = false;

    (async () => {
      try {
        const index = await buildFeedIndex(blueSkyConfig.handle!);
        if (!cancelled)
          setState({
            recordKey: index[currentUrl] || (sourceUrl && index[sourceUrl]) || null,
            resolving: false,
          });
      } catch (e) {
        console.error("Bluesky record key lookup failed:", e);
        if (!cancelled) setState({ recordKey: null, resolving: false });
      }
    })();

    return () => {
      cancelled = true;
    };
  }, [frontMatterKey, blueSkyConfig?.handle, currentUrl, sourceUrl]);

  return state;
}

interface LikesResponse {
  likes: { actor: BlueskyActor }[];
}

interface RepostedByResponse {
  repostedBy: BlueskyActor[];
}

async function fetchActors(
  endpoint: "getLikes" | "getRepostedBy",
  uri: string,
  listKey: "likes" | "repostedBy",
): Promise<BlueskyActor[]> {
  const url = `https://public.api.bsky.app/xrpc/app.bsky.feed.${endpoint}?uri=${encodeURIComponent(
    uri,
  )}&limit=${MAX_ACTORS_PER_ENDPOINT}`;

  const res = await fetch(url);
  if (!res.ok) throw new Error(`Failed to fetch ${endpoint}`);

  const data = (await res.json()) as LikesResponse | RepostedByResponse;
  return listKey === "likes"
    ? (data as LikesResponse).likes.map(({ actor }) => actor)
    : (data as RepostedByResponse).repostedBy;
}

interface PostThreadResponse {
  thread: {
    post: { likeCount: number; repostCount: number; uri: string };
    replies?: BlueskyReplyNode[];
  };
}

// Shared by index.tsx (headline copy) and likes.tsx (counts + facepile) so the
// thread/likes/reposts fetches happen once per post, not once per consumer.
export default function useBlueskyEngagement(
  metadata: BlueskyMetadata | undefined,
): EngagementStats {
  const { siteConfig } = useDocusaurusContext();
  const blueSkyConfig = siteConfig?.customFields?.bluesky as
    BlueskySiteConfig | undefined;
  const blueskyRecordKey = metadata?.frontMatter?.blueskyRecordKey;

  const [stats, setStats] = useState<EngagementStats>({
    likes: null,
    reposts: null,
    engaged: [],
    loading: true,
    unavailable: false,
  });

  useEffect(() => {
    if (!blueskyRecordKey || !blueSkyConfig?.handle) {
      // eslint-disable-next-line react-hooks/set-state-in-effect -- resets stats when the post/config identity changes; the effect also fetches below, it's not derivable at render time
      setStats({
        likes: null,
        reposts: null,
        engaged: [],
        loading: false,
        unavailable: false,
      });
      return;
    }

    const fetchData = async () => {
      const postUri = `at://${blueSkyConfig.handle}/app.bsky.feed.post/${blueskyRecordKey}`;
      const threadUrl = `https://public.api.bsky.app/xrpc/app.bsky.feed.getPostThread?uri=${encodeURIComponent(
        postUri,
      )}&depth=5`;

      // Fetch the thread and the moderation list in parallel — neither depends on the other.
      // The list is cached 1 h in sessionStorage, so after the first load it resolves instantly.
      try {
        const [threadRes, listBlocked] = await Promise.all([
          fetch(threadUrl),
          blueSkyConfig.blockedList
            ? fetchBlockedList(blueSkyConfig.blockedList).catch(() => new Set<string>())
            : Promise.resolve(new Set<string>()),
        ]);
        const blockedHandles = new Set([
          ...(blueSkyConfig.blockedHandles ?? []),
          ...listBlocked,
        ]);

        const res = threadRes;
        if (!res.ok) throw new Error("Failed to fetch post data");

        const data = (await res.json()) as PostThreadResponse;
        const { likeCount, repostCount, uri: resolvedUri } = data.thread.post;
        const commenters = flattenReplyAuthors(data.thread.replies);

        setStats({
          likes: likeCount,
          reposts: repostCount,
          engaged: mergeEngagement({ commenters }, blueSkyConfig.handle, blockedHandles),
          loading: false,
          unavailable: false,
        });

        // resolvedUri carries the post's DID (getLikes/getRepostedBy return nothing for a handle-based URI)
        const [likers, reposters] = await Promise.all([
          likeCount > 0 ? fetchActors("getLikes", resolvedUri, "likes") : [],
          repostCount > 0 ? fetchActors("getRepostedBy", resolvedUri, "repostedBy") : [],
        ]);

        setStats((prev) => ({
          ...prev,
          engaged: mergeEngagement(
            { likers, reposters, commenters },
            blueSkyConfig.handle,
            blockedHandles,
          ),
        }));
      } catch (e) {
        // Offline, blocked by the visitor (ad-blocker, DNS filtering), or Bluesky
        // itself down — never surface this as a JS error, just mark the data as
        // unavailable so the UI doesn't claim "no one reacted yet" instead.
        console.error("Error fetching Bluesky stats:", e);
        setStats({
          likes: null,
          reposts: null,
          engaged: [],
          loading: false,
          unavailable: true,
        });
      }
    };

    fetchData();
  }, [
    blueskyRecordKey,
    blueSkyConfig?.handle,
    blueSkyConfig?.blockedHandles,
    blueSkyConfig?.blockedList,
  ]);

  return stats;
}
```

## 3/6 Our "Like, share or comment" button

**src/components/Bluesky/post.tsx**

```typescript
import Icon from "./bluesky.svg";
import styles from "./styles.module.css";
import Translate, { translate } from "@docusaurus/Translate";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import type { BlueskyMetadata, BlueskySiteConfig } from "./useBlueskyEngagement";

interface Props {
  metadata: BlueskyMetadata;
}

export default function BlueskyPost({ metadata }: Props) {
  const { siteConfig } = useDocusaurusContext();
  const blueSkyConfig = siteConfig?.customFields?.bluesky as
    BlueskySiteConfig | undefined;
  const blueskyRecordKey = metadata?.frontMatter?.blueskyRecordKey;

  if (!blueSkyConfig?.handle || !blueskyRecordKey) {
    return null;
  }

  const postUrl = `https://bsky.app/profile/${blueSkyConfig.handle}/post/${blueskyRecordKey}`;

  return (
    <a
      href={postUrl}
      target="_blank"
      rel="noopener noreferrer"
      className={styles.blueskyButton}
      aria-label={translate({
        id: "bluesky.post.ariaLabel",
        message: "See the post on Bluesky",
      })}
    >
      {/* alt dropped: SVGProps has no such prop — was a no-op DOM attribute even before this
          migration, and the link's own aria-label already names the icon. */}
      <Icon className={styles.blueskyLogo} />
      <Translate id="bluesky.post.label">Like, share or comment on Bluesky</Translate>
    </a>
  );
}
```

## 4/6 Our component for getting the number of likes and reposts

**src/components/Bluesky/likes.tsx**

```typescript
import styles from "./styles.module.css";
import { translate } from "@docusaurus/Translate";
import type {
  EngagedPerson,
  EngagementAction,
  EngagementStats,
} from "./useBlueskyEngagement";

const MAX_AVATARS = 10;

// Bluesky facets are keyed by "liked", "reposted", "commented" — a person can carry more than one.
function describeActions(actions: Set<EngagementAction>): string {
  // Each verb is translated on its own and the list is joined here. That holds in French too
  // ("a aimé, a repartagé et a commenté"), which is cheaper than translating all seven
  // combinations as whole sentences.
  const verbs: string[] = [];
  if (actions.has("liked")) {
    verbs.push(translate({ id: "bluesky.likes.verbLiked", message: "liked" }));
  }
  if (actions.has("reposted")) {
    verbs.push(translate({ id: "bluesky.likes.verbReposted", message: "reposted" }));
  }
  if (actions.has("commented")) {
    verbs.push(translate({ id: "bluesky.likes.verbCommented", message: "commented on" }));
  }

  if (verbs.length === 1) return verbs[0];
  const and = translate({ id: "bluesky.likes.and", message: "and" });
  return `${verbs.slice(0, -1).join(", ")} ${and} ${verbs[verbs.length - 1]}`;
}

interface Props {
  stats: EngagementStats;
}

export default function BlueskyLikes({ stats }: Props) {
  if (stats.loading || stats.likes === null) {
    return null;
  }

  const shown: EngagedPerson[] = stats.engaged.slice(0, MAX_AVATARS);
  const extraEngaged = stats.engaged.length - shown.length;

  return (
    <span className={styles.blueskyPostLikes}>
      <span
        className={styles.blueskyCommentLikes}
        title={translate(
          {
            id: "bluesky.likes.likesTitle",
            message: "The original post has {count} likes on Bluesky",
          },
          { count: stats.likes },
        )}
      >
        {stats.likes}
      </span>
      <span
        className={styles.blueskyCommentReposts}
        title={translate(
          {
            id: "bluesky.likes.repostsTitle",
            message: "The original post has been shared {count} times on Bluesky",
          },
          // Only `likes` is narrowed by the guard above; `reposts` can still be null here.
          { count: stats.reposts ?? 0 },
        )}
      >
        {stats.reposts}
      </span>
      {shown.length > 0 && (
        <span className={styles.blueskyLikersAvatars}>
          {shown.map((person, index) => (
            <a
              key={person.did}
              href={`https://bsky.app/profile/${person.handle}`}
              target="_blank"
              rel="noopener noreferrer"
              className={styles.blueskyLikersAvatarLink}
              style={{ zIndex: shown.length - index }}
              title={translate(
                {
                  id: "bluesky.likes.personTitle",
                  message: "{name} (@{handle}) {actions} this post",
                },
                {
                  name: person.displayName,
                  handle: person.handle,
                  actions: describeActions(person.actions),
                },
              )}
            >
              <img
                src={person.avatar}
                alt={translate(
                  { id: "bluesky.avatarAlt", message: "{name}'s avatar" },
                  { name: person.displayName },
                )}
                className={styles.blueskyLikersAvatar}
              />
            </a>
          ))}
          {extraEngaged > 0 && (
            <span className={styles.blueskyLikersAvatarMore}>+{extraEngaged}</span>
          )}
        </span>
      )}
    </span>
  );
}
```

> **Note:**
>
> An earlier version of this component only showed the avatars of the people who **liked** the post. That was misleading: a reader could see "5 likes" next to only 3 avatars, because reposters and commenters weren't counted. The current version fetches likers, reposters and commenters in parallel, merges them into a single `Map` keyed by the person's Bluesky `did` (so the same person liking **and** commenting only appears once), and sorts that list by number of actions — someone who liked *and* commented outranks someone who only liked. Up to ten avatars are shown, the rest collapse into a `+N` badge, and each avatar's tooltip spells out what that person actually did (`"liked and commented on this post"`).

## 5/6 Retrieving all comments

**src/components/Bluesky/comments.tsx**

```typescript
import { useState, useEffect, type ReactNode } from "react";
import styles from "./styles.module.css";
import Translate, { translate } from "@docusaurus/Translate";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import { fetchBlockedList } from "./useBlueskyEngagement";
import type {
  BlueskyEmbed,
  BlueskyMetadata,
  BlueskyPostRecord,
  BlueskyReplyNode,
  BlueskySiteConfig,
} from "./useBlueskyEngagement";

// Bluesky facet indices are UTF-8 byte offsets, not JS string indices.
// TextEncoder/TextDecoder ensures correct slicing for non-ASCII text (emoji, accents…).
function renderPostText(record: BlueskyPostRecord, isOwner: boolean): ReactNode {
  const text = record.text;
  const facets = record.facets || [];
  if (facets.length === 0) return text;

  const encoder = new TextEncoder();
  const decoder = new TextDecoder();
  const bytes = encoder.encode(text);

  const parts: ReactNode[] = [];
  let lastIndex = 0;

  facets.forEach((facet, idx) => {
    const start = facet.index.byteStart;
    const end = facet.index.byteEnd;

    const before = decoder.decode(bytes.slice(lastIndex, start));
    if (before) parts.push(before);

    const linkFeature = facet.features.find(
      (f) => f.$type === "app.bsky.richtext.facet#link",
    );
    if (linkFeature && isOwner) {
      // Site owner's links are trusted — render as a clickable anchor.
      parts.push(
        <a
          key={`link-${idx}`}
          href={linkFeature.uri}
          target="_blank"
          rel="noopener noreferrer nofollow"
        >
          {decoder.decode(bytes.slice(start, end))}
        </a>,
      );
    } else {
      // Other authors' links are unvetted (spam risk).
      // Render the anchor text only — the original is reachable via "View comment".
      parts.push(decoder.decode(bytes.slice(start, end)));
    }

    lastIndex = end;
  });

  if (lastIndex < bytes.length) {
    parts.push(decoder.decode(bytes.slice(lastIndex)));
  }

  return parts;
}

function renderEmbed(embed: BlueskyEmbed | null | undefined): ReactNode {
  if (!embed) return null;

  // Narrowed by property presence, not by `$type` equality: `BlueskyEmbed`'s catch-all
  // member types `$type` as a plain `string` (any other embed kind the API can return —
  // video, record quote, …), so a literal-equality check can't exclude it and `embed.external`
  // wouldn't narrow.
  if ("external" in embed) {
    const { uri, title, thumb } = embed.external;

    return (
      <a
        href={uri}
        target="_blank"
        rel="noopener noreferrer nofollow"
        className={styles.blueskyCommentEmbed}
      >
        {thumb && <img src={thumb} alt="" className={styles.blueskyCommentEmbedThumb} />}
        <div className={styles.blueskyCommentEmbedContent}>
          <strong>{title}</strong>
        </div>
      </a>
    );
  }

  if ("images" in embed) {
    return (
      <div className={styles.blueskyCommentImages}>
        {embed.images.map((image, index) => (
          <img
            key={index}
            src={image.fullsize}
            alt={
              image.alt ||
              translate({ id: "bluesky.embeddedImage", message: "Embedded image" })
            }
            className={styles.blueskyCommentImage}
          />
        ))}
      </div>
    );
  }

  return null;
}

interface FlattenedReply extends BlueskyReplyNode {
  depth: number;
}

function BlueskyComment({
  reply,
  ownerHandle,
}: {
  reply: FlattenedReply;
  ownerHandle?: string;
}) {
  const isOwner = !!ownerHandle && reply.post.author.handle === ownerHandle;
  const recordKey = reply.post.uri.split("/").pop();
  const profileUrl = `https://bsky.app/profile/${reply.post.author.handle}`;
  const commentUrl = `https://bsky.app/profile/${reply.post.author.handle}/post/${recordKey}`;
  const date = new Date(reply.post.indexedAt).toLocaleString(undefined, {
    year: "numeric",
    month: "short",
    day: "numeric",
    hour: "2-digit",
    minute: "2-digit",
  });

  return (
    <div
      className={styles.blueskyCommentContainer}
      style={{ paddingLeft: `${1.5 + reply.depth * 1.5}rem` }}
    >
      <div className={`${styles.blueskyCommentHeader} mb-2 flex items-center`}>
        <a href={profileUrl} target="_blank" rel="noopener noreferrer nofollow">
          <img
            src={reply.post.author.avatar}
            alt={translate(
              { id: "bluesky.avatarAlt", message: "{name}'s avatar" },
              { name: reply.post.author.displayName },
            )}
            className={styles.blueskyCommentAvatar}
          />
        </a>
        <div className={styles.blueskyCommentAuthorInfos}>
          <a
            href={profileUrl}
            target="_blank"
            rel="noopener noreferrer nofollow"
            className={styles.blueskyCommentAuthorDisplayName}
          >
            {reply.post.author.displayName}
          </a>
          <span className={styles.blueskyCommentAuthorHandle}>
            @{reply.post.author.handle}
          </span>
        </div>
      </div>

      <span className={styles.blueskyCommentDate}>{date}</span>

      <p className={styles.blueskyCommentText}>
        {renderPostText(reply.post.record, isOwner)}
      </p>

      {renderEmbed(reply.post.embed)}

      <div className={styles.blueskyCommentFooter}>
        <span className={styles.blueskyCommentLikes}>{reply.post.likeCount}</span>
        <span className={styles.blueskyCommentReposts}>
          {reply.post.repostCount || 0}
        </span>
        <a
          className={styles.blueskyCommentLink}
          href={commentUrl}
          target="_blank"
          rel="noopener noreferrer nofollow"
        >
          <Translate id="bluesky.comments.view">View comment</Translate>
        </a>
      </div>
    </div>
  );
}

interface PostThreadResponse {
  thread: {
    replies?: BlueskyReplyNode[];
  };
}

interface Props {
  metadata: BlueskyMetadata;
}

export default function BlueskyComments({ metadata }: Props) {
  const { siteConfig } = useDocusaurusContext();
  const blueSkyConfig = siteConfig?.customFields?.bluesky as
    BlueskySiteConfig | undefined;
  const blueskyRecordKey = metadata?.frontMatter?.blueskyRecordKey;

  const [comments, setComments] = useState<FlattenedReply[] | null>(null);
  const [error, setError] = useState(false);

  useEffect(() => {
    if (!blueskyRecordKey || !blueSkyConfig?.handle) return;

    const fetchComments = async () => {
      try {
        const postUri = `at://${blueSkyConfig.handle}/app.bsky.feed.post/${blueskyRecordKey}`;
        const url =
          "https://public.api.bsky.app/xrpc/app.bsky.feed.getPostThread?depth=5&uri=" +
          encodeURIComponent(postUri);

        // Fetch thread and moderation list in parallel — shares the sessionStorage cache
        // with useBlueskyEngagement so the second caller resolves instantly.
        const [res, listBlocked] = await Promise.all([
          fetch(url),
          blueSkyConfig?.blockedList
            ? fetchBlockedList(blueSkyConfig.blockedList).catch(() => new Set<string>())
            : Promise.resolve(new Set<string>()),
        ]);
        if (!res.ok) throw new Error("Failed to fetch post thread");
        const data = (await res.json()) as PostThreadResponse;

        const blocked = new Set([
          ...(blueSkyConfig?.blockedHandles ?? []),
          ...listBlocked,
        ]);
        const allComments: FlattenedReply[] = [];
        const flattenReplies = (arr: BlueskyReplyNode[] | undefined, depth: number) => {
          if (!arr) return;
          for (const r of arr) {
            // Skip blocked handles (e.g. spammers hidden on bsky.app but still
            // returned by the public API). Sub-replies are still walked so that
            // legitimate replies to a spam comment remain visible.
            if (!blocked.has(r.post.author.handle)) {
              allComments.push({ ...r, depth });
            }
            if (r.replies) flattenReplies(r.replies, depth + 1);
          }
        };

        if (data.thread?.replies) {
          flattenReplies(data.thread.replies, 0);
        }

        setComments(allComments);
      } catch (err) {
        // Offline, blocked by the visitor, or Bluesky unreachable: stay silent
        // rather than surface a raw error — same outcome as no comments to show.
        console.error(err);
        setError(true);
      }
    };
    fetchComments();
  }, [
    blueskyRecordKey,
    blueSkyConfig?.handle,
    blueSkyConfig?.blockedHandles,
    blueSkyConfig?.blockedList,
  ]);

  if (!blueskyRecordKey || error) return null;
  if (comments === null) {
    return (
      <p>
        <Translate id="bluesky.comments.loading">Loading comments…</Translate>
      </p>
    );
  }

  const postUrl = `https://bsky.app/profile/${blueSkyConfig?.handle}/post/${blueskyRecordKey}`;

  if (comments.length === 0)
    return (
      <p className={styles.blueskyNoCommentYet}>
        <Translate id="bluesky.comments.none">
          This post is waiting for its first comment.
        </Translate>
        &nbsp;
        <a
          className={styles.blueskyNoCommentYetCTA}
          href={postUrl}
          target="_blank"
          rel="noopener noreferrer nofollow"
        >
          <Translate id="bluesky.comments.cta">Share your thoughts!</Translate>
        </a>
      </p>
    );

  return (
    <div className={styles.blueskyCommentsContainer}>
      <h3>
        <Translate id="bluesky.comments.heading" values={{ count: comments.length }}>
          {"💬 Comments from Bluesky ({count})"}
        </Translate>
      </h3>
      {comments.map((reply) => (
        <BlueskyComment
          key={reply.post.uri}
          reply={reply}
          ownerHandle={blueSkyConfig?.handle}
        />
      ))}
    </div>
  );
}
```

## 6/6 Our new CSS

**src/components/Bluesky/styles.module.css**

```css
.blueskyLogo {
  width: 20px;
  height: 20px;
}

.blueskyContainer {
  margin: 2rem 0 0.5rem;
  padding: 1.1rem 1.25rem 1.4rem;
  border: 1px solid var(--ifm-color-emphasis-200);
  border-radius: 8px;
  background: var(--ifm-background-surface-color);
}

.blueskyHeadline {
  display: block;
  font-weight: 500;
  color: var(--ifm-color-content);
  margin-bottom: 0.75rem;
}

.blueskyAccountNote {
  display: block;
  margin-top: 0.6rem;
  font-size: smaller;
  color: var(--ifm-color-emphasis-600);
}

.blueskyCommentsContainer {
  border: 1px solid var(--ifm-color-emphasis-200);
  margin-top: 1rem;
  padding: 0.4rem 0.9rem;
  margin-bottom: 1.25rem;
}

.blueskyCommentContainer {
  margin-bottom: 1rem;
  background-color: var(--ifm-color-emphasis-100);
  padding: 0.8rem;
  border-radius: 6px;
  border-left: 2px solid var(--ifm-color-emphasis-300);
  color: var(--ifm-font-color-base);
}

.blueskyCommentHeader {
  display: flex;
  align-items: center;
  gap: 10px;
}

.blueskyCommentAuthorInfos {
  display: flex;
  flex-direction: column;
}

.blueskyCommentAvatar {
  width: 32px;
  height: 32px;
  border-radius: 50%;
  margin-right: 0.5rem;
}

.blueskyCommentAuthorDisplayName {
  margin: 0;
  font-weight: bold;
}

.blueskyCommentAuthorHandle {
  margin: 0;
  font-size: smaller;
  font-weight: normal;
  color: var(--ifm-color-emphasis-600);
  display: block;
}

.blueskyCommentDate {
  margin-left: auto;
  font-size: smaller;
  color: var(--ifm-color-emphasis-600);
}

.blueskyCommentText {
  margin: 0.3rem 0 0;
}

.blueskyCommentLikes::before {
  content: "❤️\a0";
}

.blueskyCommentLikes::after {
  content: " ";
}

.blueskyCommentReposts::before {
  content: "🔁\a0";
}

.blueskyCommentReposts::after {
  content: " ";
}

.blueskyCommentLink::before {
  content: "→\a0";
}

.blueskyCommentLink::after {
  content: " ";
}

.blueskyCommentLink {
  margin-right: 0.25rem;
  display: inline-flex;
  align-items: center;
  color: var(--ifm-color-emphasis-600);
  text-decoration: none;
  margin-top: 0.25rem;
}

img.blueskyCommentEmbedThumb {
  max-height: 250px;
}

.blueskyCommentImages {
  margin-top: 0.5rem;
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
}

.blueskyCommentImage {
  max-width: 100%;
  height: auto;
  border-radius: 0.25rem;
  border: 1px solid var(--ifm-color-emphasis-300);
}

.blueskyNoCommentYet {
  color: var(--ifm-color-emphasis-600);
  font-size: 1rem;
  line-height: 1.5;
  text-align: center;
  padding: 20px;
  background-color: var(--ifm-color-emphasis-100);
  border: 1px solid var(--ifm-color-emphasis-300);
  border-radius: 8px;
  margin: 20px 0;
}

.blueskyNoCommentYetCTA {
  font-weight: bold;
  color: var(--ifm-color-primary-dark);
  cursor: pointer;
  text-decoration: underline;
}

[data-theme="dark"] .blueskyNoCommentYetCTA {
  color: var(--ifm-color-primary-light);
}

.blueskyPostLikes {
  display: inline-flex;
  align-items: center;
  gap: 0.4rem;
}

.blueskyLikersAvatars {
  display: inline-flex;
  align-items: center;
  margin-left: 0.4rem;
}

.blueskyLikersAvatarLink {
  margin-left: -1rem;
  line-height: 0;
}

.blueskyLikersAvatarLink:first-child {
  margin-left: 0;
}

.blueskyLikersAvatar {
  width: 40px;
  height: 40px;
  border-radius: 50%;
  border: 2px solid var(--ifm-background-color);
  display: block;
}

.blueskyLikersAvatarMore {
  margin-left: 0.4rem;
  font-size: smaller;
  color: var(--ifm-color-emphasis-600);
}

.blueskyEngagementRow {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
}

.blueskyButton {
  align-items: center;
  background-color: var(--ifm-color-emphasis-200);
  border-radius: 6px;
  border: 1px solid var(--ifm-color-emphasis-300);
  box-shadow: none;
  color: var(--ifm-font-color-base);
  display: inline-flex;
  font-size: 0.9rem;
  font-weight: 400;
  gap: 0.4rem;
  margin-bottom: 0.8rem;
  margin-right: 0.4rem;
  padding: 0.4rem 0.9rem;
  text-decoration: none;
  transition:
    background-color 0.2s ease,
    color 0.2s ease;
}

.blueskyButton:hover {
  background-color: var(--ifm-color-primary);
  border-color: var(--ifm-color-primary);
  color: white;
}
```

## Update the Docusaurus configuration file

We're almost done. In order to be able to retrieve likes, shares and comments from your Bluesky account, you have to tell the component your Bluesky handle.

You have to edit the `docusaurus.config.js` file and add a new section called `customFields` as illustrated below:

**docusaurus.config.js**

```javascript
// Partial file; illustration of what you've to do

// [...]

const config = {

  // [...]

  customFields: {
    bluesky: {
      // This is the Bluesky handle as displayed in your Bluesky profile page
      handle: "your-bluesky-handle",
    },
  }

}
```

> **Danger:**
>
> For sure, use yours; not mine ;-)

## All Files at a Glance

Here is the full set of files this article touched — the update to `index.tsx`, and the four new files (`useBlueskyEngagement.ts`, `post.tsx`, `likes.tsx`, `comments.tsx`) plus the refreshed CSS. Use the button below to copy them all at once, or download them as a ready-to-extract ZIP:

**Project: Bluesky engagement**

> **Note:**
>
> These files replace the ones created in the [first article](/blog/docusaurus-bluesky-share).
> Don't forget to also add the `customFields.bluesky` block to your `docusaurus.config.js` (see
> above), then restart your Docusaurus dev server.

**src/components/Bluesky/index.tsx**

```typescript
import BlueskyComments from "./comments";
import BlueskyLikes from "./likes";
import BlueskyPost from "./post";
import BlueskyShare from "./share";
import styles from "./styles.module.css";
import Translate, { translate } from "@docusaurus/Translate";
import useBlueskyEngagement, { useBlueskyRecordKey } from "./useBlueskyEngagement";
import type { BlueskyMetadata, EngagedPerson } from "./useBlueskyEngagement";

function engagementHeadline({
  blueskyRecordKey,
  loading,
  unavailable,
  engaged,
}: {
  blueskyRecordKey: string | null;
  loading: boolean;
  unavailable: boolean;
  engaged: EngagedPerson[];
}): string {
  if (!blueskyRecordKey) {
    return translate({
      id: "bluesky.heading.share",
      message: "🦋 Enjoyed this article? Share it on Bluesky",
    });
  }
  if (loading || unavailable) {
    // Same neutral copy for "still fetching" and "couldn't fetch" — never claim
    // "no one reacted yet" when the truth is just "couldn't check".
    return translate({
      id: "bluesky.heading.join",
      message: "🦋 Join the conversation on Bluesky",
    });
  }
  if (engaged.length === 0) {
    return translate({
      id: "bluesky.heading.first",
      message: "🦋 Be the first to react on Bluesky",
    });
  }
  const count = engaged.length;
  // Two whole sentences rather than a spliced "person is" / "people are": French agreement
  // reaches further than the verb ("personne en parle" / "personnes en parlent").
  return count === 1
    ? translate({
        id: "bluesky.heading.talkingOne",
        message: "🦋 1 person is already talking about this on Bluesky — join them",
      })
    : translate(
        {
          id: "bluesky.heading.talkingOther",
          message:
            "🦋 {count} people are already talking about this on Bluesky — join them",
        },
        { count },
      );
}

interface Props {
  metadata: BlueskyMetadata;
}

export default function Bluesky({ metadata }: Props) {
  // The frontmatter key always wins (manual override); otherwise it's looked up
  // from the account's own Bluesky post history, matched against this article's
  // URL — see useBlueskyRecordKey for why and how.
  const { recordKey, resolving } = useBlueskyRecordKey(metadata);
  const effectiveMetadata: BlueskyMetadata = {
    ...metadata,
    frontMatter: { ...metadata.frontMatter, blueskyRecordKey: recordKey ?? undefined },
  };
  const stats = useBlueskyEngagement(effectiveMetadata);

  // Still checking whether this article was already promoted — skip the frame
  // rather than flash a "Share on Bluesky" button that may disappear a moment
  // later once a match is found.
  if (resolving) return null;

  return (
    <div className={styles.blueskyContainer}>
      <span className={styles.blueskyHeadline}>
        {engagementHeadline({
          blueskyRecordKey: recordKey,
          loading: stats.loading,
          unavailable: stats.unavailable,
          engaged: stats.engaged,
        })}
      </span>

      {/* No Bluesky post found for this article: show a share button */}
      <BlueskyShare metadata={effectiveMetadata} />

      {/* A Bluesky post was found and its data actually loaded: show engagement UI.
          Hiding BlueskyPost too when unavailable — a resolved key can point to a
          post that was since deleted, and a link straight to a 404 is worse than
          no link. */}
      {!stats.unavailable && (
        <div className={styles.blueskyEngagementRow}>
          <BlueskyPost metadata={effectiveMetadata} />
          <BlueskyLikes stats={stats} />
        </div>
      )}

      <span className={styles.blueskyAccountNote}>
        <Translate id="bluesky.accountNote">
          {
            "Requires a free Bluesky account to like, repost or comment. This block talks to Bluesky's public API directly from your browser (no cookies, no sign-in) — that means your IP address reaches Bluesky's servers just by this section loading."
          }
        </Translate>
      </span>

      <BlueskyComments metadata={effectiveMetadata} />
    </div>
  );
}
```

**src/components/Bluesky/useBlueskyEngagement.ts**

```typescript
import { useState, useEffect } from "react";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import { useSourceLocaleUrls } from "@site/src/components/Blog/utils/localeUrls";

const MAX_ACTORS_PER_ENDPOINT = 20;
const FEED_CACHE_PREFIX = "bluesky-feed-cache:";
const FEED_CACHE_TTL_MS = 5 * 60 * 1000;
const MAX_FEED_PAGES = 5;
const BLOCKED_LIST_CACHE_PREFIX = "bluesky-blocked-list-cache:";
const BLOCKED_LIST_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour — list changes rarely

/** `docusaurus.config.js`'s `customFields.bluesky` — a custom field, typed `unknown` by
 * Docusaurus itself, so every reader casts against this shape. */
export interface BlueskySiteConfig {
  handle?: string;
  /**
   * AT URI of a Bluesky moderation list whose members are hidden from comments and the facepile.
   * Fetched at runtime from the public API (no auth required) and cached 1 h in sessionStorage —
   * adding a handle to the list takes effect on the next page load with no deploy needed.
   * Create a list at bsky.app → Lists, then copy its URI (at://did:plc:…/app.bsky.graph.list/…).
   */
  blockedList?: string;
  /** Compile-time override: handles blocked regardless of the Bluesky list (e.g. during deploy). */
  blockedHandles?: string[];
}

/** The subset of a blog post's `useBlogPost().metadata` every Bluesky file actually reads. */
export interface BlueskyMetadata {
  title?: string;
  permalink?: string;
  frontMatter?: {
    blueskyRecordKey?: string;
  };
}

export type EngagementAction = "liked" | "reposted" | "commented";

export interface EngagedPerson {
  did: string;
  handle: string;
  displayName: string;
  avatar?: string;
  actions: Set<EngagementAction>;
}

export interface EngagementStats {
  likes: number | null;
  reposts: number | null;
  engaged: EngagedPerson[];
  loading: boolean;
  unavailable: boolean;
}

export interface RecordKeyState {
  recordKey: string | null;
  resolving: boolean;
}

export interface BlueskyActor {
  did: string;
  handle: string;
  displayName?: string;
  avatar?: string;
}

export interface BlueskyFacetFeature {
  $type: string;
  uri?: string;
}

export interface BlueskyFacet {
  index: { byteStart: number; byteEnd: number };
  features: BlueskyFacetFeature[];
}

export interface BlueskyPostRecord {
  text: string;
  facets?: BlueskyFacet[];
}

export interface BlueskyEmbedExternal {
  $type: "app.bsky.embed.external#view";
  external: { uri: string; title: string; thumb?: string };
}

export interface BlueskyEmbedImages {
  $type: "app.bsky.embed.images#view";
  images: { fullsize: string; alt?: string }[];
}

export type BlueskyEmbed = BlueskyEmbedExternal | BlueskyEmbedImages | { $type: string };

export interface BlueskyPostView {
  uri: string;
  indexedAt: string;
  likeCount: number;
  repostCount?: number;
  author: BlueskyActor & { displayName: string };
  record: BlueskyPostRecord;
  embed?: BlueskyEmbed | null;
}

export interface BlueskyReplyNode {
  post: BlueskyPostView;
  replies?: BlueskyReplyNode[];
}

function flattenReplyAuthors(replies: BlueskyReplyNode[] | undefined): BlueskyActor[] {
  const authors: BlueskyActor[] = [];
  const walk = (arr: BlueskyReplyNode[] | undefined) => {
    if (!arr) return;
    for (const reply of arr) {
      authors.push(reply.post.author);
      walk(reply.replies);
    }
  };
  walk(replies);
  return authors;
}

function mergeEngagement(
  {
    likers = [],
    reposters = [],
    commenters = [],
  }: { likers?: BlueskyActor[]; reposters?: BlueskyActor[]; commenters?: BlueskyActor[] },
  ownerHandle: string | undefined,
  blockedHandles: Set<string> = new Set(),
): EngagedPerson[] {
  const byDid = new Map<string, EngagedPerson>();

  const record = (actor: BlueskyActor | undefined, action: EngagementAction) => {
    // Replying to your own readers isn't reader engagement — exclude the blog's own account.
    // Also exclude any handle explicitly blocked in the site config (e.g. spammers).
    if (!actor?.did || actor.handle === ownerHandle || blockedHandles.has(actor.handle))
      return;
    const entry = byDid.get(actor.did) || {
      did: actor.did,
      handle: actor.handle,
      displayName: actor.displayName || actor.handle,
      avatar: actor.avatar,
      actions: new Set<EngagementAction>(),
    };
    entry.actions.add(action);
    byDid.set(actor.did, entry);
  };

  likers.forEach((actor) => record(actor, "liked"));
  reposters.forEach((actor) => record(actor, "reposted"));
  commenters.forEach((actor) => record(actor, "commented"));

  // People engaged in more than one way surface first — they're the strongest social proof.
  return [...byDid.values()].sort((a, b) => b.actions.size - a.actions.size);
}

function normalizeUrl(url: string | null | undefined): string | null {
  if (!url) return null;
  return url.split("?")[0].replace(/\/+$/, "");
}

interface BlockedListResponse {
  items?: { subject?: { handle?: string } }[];
  cursor?: string;
}

// Fetches every handle in a Bluesky moderation list (pagination-aware) and caches
// the result in sessionStorage for 1 hour so browsing many articles doesn't re-fetch.
// Exported so BlueskyComments can share the same cache without a duplicate request.
export async function fetchBlockedList(listUri: string): Promise<Set<string>> {
  const cacheKey = BLOCKED_LIST_CACHE_PREFIX + listUri;
  try {
    const raw = sessionStorage.getItem(cacheKey);
    if (raw) {
      const { timestamp, handles } = JSON.parse(raw) as {
        timestamp: number;
        handles: string[];
      };
      if (Date.now() - timestamp <= BLOCKED_LIST_CACHE_TTL_MS) return new Set(handles);
    }
  } catch {
    /* private browsing or corrupt entry — just refetch */
  }

  const handles: string[] = [];
  let cursor: string | undefined;

  for (let page = 0; page < 10; page++) {
    const params = new URLSearchParams({ list: listUri, limit: "100" });
    if (cursor) params.set("cursor", cursor);
    const res = await fetch(
      `https://public.api.bsky.app/xrpc/app.bsky.graph.getList?${params}`,
    );
    if (!res.ok) break;
    const data = (await res.json()) as BlockedListResponse;
    for (const item of data.items ?? []) {
      if (item.subject?.handle) handles.push(item.subject.handle);
    }
    cursor = data.cursor;
    if (!cursor) break;
  }

  try {
    sessionStorage.setItem(cacheKey, JSON.stringify({ timestamp: Date.now(), handles }));
  } catch {
    /* private browsing — cache miss next time, that's fine */
  }

  return new Set(handles);
}

type FeedIndex = Record<string, string>;

function readFeedCache(handle: string): FeedIndex | null {
  try {
    const raw = sessionStorage.getItem(FEED_CACHE_PREFIX + handle);
    if (!raw) return null;
    const { timestamp, urlToRecordKey } = JSON.parse(raw) as {
      timestamp: number;
      urlToRecordKey: FeedIndex;
    };
    if (Date.now() - timestamp > FEED_CACHE_TTL_MS) return null;
    return urlToRecordKey;
  } catch {
    return null;
  }
}

function writeFeedCache(handle: string, urlToRecordKey: FeedIndex): void {
  try {
    sessionStorage.setItem(
      FEED_CACHE_PREFIX + handle,
      JSON.stringify({ timestamp: Date.now(), urlToRecordKey }),
    );
  } catch {
    // Private browsing / storage disabled — resolution still works, just uncached.
  }
}

interface AuthorFeedItem {
  post: {
    uri: string;
    record?: {
      embed?: {
        $type?: string;
        external?: { uri?: string };
      };
    };
  };
}

interface AuthorFeedResponse {
  feed?: AuthorFeedItem[];
  cursor?: string;
}

// Builds a { normalizedArticleUrl: recordKey } map from the account's own post
// history, matching on the "external" link-card embed Bluesky attaches when a
// post links out (the same card the Share button in this component produces).
// Cached per tab session so browsing several un-tagged articles doesn't re-fetch
// the whole feed each time.
async function buildFeedIndex(handle: string): Promise<FeedIndex> {
  const cached = readFeedCache(handle);
  if (cached) return cached;

  const urlToRecordKey: FeedIndex = {};
  let cursor: string | undefined;

  for (let page = 0; page < MAX_FEED_PAGES; page += 1) {
    const params = new URLSearchParams({
      actor: handle,
      limit: "100",
      filter: "posts_no_replies",
    });
    if (cursor) params.set("cursor", cursor);

    const res = await fetch(
      `https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?${params}`,
    );
    if (!res.ok) throw new Error("Failed to fetch author feed");
    const data = (await res.json()) as AuthorFeedResponse;

    for (const item of data.feed || []) {
      const embed = item.post?.record?.embed;
      const externalUri =
        embed?.$type === "app.bsky.embed.external" ? (embed.external?.uri ?? null) : null;
      const normalized = normalizeUrl(externalUri);
      if (normalized) urlToRecordKey[normalized] = item.post.uri.split("/").pop()!;
    }

    cursor = data.cursor;
    if (!cursor || !data.feed?.length) break;
  }

  writeFeedCache(handle, urlToRecordKey);
  return urlToRecordKey;
}

// Resolves the Bluesky record key for the current article. The frontmatter value
// always wins — it's the manual override needed after a slug rename, or to
// disambiguate an article re-promoted with a second post. Otherwise the key is
// looked up from the account's own post history. In a translated locale the
// article's own URL (`/fr/blog/x/`) is tried first, then the source-language one
// (`/blog/x/`): the author usually promotes only the English article, and French
// readers should join that conversation rather than see a "Share" button. A
// dedicated French post, if one exists, still wins. Never throws: any failure here
// (offline, blocked, no match found) just means no engagement UI is shown, the
// same as an article that was never promoted at all.
export function useBlueskyRecordKey(
  metadata: BlueskyMetadata | undefined,
): RecordKeyState {
  const { siteConfig } = useDocusaurusContext();
  const blueSkyConfig = siteConfig?.customFields?.bluesky as
    BlueskySiteConfig | undefined;
  const frontMatterKey = metadata?.frontMatter?.blueskyRecordKey;
  const { isDefaultLocale, sourceAbsoluteUrl } = useSourceLocaleUrls();

  // `permalink` comes from Docusaurus and already carries the locale's baseUrl
  // (`/fr/blog/x/`) — so `siteConfig.url + permalink` is correct as is and must
  // NOT be prefixed again. The source URL is the reverse: strip that baseUrl,
  // then resolve the rest against the source locale. Slugs are never translated,
  // so the remainder is the same in both locales.
  const permalink = metadata?.permalink;
  const currentUrl = permalink ? normalizeUrl(`${siteConfig.url}${permalink}`) : null;
  const sourceUrl =
    permalink && !isDefaultLocale && permalink.startsWith(siteConfig.baseUrl)
      ? normalizeUrl(sourceAbsoluteUrl(permalink.slice(siteConfig.baseUrl.length)))
      : null;

  const [state, setState] = useState<RecordKeyState>({
    recordKey: frontMatterKey || null,
    resolving: !frontMatterKey,
  });

  useEffect(() => {
    if (frontMatterKey) {
      // eslint-disable-next-line react-hooks/set-state-in-effect -- mirrors a prop change (article navigation), not derivable at render time
      setState({ recordKey: frontMatterKey, resolving: false });
      return;
    }
    if (!blueSkyConfig?.handle || !currentUrl) {
      setState({ recordKey: null, resolving: false });
      return;
    }

    let cancelled = false;

    (async () => {
      try {
        const index = await buildFeedIndex(blueSkyConfig.handle!);
        if (!cancelled)
          setState({
            recordKey: index[currentUrl] || (sourceUrl && index[sourceUrl]) || null,
            resolving: false,
          });
      } catch (e) {
        console.error("Bluesky record key lookup failed:", e);
        if (!cancelled) setState({ recordKey: null, resolving: false });
      }
    })();

    return () => {
      cancelled = true;
    };
  }, [frontMatterKey, blueSkyConfig?.handle, currentUrl, sourceUrl]);

  return state;
}

interface LikesResponse {
  likes: { actor: BlueskyActor }[];
}

interface RepostedByResponse {
  repostedBy: BlueskyActor[];
}

async function fetchActors(
  endpoint: "getLikes" | "getRepostedBy",
  uri: string,
  listKey: "likes" | "repostedBy",
): Promise<BlueskyActor[]> {
  const url = `https://public.api.bsky.app/xrpc/app.bsky.feed.${endpoint}?uri=${encodeURIComponent(
    uri,
  )}&limit=${MAX_ACTORS_PER_ENDPOINT}`;

  const res = await fetch(url);
  if (!res.ok) throw new Error(`Failed to fetch ${endpoint}`);

  const data = (await res.json()) as LikesResponse | RepostedByResponse;
  return listKey === "likes"
    ? (data as LikesResponse).likes.map(({ actor }) => actor)
    : (data as RepostedByResponse).repostedBy;
}

interface PostThreadResponse {
  thread: {
    post: { likeCount: number; repostCount: number; uri: string };
    replies?: BlueskyReplyNode[];
  };
}

// Shared by index.tsx (headline copy) and likes.tsx (counts + facepile) so the
// thread/likes/reposts fetches happen once per post, not once per consumer.
export default function useBlueskyEngagement(
  metadata: BlueskyMetadata | undefined,
): EngagementStats {
  const { siteConfig } = useDocusaurusContext();
  const blueSkyConfig = siteConfig?.customFields?.bluesky as
    BlueskySiteConfig | undefined;
  const blueskyRecordKey = metadata?.frontMatter?.blueskyRecordKey;

  const [stats, setStats] = useState<EngagementStats>({
    likes: null,
    reposts: null,
    engaged: [],
    loading: true,
    unavailable: false,
  });

  useEffect(() => {
    if (!blueskyRecordKey || !blueSkyConfig?.handle) {
      // eslint-disable-next-line react-hooks/set-state-in-effect -- resets stats when the post/config identity changes; the effect also fetches below, it's not derivable at render time
      setStats({
        likes: null,
        reposts: null,
        engaged: [],
        loading: false,
        unavailable: false,
      });
      return;
    }

    const fetchData = async () => {
      const postUri = `at://${blueSkyConfig.handle}/app.bsky.feed.post/${blueskyRecordKey}`;
      const threadUrl = `https://public.api.bsky.app/xrpc/app.bsky.feed.getPostThread?uri=${encodeURIComponent(
        postUri,
      )}&depth=5`;

      // Fetch the thread and the moderation list in parallel — neither depends on the other.
      // The list is cached 1 h in sessionStorage, so after the first load it resolves instantly.
      try {
        const [threadRes, listBlocked] = await Promise.all([
          fetch(threadUrl),
          blueSkyConfig.blockedList
            ? fetchBlockedList(blueSkyConfig.blockedList).catch(() => new Set<string>())
            : Promise.resolve(new Set<string>()),
        ]);
        const blockedHandles = new Set([
          ...(blueSkyConfig.blockedHandles ?? []),
          ...listBlocked,
        ]);

        const res = threadRes;
        if (!res.ok) throw new Error("Failed to fetch post data");

        const data = (await res.json()) as PostThreadResponse;
        const { likeCount, repostCount, uri: resolvedUri } = data.thread.post;
        const commenters = flattenReplyAuthors(data.thread.replies);

        setStats({
          likes: likeCount,
          reposts: repostCount,
          engaged: mergeEngagement({ commenters }, blueSkyConfig.handle, blockedHandles),
          loading: false,
          unavailable: false,
        });

        // resolvedUri carries the post's DID (getLikes/getRepostedBy return nothing for a handle-based URI)
        const [likers, reposters] = await Promise.all([
          likeCount > 0 ? fetchActors("getLikes", resolvedUri, "likes") : [],
          repostCount > 0 ? fetchActors("getRepostedBy", resolvedUri, "repostedBy") : [],
        ]);

        setStats((prev) => ({
          ...prev,
          engaged: mergeEngagement(
            { likers, reposters, commenters },
            blueSkyConfig.handle,
            blockedHandles,
          ),
        }));
      } catch (e) {
        // Offline, blocked by the visitor (ad-blocker, DNS filtering), or Bluesky
        // itself down — never surface this as a JS error, just mark the data as
        // unavailable so the UI doesn't claim "no one reacted yet" instead.
        console.error("Error fetching Bluesky stats:", e);
        setStats({
          likes: null,
          reposts: null,
          engaged: [],
          loading: false,
          unavailable: true,
        });
      }
    };

    fetchData();
  }, [
    blueskyRecordKey,
    blueSkyConfig?.handle,
    blueSkyConfig?.blockedHandles,
    blueSkyConfig?.blockedList,
  ]);

  return stats;
}
```

**src/components/Bluesky/post.tsx**

```typescript
import Icon from "./bluesky.svg";
import styles from "./styles.module.css";
import Translate, { translate } from "@docusaurus/Translate";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import type { BlueskyMetadata, BlueskySiteConfig } from "./useBlueskyEngagement";

interface Props {
  metadata: BlueskyMetadata;
}

export default function BlueskyPost({ metadata }: Props) {
  const { siteConfig } = useDocusaurusContext();
  const blueSkyConfig = siteConfig?.customFields?.bluesky as
    BlueskySiteConfig | undefined;
  const blueskyRecordKey = metadata?.frontMatter?.blueskyRecordKey;

  if (!blueSkyConfig?.handle || !blueskyRecordKey) {
    return null;
  }

  const postUrl = `https://bsky.app/profile/${blueSkyConfig.handle}/post/${blueskyRecordKey}`;

  return (
    <a
      href={postUrl}
      target="_blank"
      rel="noopener noreferrer"
      className={styles.blueskyButton}
      aria-label={translate({
        id: "bluesky.post.ariaLabel",
        message: "See the post on Bluesky",
      })}
    >
      {/* alt dropped: SVGProps has no such prop — was a no-op DOM attribute even before this
          migration, and the link's own aria-label already names the icon. */}
      <Icon className={styles.blueskyLogo} />
      <Translate id="bluesky.post.label">Like, share or comment on Bluesky</Translate>
    </a>
  );
}
```

**src/components/Bluesky/likes.tsx**

```typescript
import styles from "./styles.module.css";
import { translate } from "@docusaurus/Translate";
import type {
  EngagedPerson,
  EngagementAction,
  EngagementStats,
} from "./useBlueskyEngagement";

const MAX_AVATARS = 10;

// Bluesky facets are keyed by "liked", "reposted", "commented" — a person can carry more than one.
function describeActions(actions: Set<EngagementAction>): string {
  // Each verb is translated on its own and the list is joined here. That holds in French too
  // ("a aimé, a repartagé et a commenté"), which is cheaper than translating all seven
  // combinations as whole sentences.
  const verbs: string[] = [];
  if (actions.has("liked")) {
    verbs.push(translate({ id: "bluesky.likes.verbLiked", message: "liked" }));
  }
  if (actions.has("reposted")) {
    verbs.push(translate({ id: "bluesky.likes.verbReposted", message: "reposted" }));
  }
  if (actions.has("commented")) {
    verbs.push(translate({ id: "bluesky.likes.verbCommented", message: "commented on" }));
  }

  if (verbs.length === 1) return verbs[0];
  const and = translate({ id: "bluesky.likes.and", message: "and" });
  return `${verbs.slice(0, -1).join(", ")} ${and} ${verbs[verbs.length - 1]}`;
}

interface Props {
  stats: EngagementStats;
}

export default function BlueskyLikes({ stats }: Props) {
  if (stats.loading || stats.likes === null) {
    return null;
  }

  const shown: EngagedPerson[] = stats.engaged.slice(0, MAX_AVATARS);
  const extraEngaged = stats.engaged.length - shown.length;

  return (
    <span className={styles.blueskyPostLikes}>
      <span
        className={styles.blueskyCommentLikes}
        title={translate(
          {
            id: "bluesky.likes.likesTitle",
            message: "The original post has {count} likes on Bluesky",
          },
          { count: stats.likes },
        )}
      >
        {stats.likes}
      </span>
      <span
        className={styles.blueskyCommentReposts}
        title={translate(
          {
            id: "bluesky.likes.repostsTitle",
            message: "The original post has been shared {count} times on Bluesky",
          },
          // Only `likes` is narrowed by the guard above; `reposts` can still be null here.
          { count: stats.reposts ?? 0 },
        )}
      >
        {stats.reposts}
      </span>
      {shown.length > 0 && (
        <span className={styles.blueskyLikersAvatars}>
          {shown.map((person, index) => (
            <a
              key={person.did}
              href={`https://bsky.app/profile/${person.handle}`}
              target="_blank"
              rel="noopener noreferrer"
              className={styles.blueskyLikersAvatarLink}
              style={{ zIndex: shown.length - index }}
              title={translate(
                {
                  id: "bluesky.likes.personTitle",
                  message: "{name} (@{handle}) {actions} this post",
                },
                {
                  name: person.displayName,
                  handle: person.handle,
                  actions: describeActions(person.actions),
                },
              )}
            >
              <img
                src={person.avatar}
                alt={translate(
                  { id: "bluesky.avatarAlt", message: "{name}'s avatar" },
                  { name: person.displayName },
                )}
                className={styles.blueskyLikersAvatar}
              />
            </a>
          ))}
          {extraEngaged > 0 && (
            <span className={styles.blueskyLikersAvatarMore}>+{extraEngaged}</span>
          )}
        </span>
      )}
    </span>
  );
}
```

**src/components/Bluesky/comments.tsx**

```typescript
import { useState, useEffect, type ReactNode } from "react";
import styles from "./styles.module.css";
import Translate, { translate } from "@docusaurus/Translate";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import { fetchBlockedList } from "./useBlueskyEngagement";
import type {
  BlueskyEmbed,
  BlueskyMetadata,
  BlueskyPostRecord,
  BlueskyReplyNode,
  BlueskySiteConfig,
} from "./useBlueskyEngagement";

// Bluesky facet indices are UTF-8 byte offsets, not JS string indices.
// TextEncoder/TextDecoder ensures correct slicing for non-ASCII text (emoji, accents…).
function renderPostText(record: BlueskyPostRecord, isOwner: boolean): ReactNode {
  const text = record.text;
  const facets = record.facets || [];
  if (facets.length === 0) return text;

  const encoder = new TextEncoder();
  const decoder = new TextDecoder();
  const bytes = encoder.encode(text);

  const parts: ReactNode[] = [];
  let lastIndex = 0;

  facets.forEach((facet, idx) => {
    const start = facet.index.byteStart;
    const end = facet.index.byteEnd;

    const before = decoder.decode(bytes.slice(lastIndex, start));
    if (before) parts.push(before);

    const linkFeature = facet.features.find(
      (f) => f.$type === "app.bsky.richtext.facet#link",
    );
    if (linkFeature && isOwner) {
      // Site owner's links are trusted — render as a clickable anchor.
      parts.push(
        <a
          key={`link-${idx}`}
          href={linkFeature.uri}
          target="_blank"
          rel="noopener noreferrer nofollow"
        >
          {decoder.decode(bytes.slice(start, end))}
        </a>,
      );
    } else {
      // Other authors' links are unvetted (spam risk).
      // Render the anchor text only — the original is reachable via "View comment".
      parts.push(decoder.decode(bytes.slice(start, end)));
    }

    lastIndex = end;
  });

  if (lastIndex < bytes.length) {
    parts.push(decoder.decode(bytes.slice(lastIndex)));
  }

  return parts;
}

function renderEmbed(embed: BlueskyEmbed | null | undefined): ReactNode {
  if (!embed) return null;

  // Narrowed by property presence, not by `$type` equality: `BlueskyEmbed`'s catch-all
  // member types `$type` as a plain `string` (any other embed kind the API can return —
  // video, record quote, …), so a literal-equality check can't exclude it and `embed.external`
  // wouldn't narrow.
  if ("external" in embed) {
    const { uri, title, thumb } = embed.external;

    return (
      <a
        href={uri}
        target="_blank"
        rel="noopener noreferrer nofollow"
        className={styles.blueskyCommentEmbed}
      >
        {thumb && <img src={thumb} alt="" className={styles.blueskyCommentEmbedThumb} />}
        <div className={styles.blueskyCommentEmbedContent}>
          <strong>{title}</strong>
        </div>
      </a>
    );
  }

  if ("images" in embed) {
    return (
      <div className={styles.blueskyCommentImages}>
        {embed.images.map((image, index) => (
          <img
            key={index}
            src={image.fullsize}
            alt={
              image.alt ||
              translate({ id: "bluesky.embeddedImage", message: "Embedded image" })
            }
            className={styles.blueskyCommentImage}
          />
        ))}
      </div>
    );
  }

  return null;
}

interface FlattenedReply extends BlueskyReplyNode {
  depth: number;
}

function BlueskyComment({
  reply,
  ownerHandle,
}: {
  reply: FlattenedReply;
  ownerHandle?: string;
}) {
  const isOwner = !!ownerHandle && reply.post.author.handle === ownerHandle;
  const recordKey = reply.post.uri.split("/").pop();
  const profileUrl = `https://bsky.app/profile/${reply.post.author.handle}`;
  const commentUrl = `https://bsky.app/profile/${reply.post.author.handle}/post/${recordKey}`;
  const date = new Date(reply.post.indexedAt).toLocaleString(undefined, {
    year: "numeric",
    month: "short",
    day: "numeric",
    hour: "2-digit",
    minute: "2-digit",
  });

  return (
    <div
      className={styles.blueskyCommentContainer}
      style={{ paddingLeft: `${1.5 + reply.depth * 1.5}rem` }}
    >
      <div className={`${styles.blueskyCommentHeader} mb-2 flex items-center`}>
        <a href={profileUrl} target="_blank" rel="noopener noreferrer nofollow">
          <img
            src={reply.post.author.avatar}
            alt={translate(
              { id: "bluesky.avatarAlt", message: "{name}'s avatar" },
              { name: reply.post.author.displayName },
            )}
            className={styles.blueskyCommentAvatar}
          />
        </a>
        <div className={styles.blueskyCommentAuthorInfos}>
          <a
            href={profileUrl}
            target="_blank"
            rel="noopener noreferrer nofollow"
            className={styles.blueskyCommentAuthorDisplayName}
          >
            {reply.post.author.displayName}
          </a>
          <span className={styles.blueskyCommentAuthorHandle}>
            @{reply.post.author.handle}
          </span>
        </div>
      </div>

      <span className={styles.blueskyCommentDate}>{date}</span>

      <p className={styles.blueskyCommentText}>
        {renderPostText(reply.post.record, isOwner)}
      </p>

      {renderEmbed(reply.post.embed)}

      <div className={styles.blueskyCommentFooter}>
        <span className={styles.blueskyCommentLikes}>{reply.post.likeCount}</span>
        <span className={styles.blueskyCommentReposts}>
          {reply.post.repostCount || 0}
        </span>
        <a
          className={styles.blueskyCommentLink}
          href={commentUrl}
          target="_blank"
          rel="noopener noreferrer nofollow"
        >
          <Translate id="bluesky.comments.view">View comment</Translate>
        </a>
      </div>
    </div>
  );
}

interface PostThreadResponse {
  thread: {
    replies?: BlueskyReplyNode[];
  };
}

interface Props {
  metadata: BlueskyMetadata;
}

export default function BlueskyComments({ metadata }: Props) {
  const { siteConfig } = useDocusaurusContext();
  const blueSkyConfig = siteConfig?.customFields?.bluesky as
    BlueskySiteConfig | undefined;
  const blueskyRecordKey = metadata?.frontMatter?.blueskyRecordKey;

  const [comments, setComments] = useState<FlattenedReply[] | null>(null);
  const [error, setError] = useState(false);

  useEffect(() => {
    if (!blueskyRecordKey || !blueSkyConfig?.handle) return;

    const fetchComments = async () => {
      try {
        const postUri = `at://${blueSkyConfig.handle}/app.bsky.feed.post/${blueskyRecordKey}`;
        const url =
          "https://public.api.bsky.app/xrpc/app.bsky.feed.getPostThread?depth=5&uri=" +
          encodeURIComponent(postUri);

        // Fetch thread and moderation list in parallel — shares the sessionStorage cache
        // with useBlueskyEngagement so the second caller resolves instantly.
        const [res, listBlocked] = await Promise.all([
          fetch(url),
          blueSkyConfig?.blockedList
            ? fetchBlockedList(blueSkyConfig.blockedList).catch(() => new Set<string>())
            : Promise.resolve(new Set<string>()),
        ]);
        if (!res.ok) throw new Error("Failed to fetch post thread");
        const data = (await res.json()) as PostThreadResponse;

        const blocked = new Set([
          ...(blueSkyConfig?.blockedHandles ?? []),
          ...listBlocked,
        ]);
        const allComments: FlattenedReply[] = [];
        const flattenReplies = (arr: BlueskyReplyNode[] | undefined, depth: number) => {
          if (!arr) return;
          for (const r of arr) {
            // Skip blocked handles (e.g. spammers hidden on bsky.app but still
            // returned by the public API). Sub-replies are still walked so that
            // legitimate replies to a spam comment remain visible.
            if (!blocked.has(r.post.author.handle)) {
              allComments.push({ ...r, depth });
            }
            if (r.replies) flattenReplies(r.replies, depth + 1);
          }
        };

        if (data.thread?.replies) {
          flattenReplies(data.thread.replies, 0);
        }

        setComments(allComments);
      } catch (err) {
        // Offline, blocked by the visitor, or Bluesky unreachable: stay silent
        // rather than surface a raw error — same outcome as no comments to show.
        console.error(err);
        setError(true);
      }
    };
    fetchComments();
  }, [
    blueskyRecordKey,
    blueSkyConfig?.handle,
    blueSkyConfig?.blockedHandles,
    blueSkyConfig?.blockedList,
  ]);

  if (!blueskyRecordKey || error) return null;
  if (comments === null) {
    return (
      <p>
        <Translate id="bluesky.comments.loading">Loading comments…</Translate>
      </p>
    );
  }

  const postUrl = `https://bsky.app/profile/${blueSkyConfig?.handle}/post/${blueskyRecordKey}`;

  if (comments.length === 0)
    return (
      <p className={styles.blueskyNoCommentYet}>
        <Translate id="bluesky.comments.none">
          This post is waiting for its first comment.
        </Translate>
        &nbsp;
        <a
          className={styles.blueskyNoCommentYetCTA}
          href={postUrl}
          target="_blank"
          rel="noopener noreferrer nofollow"
        >
          <Translate id="bluesky.comments.cta">Share your thoughts!</Translate>
        </a>
      </p>
    );

  return (
    <div className={styles.blueskyCommentsContainer}>
      <h3>
        <Translate id="bluesky.comments.heading" values={{ count: comments.length }}>
          {"💬 Comments from Bluesky ({count})"}
        </Translate>
      </h3>
      {comments.map((reply) => (
        <BlueskyComment
          key={reply.post.uri}
          reply={reply}
          ownerHandle={blueSkyConfig?.handle}
        />
      ))}
    </div>
  );
}
```

**src/components/Bluesky/styles.module.css**

```css
.blueskyLogo {
  width: 20px;
  height: 20px;
}

.blueskyContainer {
  margin: 2rem 0 0.5rem;
  padding: 1.1rem 1.25rem 1.4rem;
  border: 1px solid var(--ifm-color-emphasis-200);
  border-radius: 8px;
  background: var(--ifm-background-surface-color);
}

.blueskyHeadline {
  display: block;
  font-weight: 500;
  color: var(--ifm-color-content);
  margin-bottom: 0.75rem;
}

.blueskyAccountNote {
  display: block;
  margin-top: 0.6rem;
  font-size: smaller;
  color: var(--ifm-color-emphasis-600);
}

.blueskyCommentsContainer {
  border: 1px solid var(--ifm-color-emphasis-200);
  margin-top: 1rem;
  padding: 0.4rem 0.9rem;
  margin-bottom: 1.25rem;
}

.blueskyCommentContainer {
  margin-bottom: 1rem;
  background-color: var(--ifm-color-emphasis-100);
  padding: 0.8rem;
  border-radius: 6px;
  border-left: 2px solid var(--ifm-color-emphasis-300);
  color: var(--ifm-font-color-base);
}

.blueskyCommentHeader {
  display: flex;
  align-items: center;
  gap: 10px;
}

.blueskyCommentAuthorInfos {
  display: flex;
  flex-direction: column;
}

.blueskyCommentAvatar {
  width: 32px;
  height: 32px;
  border-radius: 50%;
  margin-right: 0.5rem;
}

.blueskyCommentAuthorDisplayName {
  margin: 0;
  font-weight: bold;
}

.blueskyCommentAuthorHandle {
  margin: 0;
  font-size: smaller;
  font-weight: normal;
  color: var(--ifm-color-emphasis-600);
  display: block;
}

.blueskyCommentDate {
  margin-left: auto;
  font-size: smaller;
  color: var(--ifm-color-emphasis-600);
}

.blueskyCommentText {
  margin: 0.3rem 0 0;
}

.blueskyCommentLikes::before {
  content: "❤️\a0";
}

.blueskyCommentLikes::after {
  content: " ";
}

.blueskyCommentReposts::before {
  content: "🔁\a0";
}

.blueskyCommentReposts::after {
  content: " ";
}

.blueskyCommentLink::before {
  content: "→\a0";
}

.blueskyCommentLink::after {
  content: " ";
}

.blueskyCommentLink {
  margin-right: 0.25rem;
  display: inline-flex;
  align-items: center;
  color: var(--ifm-color-emphasis-600);
  text-decoration: none;
  margin-top: 0.25rem;
}

img.blueskyCommentEmbedThumb {
  max-height: 250px;
}

.blueskyCommentImages {
  margin-top: 0.5rem;
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
}

.blueskyCommentImage {
  max-width: 100%;
  height: auto;
  border-radius: 0.25rem;
  border: 1px solid var(--ifm-color-emphasis-300);
}

.blueskyNoCommentYet {
  color: var(--ifm-color-emphasis-600);
  font-size: 1rem;
  line-height: 1.5;
  text-align: center;
  padding: 20px;
  background-color: var(--ifm-color-emphasis-100);
  border: 1px solid var(--ifm-color-emphasis-300);
  border-radius: 8px;
  margin: 20px 0;
}

.blueskyNoCommentYetCTA {
  font-weight: bold;
  color: var(--ifm-color-primary-dark);
  cursor: pointer;
  text-decoration: underline;
}

[data-theme="dark"] .blueskyNoCommentYetCTA {
  color: var(--ifm-color-primary-light);
}

.blueskyPostLikes {
  display: inline-flex;
  align-items: center;
  gap: 0.4rem;
}

.blueskyLikersAvatars {
  display: inline-flex;
  align-items: center;
  margin-left: 0.4rem;
}

.blueskyLikersAvatarLink {
  margin-left: -1rem;
  line-height: 0;
}

.blueskyLikersAvatarLink:first-child {
  margin-left: 0;
}

.blueskyLikersAvatar {
  width: 40px;
  height: 40px;
  border-radius: 50%;
  border: 2px solid var(--ifm-background-color);
  display: block;
}

.blueskyLikersAvatarMore {
  margin-left: 0.4rem;
  font-size: smaller;
  color: var(--ifm-color-emphasis-600);
}

.blueskyEngagementRow {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
}

.blueskyButton {
  align-items: center;
  background-color: var(--ifm-color-emphasis-200);
  border-radius: 6px;
  border: 1px solid var(--ifm-color-emphasis-300);
  box-shadow: none;
  color: var(--ifm-font-color-base);
  display: inline-flex;
  font-size: 0.9rem;
  font-weight: 400;
  gap: 0.4rem;
  margin-bottom: 0.8rem;
  margin-right: 0.4rem;
  padding: 0.4rem 0.9rem;
  text-decoration: none;
  transition:
    background-color 0.2s ease,
    color 0.2s ease;
}

.blueskyButton:hover {
  background-color: var(--ifm-color-primary);
  border-color: var(--ifm-color-primary);
  color: white;
}
```


---