Skip to content

Bluesky for comments on mkdocs blog

Background

I have recently migrated this blog from Jekyll to Mkdocs using material theme. I was also planning to move away from Disqus commenting system given all the known issues and just when I had finished the migration to Mkdocs, there was this post from Emily Liu - which showcases how easily the bluesky replies to a post can be added in comments section of a blog page. Followed closely by this, was a post from Cory Zue who created NPM packaging.

I initially was looking to use that on my blog and while searching for that package on jsdelivr, I came across the bluesky-comments-tag: a package created by Matt Kane. I understood the code behind this one much better and that was my starting point. There were two problems with the solution thus far that I wanted to solve.

Problem Description

For the comments to appear on the blog, the bluesky post url needs to be added to the frontmatter. Now that is a cyclic process because you can't post the url of your blog post on bluesky until you have published it.

This, I have solved to an acceptable flow as shown below and the "How?" is explained in this post.

Open Blogpost in browserCopy the BlogPost URLReduced but still additional stepsOpen Bluesky websiteAlgorithm 1. Take the blog post URL active in the browser. 2. Search on bluesky for the oldest post created by the author containing this URL. 3. Use that URL to display comment thread. 4. If no such URL is found, display the message: `No Bluesky Comments thread found for this post.`Login and create a new postPaste the copied Blogpost URL in this postPublish the postComment Section is activated

Create BlogpostPublishAdditional StepsThis becomes all too cumbersome and I would much ratherthe comments were visible after the blog post was publishedand if the bluesky post existed for that blog post URLwithout the need for all these additional steps.Open Blogpost in browserCopy the BlogPost URLOpen Bluesky websiteLogin and create a new postPaste the copied Blogpost URL in this postPublish the postCopy the Bluesky Post URLOpen Blogpost filePaste the Bluesky Post URL in frontmatterRepublish the BlogpostComment Section is activatedcomments thread activated on blog post

Second part of the problem is that while the 'acceptable flow' removes need to republish the blogpost, it still means that unless the author has created a bluesky post, comments are not open for that blog post. I am working on a way to automate that using blusky API but it is still very much work in progress.

create a blog postpublish the blog posttrigger creation of bluesky post automaticallycomments thread activated on blog postyesPost deployed?

Obtain your DID

DID is short for Decentralized identifier.

  1. Step1: Login to you account on https://bsky.app/

  2. Step 2: Click "Settings".

    Click "Settings" ....

  3. Step 3: Click "Account".

    Click "Account" ....

  4. Step 4: Click "Handle".

    Click "Handle" ....

  5. Step 5: Click "I have my own domain".

    Click "I have my own domain" ....

  6. Step 6: Now on resulting screen copy the value shown against did

    Click "Enter the domain you want to use...

  7. Step 7: Then press Cancel.

    Click "Cancel" ....

Javascript

The required javascript for this code is available in the repo of my blog here. Copy all the content which will be following:

docs/assets/js
js
 |-- src
 |    |-- BlueskyComments.js
 |-- bluesky-comments.mjs
 |-- custom-elements.json

What does this script do?

  1. The function loadComments is where bulk of the magic happens.
  2. This function first obtains the URL of the webpage and extracts pathname and discards the # part.
  3. It then creates an assembled URL which concatenates my blog domain with the pathname.
  4. It then searches on bluesky URL against my DID for the oldest post that has the URL for this blog post on it.
  5. If it finds one, it passes it further to then get the thread and replies etc.
  6. If it does not find any post, it checks if the bsky value from frontmatter is a valid bluesky URL and if so it tries using that to obtain thread.
  7. If neither value was available, it displays No Comments thread found for this post under comments section until such time that a post is created on bluesky by the account being used to host comments.

Modify javascript

Now, in order to achieve step 2 of algorithm Search on bluesky for the oldest post created by the author containing this URL I have done some bit of hardcoding. I can do away with it in due course but for the moment, anyone planning to reuse the code, must modify it, specifically the highlighted lines below:

/docs/assets/js/src/BlueskyComments.js
156
157
158
159
160
161
162
163
164
165
166
167
168
async #loadComments() {      
  // Get the current URL
  const currentUrl = window.location.href;
  // Create a URL object
  const deconstructedurl = new URL(currentUrl);
  // Extract the pathname and hash
  const extractedPart = deconstructedurl.pathname //+ deconstructedurl.hash;
  console.log(extractedPart); // Output: "/2023/03/29/read-excel-csv-recursive.html#displays-extracted-output"
  const assembledUrl = "https://mgw.dumatics.com"+extractedPart // (1)
  console.log(assembledUrl)

  const query = encodeURIComponent(assembledUrl);
  const author = encodeURIComponent("did:plc:y24b7ow3kvvkm6lpgcbh2j2o"); //(2)
  1. Change this to your own domain
  2. Change this to your own did.

CSS

Make sure you update your extra.css so the comments match your theme colours. The css rules associated with bluesky comment are ,clearly marked in docs/assets/stylesheets/extra.css on my repo. However, specifically following rules must be added / adjusted to ensure light and dark theme work well:

light theme
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
:root {
  /* Default Bluesky commenting*/
  --bluesky-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
  --bluesky-font-size: 16px;
  --bluesky-text-color: #333;
  --bluesky-handle-color: #888;
  --bluesky-footer-text-color: rgb(111, 134, 159);
  --bluesky-bg-color: #fff;
  --bluesky-hover-bg: #f0f0f0;
  --bluesky-spacing-xs: 6px;
  --bluesky-spacing-sm: 10px;
  --bluesky-spacing-md: 14px;
  --bluesky-spacing-lg: 19px;
  --bluesky-avatar-size: 36px;
  --bluesky-avatar-bg: #e0e0e0;

  /* Comments Structure */
  --bluesky-reply-border-width: 2px;

  /* Footer */
  --bluesky-footer-font-size: 15px;
  --bluesky-icon-size: 18px;
  --bluesky-border-color: #ef7109;
}
dark theme
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
[data-md-color-scheme=slate] {
    /* For bluesky comments */
    --bluesky-bg-color: hsla(var(--md-hue),15%,14%,1);
    --bluesky-font-family: system-ui, sans-serif;
    --bluesky-font-size: 16px;
    --bluesky-text-color: #cdd6f4;
    --bluesky-handle-color: #a6adc8;
    --bluesky-footer-text-color: #7f849c;
    --bluesky-border-color: #ffa724;
    --bluesky-hover-bg: #181825;
    --bluesky-spacing-xs: 6px;
    --bluesky-spacing-sm: 10px;
    --bluesky-spacing-md: 14px;
    --bluesky-avatar-size: 36px;
    --bluesky-avatar-bg: #313244;
    --bluesky-reply-border-width: 2px;
    --bluesky-footer-font-size: 15px;
    --bluesky-icon-size: 18px;
}

There are also some css rules specified in BlueskyComments.js that can be seen by clicking on this link and will need to be modified depending on the theme in use.

Comments Template

Now, my comments template currently has some code that ensures the comments from disqus are displayed if needed but assuming that a typical deployment would only need bsky comments, following code should suffice.

Important

Please do make sure you remove space after first curly bracket in each of the highlighted lines so { % becomes {% and { { becomes {{. Refer to code in my repo for clarity.

overrides/partials/comments.html
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{ % if page.meta.bsky %}
<h2 id="__comments">
  <span class="twemoji" style="margin-right: 10px;">
    { % include ".icons/fontawesome/brands/square-bluesky.svg" %}
  </span>
  { { lang.t("meta.comments") }}
</h2>
<script type="module" src="{ { '/assets/js/bluesky-comments.mjs' }}"></script>
<bluesky-comments url={ { page.meta.bsky }}>
</bluesky-comments>
{% endif %}

Tip

This ofcourse means that in your frontmatter of the post, there must be an entry for bsky.

For example, frontmatter of this post is:

post fronmatter
title: "Bluesky for comments on mkdocs blog"
slug: "bluesky-for-comments-on-mkdocs-blog"
date: 
  created: 2024-12-10 21:57:00
bsky: true

Update mkdocs.yml

Finally, update the mkdocs.yml to include the javascript and css files, like so:

mkdocs.yml
extra_css:
  - assets/stylesheets/extra.css

extra_javascript:
  - assets/js/bluesky-comments.mjs

This should then get the comments thread from bluesky on your mkdocs blog or documentation site. Do let me know if something is not working and I will try to help troubleshoot.

Comments