Deep Thoughts | Deep Thoughts

Rising community at tomorrow's horizon

Tue, 03 Mar 2026 00:00:00 GMT

Here I am. Thoughtfully sitting like the French sculptor Auguste Rodin imagined “The Thinker” (Le Penseur) in the late 19th century. Thinking about how to write a blog post which should express deepest gratitude, but unable to find the right words to do so.

Projects come and go. They develop; they move on. Sometimes they finish, but often they don’t - especially personal or side projects. But they rarely evolve at light speed. They rarely explode. Nuke the entire ecosystem with their majesty. Rise like a superhuman. Unite. Shine. And inspire. Bring together what was thought far apart. Combining thoughts of hundreds through vision. Making the impossible possible. Sometimes I feel like I should have become a poet. Until I publish my content… and I realize that tools like npmx are the ink for my digital poetry.

Poetry or not aside: I recently discovered a newly forming community of talented people, connected by the vision of creating a fast and modern browser for the npm registry. What sounds simple on paper - or should I say in the README.md - got features added more quickly than it takes Nutella to sell 1,000 jars of their hazelnut cocoa spread; worldwide — goes without saying. In the early days - before people needed vacation (if you know you know), the young project’s main branch struggled to keep up with all the good stuff called “commits” in our world that came around every 37 minutes, 24/7. I wouldn’t have been amazed if GitHub had spun up a dedicated Azure data centre just for our commitment.

Now what actually is npmx? For those just discovering it, npmx is a lightning-fast, modern browser for the npm registry, reimagining how developers explore and discover packages. It doesn’t host the package itself, it’s just a way to interact with all the awesome npm packages you already love. The community plays a very important role, and we define the features we want to have ourselves. The project started with Daniel Roe asking people on Bluesky for what they wished npmjs.org had, without explaining the reason for his question. This way, a handful of useful features for maintainers and consumers like managing, comparing or even liking packages made their way from ideas to reality. It’s really impressive what people can build together when they have a common belief, unbounded by possibilities, formed by imagination.

While many faces were familiar, the sheer number of developers, designers, security and a11y experts, organisers, sponsors and all other professionals that I didn’t even know existed before was just mind-blowing. ¡Ay! ¡Estoy abrumado! I am definitely proud of what we have already achieved. And I am looking forward to what we will achieve. As developers, but much more as a community. I am here to stay!

Leave a comment or two, depending on how talkative you are 👋

🔗 Resources

npmx.dev - The official npmx website
Announcement Post - Read the official alpha blog post
Documentation - Get started with npmx
Discord Server - Chat with the community
Vacation - One-week break; Discord offline

Recommended Git Config

Fri, 27 Feb 2026 00:00:00 GMT

In order to optimize my git workflow, specifically for GitHub, I present you with some configs and tricks that I set up.

Automatic rebase

Since I like to keep my commit history linear, I personally prefer to rebase instead of merge when I pull new changes from the remote repository. This means that if I run git pull, it will not perform a fetch and merge but rather a fetch followed by a rebase, which results in my local commits being automatically included on top of the remote commits coming in. That way, I avoid having merge commits that would IMHO pollute the history.

If you want to try this out yourself, use the --rebase parameter on pull like that:

git pull --rebase

If you feel happy with this workflow, you can set it in your global config, so you don’t need to include the --rebase option anymore:

git config --global pull.rebase true

Default branch: `main`

By default, git often initializes new repositories with master as the primary branch. However, most modern platforms (especially GitHub) have moved towards using main. Instead of renaming your branch every time you run git init, you can tell git to use main globally by default:

git config --global init.defaultBranch main

Adding co-authors

I really like to credit people who contributed in any way to my commits. What I find annoying, however, is that you have to know the GitHub email address of the user you want to Co-author. I used to go to the people’s profile, search for a recent commit they made and appending .patch to the GitHub commit URL. In the diff that you get this way, you can manually extract the email of the user. But why should I manually do this 1min work if I could spend 10h automating it?

Sorry, I just had to include those two legendary xkcds in here.

So I created a little bash script which simplifies adding Co-authors to your commits. All you need is gh and jq installed, and the little bash script below.

brew install gh jq

sudo apt install gh jq

Save this bash script as git-ucommit to a folder that is in your $PATH (like ~/bin or /usr/local/bin) and make it executable with chmod +x ~/bin/git-ucommit:

~/bin/git-ucommit

#!/usr/bin/env bash

# Check for dependencies
if ! command -v gh &> /dev/null || ! command -v jq &> /dev/null; then
    echo "Error: 'gh' (GitHub CLI) and 'jq' are required."
    exit 1
fi

args=()
usernames=()
message=""

# Parse arguments
while [[ $# -gt 0 ]]; do
  case "$1" in
    -u|--user)
      usernames+=("$2")
      shift 2
      ;;
    -m|--message)
      message="$2"
      shift 2
      ;;
    *)
      args+=("$1")
      shift
      ;;
  esac
done

trailer_args=()

# Resolve GitHub usernames to Co-authored-by trailers
for user in "${usernames[@]}"; do
  user_json=$(gh api users/"$user" 2>/dev/null)
  if [[ $? -ne 0 ]]; then
    echo "Warning: Could not find GitHub user '$user'. Skipping."
    continue
  fi

  name=$(echo "$user_json" | jq -r '.name // .login')
  id=$(echo "$user_json" | jq -r '.id')
  email="$id+$user@users.noreply.github.com"

  trailer_args+=(--trailer "Co-authored-by: $name <$email>")
done

# Execute the commit
if [[ -n "$message" ]]; then
  final_msg=$(echo -e "$message" | git interpret-trailers "${trailer_args[@]}")
  git commit "${args[@]}" -m "$final_msg"
else
  # No -m flag? Inject trailers and open the editor
  git commit "${args[@]}" "${trailer_args[@]}" -e
fi

Since the file name starts with git-, you do not even need to create a git alias, as it is smart enough to detect your executable and just allows you run:

git ucommit -m "fix: suggestions" -u trueberryless -u delucis

I myself integrated this functionality into my nix-darwin setup. Check out my Nix module if you can profit from this setup.

Summary

🔄 Automatic Rebase on Pull

git config --global pull.rebase true

Sets your global configuration to perform a rebase instead of a merge when pulling. This keeps your git history linear and avoids unnecessary merge commits.

🌱 Modern Default Branch

git config --global init.defaultBranch main

Ensures every new local repository you initialize starts with main instead of master, aligning your local environment with GitHub’s defaults.

👥 Simplified Co-Authoring

git ucommit -m "message" -u <username>

Uses a custom bash script alongside gh and jq to automatically resolve GitHub usernames to the correct “Co-authored-by” trailers, saving you from manual email lookups.

Resources

Here are some helpful resources for optimizing your Git and GitHub workflow:

That’s it! With these tweaks, your local environment stays modern, your history stays clean, and giving credit to your collaborators becomes a breeze. Happy coding!

Uncommon Git Commands

Thu, 26 Feb 2026 00:00:00 GMT

I like to use the git CLI. I have tried UIs like GitKraken, Fork or GitHub Desktop. I don’t like them.

The majority of commands can be remembered after a short amount of time because you use them daily. However, there are some commands you only need here and there, which makes them really difficult to memorize. Every time I need them, I haven’t used them for so long that I forget which option it was. Then I have to look them up again, feeling frustrated and uncool for not knowing Git by heart. It’s embarrassing.

So I decided to write this little post, which doesn’t help memorizing them, but I’ll always know where I can look them up quickly 😅

Checkout a remote branch on fork

When contributing to open source, it is common that you want to checkout a branch of the upstream branch, that doesn’t exist in your remote fork yet. Neither does it exist in your local repository. Now when it comes to checking out a remote branch on a local repository, git switch is your friend. Just remember to fetch the upstream, so git knows the reference you want to track. However, what if the branch is not in your remote repository - your fork.

I usually have set up the original remote repository as the upstream repo locally, which can be done with:

git remote add upstream https://github.com/<org>/<repo>

With this information, git can then fetch the upstream:

git fetch upstream

And now comes the magic: Create and checkout a branch, that until then only exists in the original remote repo with:

git checkout -b <branch> upstream/<branch>

I know that it is pretty annoying that you have to specify the branch name two times, but in theory you could name the local branch differently.

Also don’t forget that this branch does not yet exist in your remote fork, but you can push it easily with:

git push -u origin <branch>

Rename the commit message of an older commit

If you want to rename the last commit, just use:

git commit --amend

When you already have multiple local commits, you have to start an interactive rebase with:

git rebase -i HEAD~3

Here, 3 is the number of commits you want to adapt. If your commit is back 10 commits, you need to put a 10 there instead.

Git will open your favourite editor with some text like:

pick 64e085f Commit Message 1
pick e5f607a Commit Message 2
pick a9b0c1d Commit Message 3

You can now edit this text like a normal file and replace all the pick keywords where you want to change the commit message with reword. After you save and close the file, git will repeatedly open text files with the old commit message, which you can freely edit to your likings. After you adapted everything you wanted and close the last file, the rebase is finished and you can check your corrections with:

git log --oneline

Interactive rebasing is incredibly useful, as other options like squash, break or even exec are available. Just keep in mind that it makes more sense to do this on a branch where only you work to avoid team friction.

Clean up local branches

When a PR is merged, the branch is usually deleted after it is safely merged into the default branch. But the branch still exists locally. If you want to delete all the local branches, which got deleted in your remote repository, you can run this command in most shells (use wsl on Windows):

git fetch -p && git branch -vv | awk '/: gone] / {print $1}' | grep -v '^\*$' | xargs -I{} git branch -d "{}"

Remove tracked files with .gitignore

We’ve all been there: you create a config.json or a .env file, write some code, and commit it. Later, you realize that file should definitely not be in the repository, so you add it to your .gitignore.

The problem? Git is already tracking it. Adding a file to .gitignore only stops Git from tracking new files. To tell Git to “forget” a file it is already tracking without deleting it from your hard drive, you use the --cached flag:

git rm --cached <file_path>

If you accidentally committed an entire directory (like node_modules or dist), you can do it recursively:

git rm -r --cached <folder_name>/

If your repository has become a bit of a mess and you want to “reset” the tracking for everything to strictly follow your current .gitignore rules, run this sequence from the repository root:

git rm -r --cached .
git add .
git commit -m "Refactor: apply .gitignore to all tracked files"

This removes everything from the index and adds it all back. Because the files are now in your .gitignore, Git will simply skip over them during the add step, effectively untracking them.

Summary

🛰️ Track Upstream Branch

git fetch upstream && git checkout -b <branch> upstream/<branch>

Fetches the latest references from the original repository and creates a local branch that tracks the upstream version in one logical flow.

🔄 Rename Older Commits

git rebase -i HEAD~n

Use this to rewrite history. In the interactive editor, change pick to reword for any of the last n commits you want to modify.

🧹 Prune Local Branches

git fetch -p && git branch -vv | awk '/: gone] / {print $1}' | grep -v '^\*$' | xargs -I{} git branch -d "{}"

A pipeline that identifies local branches whose remote counterparts have been deleted (“gone”) and attempts to delete them safely.

🧺 Untrack “Ignored” Files

git rm --cached <file>

Removes files from the Git index while keeping them physically on your disk. Essential for when you added a file to .gitignore after it was already committed.

Resources

Here are some helpful resources for learning git and other situations you often find yourself in:

That’s it for now, more useful uncommon git commands might be added in the future!

What open source really is about

Fri, 20 Feb 2026 00:00:00 GMT

tl;dr

Have fun.

Freedom

You could stop reading right now. Contributing to open-source projects is not about creating a reputation. It doesn’t bring you any fame. You can’t force yourself to create, write or refactor code just for the sake of helping out. Although it might seem that many projects can only be sustainably maintained through more contributors, the additional effort for maintainers to review pull requests that got created due to the need for recognition actually slows down progress as those maintainers have to invest their time into analysing your code. And don’t even get me started with vibe-coded issues or code changes.

Experience

I am not claiming to understand open source and its contributions by any means. And I think everyone has their own opinion on that, which is totally fair because it differs depending on the communities and languages that exist. So in this post, I am gonna share my current personal opinion, which changes over time. It changes in every programmer’s lifetime with the experiences you make, socially and in terms of knowledge.

Community

Contributions are not just coding. And open source is not just about contributions. You can give value by triaging and responding to issues, commenting on discussions, continuously improving workflows, updating dependencies, supporting others with the knowledge you have already learned, or really any non-code contribution as long as you interact with the people in a friendly way. Software is shaped by the people that build it. And you can help build this community around it.

Motivation

Programming in this sense is the challenge of self-discovery. You have to find what you love. You gotta do what interests you. Your motivation is the only substance that allows you to perform at your best. But you may not know what motivates you from the beginning. Sometimes discipline beats motivation. Some people discover their passion through the discipline of showing up. Not everyone knows what they love from the start.

Journey

Start simple. Notice a docs typo, share personal feedback in a discussion, report an issue you stumbled upon in your own projects or just get in touch with the people of the community to see if this is the place you would like to be. Nobody is perfect, and neither are most first contributions - even from people who later become maintainers. And you will get a warm welcome even if you make mistakes because that’s human. Just avoid over-relying on AI to do the work for you. Learning the codebase yourself is part of the journey. Not every PR will be accepted, and that’s okay. Sometimes the timing isn’t right, or the approach doesn’t fit the project’s vision.

Reciprocity

If open-source software has helped you in your journey, contributing back helps sustain the ecosystem we all benefit from. When you are working at a company, it makes sense to suggest sponsoring the projects you depend on. Because if maintainers can focus full time on keeping the software up-to-date via financial support, they will not consider changing the FOSS license to a commercial one. If everyone thought this way, everyone would be better off.

Interest

One thing I noticed during my contributions is that maintainers generally appreciate contributions which actually affected you. This might sound obvious for some of you, but it is a crucial detail my past self also forgot to care about. Fixing issues you didn’t encounter yourself can help you learn to recognize common design patterns. They are also useful if you want to get started with a project, on your way to finding your passion with discipline. However, by doing so you give yourself the huge disadvantage of not knowing the motivation behind it.

Enjoyment

And I think that this detail sets apart “good” from “bad” developers. The former ones do not try to be the best, they just mostly do the stuff they enjoy. Open-source projects are created in people’s spare time for a reason. I couldn’t bear writing software in my free time which doesn’t affect me. But I somehow manage to sit down after a full work day, still having the strong will to submit yet another pull request to my favourite open-source project. Because I have fun doing so!

Feel free to share this post with the people you think could benefit from it.

Comparing minor features of Spotify and YouTube Music

Tue, 25 Nov 2025 00:00:00 GMT

Since Spotify recently updated their prices across all available premium plans, I decided to test out one competitive platform: YouTube Music from Google.

While many reviews and comparisons focus on the major differences, like price, algorithms, music recommendations, playlist creations and other promoted features by those platforms (including garbage AI features), this post focuses on unnecessary comparisons between little things most people don’t care about.

Crossfade

Spotify has made me love a simple but yet so powerful feature called “Crossfade”. It allows users to personalize how many seconds (0-12s) between the current and the following song should be overlapped to reduce “non-playing” time because many songs lower the volume in the end, so you don’t strictly benefit listening to the potential silence.

YouTube Music doesn’t offer such functionalities and there are also many other features I wish to see in more streaming platforms that Spotify has built upon the years:

Listening to music together with Jams
Generating new playlists from single tracks
Add one song to multiple playlists at the same time

Shuffle

While for hard-core reddit users and maybe even intermediate music enthusiasts it is probably common knowledge that the Spotify shuffle algorithm is completely broken and unfair towards lesser known artists, Spotify recently added a new “Fewer Repeats” shuffle mode, which ironically is enabled by default as if Spotify is admitting that its old algorithm is less recommendable. Whether the option between the new and the old, now so-called “Standard” shuffle adds more confusion or finally satisfies all users that have been begging for such a seemingly simple fix for multiple years by now, will yet have to be decided by each individual listener.

While it might seem for most YouTube Music listeners that the shuffle algorithm of their streaming platform “just works”, in my opinion the UX is far from perfect. The option to shuffle a playlist or album with one click is nowhere near to be seen because you either need to always listen to the first song of your playlist before being able to activate shuffle or you need to fumble around to find the hidden menu item “Shuffle play” with winter gloves. Definitely more convenient in Spotify where shuffle stats are saved between plays, respecting your preference much better.

Volume

This is clearly the only section where YouTube Music leads the way in my opinion, while sacrificing your hearing ability at the same time. Although Spotify allows to configure the maximum volume deeply nested in the settings somewhere (Settings → Playback → Volume Controls → Volume Level) with three different options: Quiet, Normal and Loud, I am really dissatisfied that Loud on 100% is equivalent to about 80% of the non-customizable YouTube Music volume. And while I get that too loud listening activities are just simply bad for your health - no debate about that -, we all know that everyone once was in their 20s where we don’t care about our hearing capabilities in later life.

Adding songs to playlists

I know there are a lot of people out there that have never created their own playlist as streaming services already offer great managed playlists with your music style ready to be saved to your library. Nonetheless, I am this kind of guy who wants to believe that they have control over their own playlist and when I discover a new song, I want to add it to all of my playlists where this song fits into. Spotify made some huge but in my opinion very beneficial redesigns of exactly this process. Therefore, they now offer a great overview where you can ideally manage the songs in your playlists.

In YouTube Music, songs have to added one-by-one to your playlists which is a tedious process if you have around 20 playlists that are based on moods and one song usually fits into multiple moods or lets say categories.

Mixes and Smart Shuffle

Both music services offer quite good options for enhancing your static playlists with similar songs if you feel like discovering new songs that would fit besides known and loved ones. Spotify once again gives you much more options however, as there is the “Smart Shuffle” mode which temporarily adds those songs to your playlist until disabled. Moreover, they have the “Go to song radio”, which generates a whole playlist based on the song you currently vibe most to. This playlist can then optionally be saved to your library of course. On YouTube Music, the radio feature is called “Start mix” which just puts similar songs into the queue, not allowing you to save the awesome mix as a playlist.

To confuse you even more, Spotify also offers a “Mix” feature on playlists that allows complete customization of the transition between songs with equalizers, fade-ins and -outs, bpm controll and some more features I do not understand as a casual listener. Although this might be very cool for transition lovers and DJs starters, I personally can not see any potential benefit for normal music lovers and would much more prefer to be able to loop over specific parts of songs instead, which would be super helpful if the hook of one song is extremly good, but you don’t like the boring rap part in between.

Track Sorting

Yes, the order of my tracks in my playlists matter. Spotify and YouTube Music offer great ways to sort your playlist, with Spotify once again offering more flexibility by allowing sorting by title, artist, album and date added. YouTube Music really thinks that dates are everything I care about — well maybe I do.

Playlist Sorting

Not so important for most people I would assume, but still relevant enough to be written about in this post of untalked features: Spotify once again allows to order your playlists, albums and artists in your library by recent listening activity, recent song additions, title and also creator. Plus they offer pins so you can always expect to hit your favourite playlist when you know the positioning by heart. This seems like a little advantage but trust me, the speed difference is incredible.

Talking about speed, YouTube Music offers the “Speed dial” which are basically pins but on your Home tab (?) It takes some time to get used to, especially since other playlists are already listed on the home page above your speed dial, which one could argue makes them more quickly accessible with your thumb. Nonetheless, sorting playlists in my library should be a must-feature. And sorry if I am just too stupid, but I still don’t understand what the difference between “Recent activity” and “Recently played” is supposed to be, especially when you consider the third option: “Recently saved”. YouTube Music should really think about their DAU (Dumbest Assumable User) or offer info boxes. Either way, removing one of those three options and adding alphabetical order would be my recommendation for improvements.

Library Filtering

Not much to write, I really enjoy the UX and UI design of both YouTube Music and Spotify. Both offer wunderful tabs for playlists, artists, albums and more that each offer “sub-filtering” as I like to call it, e.g. “Subscriptions” or “By you”, “By Spotify” and “Downloaded”, respectively for YouTube Music and Spotify. As you can once again see, Spotify simply offers more and they feel smarter and also faster. Not sure why the YouTube Music tabs have a little .5s delay, but it ruins the flow of picking a little bit.

Lyrics

In general, it feels like YouTube Music offers lyrics on more songs than Spotify, but I didn’t run any fancy benchmarks. Both services are largely accurate compared to what I believe is sung. Since I have been using Spotify for much longer now, I can only remember mismatches on the former platform. However, AFAIK lyrics are provided by Musixmatch and Spotify offers somewhat okay-ish ways to report wrong lyrics. Personally, I would love to be able to also suggest the correct lyrics when submitting feedback, as how should Musixmatch know which part of the lyrics are the reasons for my reporting action.

YouTube Music probably has the advantage in this point since they use both Musixmatch and LyricFind and as I know Google probably some additional AI comparison to fill the gaps.

Discoverability

YouTube Music people mostly rave about the awesomeness of the YouTube algorithm and its understanding of your liking which leads to better discoverability of new songs. Admittedly, the algorithm of Google even after a short time of usage feels much more suited than what Spotify would have been able to learn from my habits for over three years now, which is incredible on the one hand but totally understanable and comprehensible on the other hand, given that Google almost exclusively makes billions of dollars every year thanks to nearly perfect advertisment match-making. What I try to say is: Google has the advantage because their business model relies on a secret, yet powerful algorithm, while Spotify’s primary selling point is simply Spotify. Correct me if I’m wrong in the comments, pls!

As a result, YouTube Music has the better algorithm and understands very well what you want to listen to at any point in time. Their recommendations are delightful and therefore, the discoverability of new songs feels like sensory overload. Spotify’s recommendations are decent, once in a while I really listen to new songs that I actually enjoy and save into at least five playlists at once thanks to the overview feature.

Integrations and Ecosystem

And now the final argument, why - as you might have noticed - I prefer Spotify over YouTube Music: The fr*cking ecosystem of Spotify. While many talk about the obvious advantage of syncing what you currently play between all your devices and having (almost*) full control of what you play on another device, which is pretty cool, I am writing about the little benefits here: The Raycast Spotify integration makes controlling music while working on my MacBook extremely fun and enjoyable. stats.fm just produces awesome daily, weekly, monthly and overall stats about my listening activity on Spotify: I know exactly, how many times I have listened to each song and if I continue to list advantages of stats.fm the post would be twice as long. Nonetheless, I have to mention the weekly creation of amazing looking images with my top artists and songs of the week.

*: The one thing I miss when controlling music from another device on Spotify is volume controll. When my headphones are connected to my phone and I work on my laptop, I want to be able to control the volume nonetheless. I understand that this is another topic when joining a jam, where only the host should be able to control the volume to avoid trolls, but within my own devices, this seems like a reasonable feature.

YouTube Music doesn’t offer any cool stats, the Raycast integration needs the YouTube Music “app” (it’s a wrapper of the webpage) downloaded which doesn’t even work when using nix-darwin. Public API endpoints would really benefit YouTube Music to allow third-party apps to visualize your music habits.

And even more important, the integrations that exists (obviously with YouTube itself) are terrible. Google doesn’t split my music and the videos I watch in any reasonable way. I mean: Why on earth would I want to see all my library playlists on my YouTube profile and have to scroll all the way down to finally be able to find the “Watch Later” video playlist ?!? If I wanna watch videos, I wanna go into the YouTube app and if I wanna listen to music, I wanna go into the YouTube Music app. It’s that simple. No need for some automatically generated YouTube Music playlist “Liked music”, which shows YouTube videos that are by pure coincidence also music videos at the same time. I understand that this separation is really hard, as the two platforms evolved as one and are now supposed to serve two different purposes. But Google charges the apps separately, so the should also provide this separation in the apps. This is the point where I think about adding a “Rage” tag to the post.

To be fair: YouTube Music offers a simple toggle under Settings → General → “Show your liked music from YouTube” which allows users to filter your “Liked music” playlist for only tracks you liked on YouTube Music. However, the other way around for whole playlists would also be very beneficial. I simply don’t want to see my music playlists on my YouTube profile, private or public, whatever.

Stats for nerds

My ratings (stars or whatever you want to imagine):

Spotify: 9/10
YouTube Music: 6.5/10

Distribution of points from this post (by heading):

Spotify: 8/11 (Crossfade, Shuffle, Adding songs, Mixes, 2x Sorting, Filtering, Ecosystem)
YouTube Music: 3/11 (Volume, Lyrics, Discoverability)

Conclusion

Spotify offers way more customization, flexibility and settings. YouTube Music just knows what you want to hear.

All in all, I find it pretty sad that the music industry is so broken, where artists need 1000x more listeners to achieve the same profit compared to hard copies like they were available before I was born. And since the whole industry is basically controlled by the ‘Big Three’ - Universal Music Group (UMG), Sony Music Entertainment (SME), and Warner Music Group (WMG) - it is impossible for Spotify to be profitable in the long run, with competitions like YouTube Music which do not necessarily need to raise prices as the companies behind all other platforms have other apps that make enough money for compensation.

To be honest, all this comparison and deep write is a waste of time, let’s just go back to gramophone records. Nonetheless, share your disagreements and maybe also your positive opinions in the comments below. Happy listening and lower the volume from time to time!

Add Additional Content to Starlight's Table of Contents

Sun, 23 Nov 2025 00:00:00 GMT

This guide shows how you can append additional content like credits, ads or additional information below to list of headings in your right Starlight sidebar.

Append content

Starlight’s table of contents can be modified by overriding the TableOfContents.astro component. Follow these steps to append a small Astro component after the existing table of contents:

Create a small Card.astro component that will be displayed after the table of contents. If you want to follow common conventions, it is recommended to create a new src/components/ folder where you can place all your components:

src/components/Card.astro

---
---

<aside class="not-content starlight-table-of-contents-aside">
    <h2>Some card!</h2>
    <p>With some text 🙌</p>
</aside>

26 collapsed lines
<style>
    .starlight-table-of-contents-aside {
        position: relative;
        background-color: var(--sl-color-gray-6);
        padding: 1rem;
        border-radius: 0.5rem;
        border: 1px solid var(--sl-color-text-accent);
        box-shadow: var(--sl-shadow-md);
        overflow-y: hidden;
    }
    .starlight-table-of-contents-aside h2 {
        color: var(--sl-color-white);
        font-size: var(--sl-text-h5);
        font-weight: 600;
        text-decoration: none !important;
        line-height: var(--sl-line-height-headings);
        margin-bottom: 0.5rem;
    }
    .starlight-table-of-contents-aside p {
        font-size: var(--sl-text-xs);
        line-height: normal;
        text-decoration: none !important;
        color: var(--sl-color-gray-3);
        overflow-wrap: anywhere;
    }
</style>

Note the usage of the "not-content" class feature provided by Starlight to make sure that Starlight’s styles for elements do not apply here as it is a custom component.

Create the TableOfContents.astro component, which will be used as the replacement of Starlight’s default table of contents component:
src/components/TableOfContents.astro
```
---
import Default from "@astrojs/starlight/components/TableOfContents.astro";
import Card from "./Card.astro";
---

<Default><slot /></Default>
<div class="starlight-table-of-contents-wrapper-container">
    <Card />
</div>

<style>
    .starlight-table-of-contents-wrapper-container {
        margin-top: 1rem;
    }
</style>
```
As you can see, the default table of contents are displayed by importing the component from Starlight and using it before our card. See the “Prepend content” section to display the card above the table of contents.

Last but not least, do not forget to set the component override in your Astro config:

astro.config.mjs

3 collapsed lines
// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
14 collapsed lines
      social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/withastro/starlight' }],
      sidebar: [
        {
          label: 'Guides',
          items: [
            // Each item here is one entry in the navigation menu.
            { label: 'Example Guide', slug: 'guides/example' },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
      ],
      components: {
        TableOfContents: "./src/components/TableOfContents.astro"
      }
    }),
  ],
});

Prepend content

If you would prefer the table of contents after your component, you need to swap the order of the elements from Step 2 above and assign margin-bottom instead:

src/components/TableOfContents.astro

---
import Default from "@astrojs/starlight/components/TableOfContents.astro";
import Card from "./Card.astro";
---

<div class="starlight-table-of-contents-wrapper-container">
    <Card />
</div>
<Default><slot /></Default>

<style>
    .starlight-table-of-contents-wrapper-container {
        margin-bottom: 1rem;
    }
</style>

The rest of the 3 steps are the same, so do not forget to complete them all!

Place content at bottom

If you want to have more spacing between your new shiny content and the table of contents, you can use some CSS tricks to achieve this. Add these global styles to the bottom of your TableOfContents.astro component to introduce two new flexboxes which will transform your card to the bottom:

src/components/TableOfContents.astro

16 collapsed lines
---
import Default from "@astrojs/starlight/components/TableOfContents.astro";
import Card from "./Card.astro";
---

<Default><slot /></Default>
<div class="starlight-table-of-contents-wrapper-container">
    <Card />
</div>

<style>
    .starlight-table-of-contents-wrapper-container {
        margin-top: 1rem;
    }
</style>

<style is:global>
    @media (min-width: 72rem) {
        .right-sidebar-panel {
            min-height: 100%;
            display: flex;
            flex-direction: column;
        }
        .right-sidebar-panel > .sl-container {
            display: flex;
            flex-direction: column;
            justify-content: space-between;
            flex: 1;
        }
    }
</style>

Mobile support

The TableOfContents.astro is only rendered when the right sidebar is visible. This is not the case on mobile devices, where the MobileTableOfContents.astro component will be rendered.

However, if you want to show your additional content on mobile devices, it is recommended to override the Pagination.astro component as adding content to the mobile view of the right sidebar would look out of place.

Here is a quick demonstration of how your custom Pagination.astro override could look like:

src/components/Pagination.astro

---
import Default from "@astrojs/starlight/components/Pagination.astro";
import Card from "./Card.astro";
---

<Default><slot /></Default>
<div class="starlight-pagination-mobile-content">
    <Card />
</div>

<style>
    .starlight-pagination-mobile-content {
        display: block;
    }
    @media (min-width: 72rem) {
        .starlight-pagination-mobile-content {
            display: none;
        }
    }
</style>

Note that the card will have much more width when displayed under the pagination than in the table of contents. So make sure to use responsive design inside your additional content.

Source code

You can also find the complete source code for all three variants on GitHub or open the project directly in StackBlitz.

Customize the "Overview" title of your Starlight Table of Contents

Sat, 22 Nov 2025 00:00:00 GMT

This guide shows how you can customize the first heading in the right sidebar (table of contents) of every Starlight page globally and individually.

Each Starlight page contains a table of contents on the right side (except if disabled). To be able to link to the top of the page, the first entry of this sidebar has the title “Overview” (as you can also see on this page’s sidebar), which can be customized globally and even on a per-page basis.

Global definition

If you want to set the title of the first table of contents entry once for all pages, you can follow these steps to achieve this for monolingual and multilingual sites:

Create route middleware to customize the data shown by Starlight.

Use this example code to configure the “Overview” title:

src/routeData.ts

import { defineRouteMiddleware } from "@astrojs/starlight/route-data";

export const onRequest = defineRouteMiddleware((context) => {
  const { starlightRoute } = context.locals;

  const overviewItem = starlightRoute.toc?.items[0];
  if (overviewItem) overviewItem.text = "Back to top";
});

If your site is multilingual, you can also assign different titles depending on the locale:

src/routeData.ts

import { defineRouteMiddleware } from "@astrojs/starlight/route-data";
import starlightConfig from "virtual:starlight/user-config";

const defaultLang =
  starlightConfig.defaultLocale.lang ??
  starlightConfig.defaultLocale.locale ??
  "en";

const translations: Record<string, string> = {
  en: "Back to top",
  de: "Zurück nach oben",
};

export const onRequest = defineRouteMiddleware((context) => {
  const { starlightRoute } = context.locals;
  const { locale } = starlightRoute;

  const overviewItem = starlightRoute.toc?.items[0];
  if (overviewItem) overviewItem.text = translations[locale ?? defaultLang];
});

Frontmatter override

In order to set the first table of contents heading to something different on individual pages, follow the steps below:

Extend your frontmatter schema in src/content.config.ts:

src/content.config.ts

import { defineCollection, z } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
    docs: defineCollection({
        loader: docsLoader(),
        schema: docsSchema({
            extend: z.object({
                overviewTitle: z.string().optional(),
            }),
        }),
    }),
};

This allows you to use the overviewTitle in your middleware like that:

src/routeData.ts

import { defineRouteMiddleware } from "@astrojs/starlight/route-data";

export const onRequest = defineRouteMiddleware((context) => {
  const { starlightRoute } = context.locals;
  const individualOverviewTitle = starlightRoute.entry.data.overviewTitle;

  const overviewItem = starlightRoute.toc?.items[0];
  if (overviewItem)
    overviewItem.text = individualOverviewTitle ?? "Back to top";
});

For the sake of completeness, here is a multilingual middleware that supports overriding on individual pages:

src/routeData.ts

import { defineRouteMiddleware } from "@astrojs/starlight/route-data";
import starlightConfig from "virtual:starlight/user-config";

const defaultLang =
  starlightConfig.defaultLocale.lang ??
  starlightConfig.defaultLocale.locale ??
  "en";

const translations: Record<string, string> = {
  en: "Back to top",
  de: "Zurück nach oben",
};

export const onRequest = defineRouteMiddleware((context) => {
  const { starlightRoute } = context.locals;
  const { locale } = starlightRoute;
  const individualOverviewTitle = starlightRoute.entry.data.overviewTitle;

  const overviewItem = starlightRoute.toc?.items[0];
  if (overviewItem)
    overviewItem.text =
      individualOverviewTitle ?? translations[locale ?? defaultLang];
});

Source code

You can also find the complete source code for all four variants on GitHub or open the project directly in StackBlitz.

How VS Code Snippets can improve your workflow when working with Astro

Tue, 28 Oct 2025 00:00:00 GMT

This article demonstrates how code snippets can be created in Visual Studio Code that can significantly boost your productivity when regularly working with Astro’s content collections.

The need for snippets

Astro supports schema validation for your frontmatter fields in Markdown and MDX files. Therefore, many content files of your collections will have the same structure between the code fences (---). If you are tired of typing the same frontmatter fields over and over again, you can create a code snippet that will automatically generate the basic structure of the desired frontmatter while letting you conveniently edit the fields with TAB ⇥ inputs.

Creating a snippet

You can create global snippets which can be scoped to multiple languages or language-specific snippets. Since we want the frontmatter snippet in Markdown and MDX files, we will create a global snippet under Code/User/snippets/markdown.code-snippets with the scope markdown,mdx. Follow the instructions in the official documentation for the correct steps for your Operating System.

Here is an example of how your snippet could look like. You can freely adjust the body or prefix as you see fit:

Code/User/snippets/markdown.code-snippets

{
  "Add Markdown frontmatter": {
    "scope": "markdown,mdx",
    "prefix": "ffmt",
    "body": [
      "---",
      "title: $TM_FILENAME_BASE",
      "description: The description",
      "---",
      "",
      "## ${1:Heading}",
      "",
      "$0"
    ],
  }
}

The flexibility of snippets allows you to create powerful and bespoke productivity boosters. You can enhance the basic configuration from above with the specific frontmatter fields you need, change how the title gets generated, and more.

Using the snippet

Create an empty Markdown (.md) or .mdx file. Start typing ffmt and press TAB ⇥ to trigger the snippet. If you do not see any suggestions, you can manually trigger them with Ctrl + Space and select the "Add Markdown frontmatter" snippet. Depending on your exact configuration, you can now tab through the fields to edit them to your current use case. For example the snippet from above allows you to directly edit the heading and then jumps to the content. The title field of the frontmatter will be set to the file name without its extension.

Further resources

If you find snippets useful and want to explore a VS Code extension which includes a decent set of preconfigured snippets, check out Astro Snippets by Shelton Louis.

Read more tips and tricks for working with Astro and Starlight on HiDeoo’s blog.

Star Days ★

Mon, 01 Sep 2025 00:00:00 GMT

1 Quick Description

A star day is a day declared one day in advance to only one cause. In a star day, everything besides daily habits, self care, and the most urgent of matters becomes noise. There only exists the topic of the day to engage with, or silence!

Unrelated thoughts as well as actions become noise unless they serve the mission.

2 Purpose

This is an attention-management strategy and not a task or time management strategy.

It is set a day in advance, where we agree on the singular attention of the day to come so that we can prepare mentally for it.

Rather than fighting to stay focused in a world of distractions, or negotiating with ourselves over what counts as a productive activity during the day. This sets the terms before the day starts. And when the day starts, we keep our head empty, and we stay mindful that all that we do and think about serves the cause agreed on beforehand.

3 On anti-productivity

Productivity is concerned with external measures of performance and delivery. Many tools focus on optimizing productivity metrics, meeting deadlines, etc.

This tool takes a different approach. It relies on internal pressure instead. Its only measure of success is singular attention. So long as you maintain full presence, you can use the best tools at your disposal. There is nothing else to it.

The section is called “anti-productivity” to signify that what truly matters is full presence with the star subject alone. Ideas on improving execution efficiency are noise in this period. It also highlights that commitment is set on a different axis from performance, and so deserves a category apart from productivity.

Productivity concerns can be reviewed later, or they can be made the star topic of the day for deliberate planning!

4 Motivation

External productivity tools often fix symptoms rather than causes. If one is not careful, they can be used to make unfocused days bearable rather than promote deep work and flow states. They can introduce planning overhead and fixation on details that may not make a big impact in the long term such as precise placement of scheduled events, or counts of to-dos done. They risk being a source of guilt to their users by putting them in a perpetual catching-up state with seemingly endless work.

But why maximize the number of to-do items completed a day, dream of an ideal of an empty to-do list, or perfectly execute a weekly schedule? What is the goal for this?

One goal is to work at our best and be fulfilled, and to be able focus on the specifics of our work and not any unnecessary scaffolding around it.

The problem begins internally, before any productivity tool is put in place. The bottleneck to flow is often in how we pay attention to the daily objects of experience and how we negotiate commitments with ourselves and others.

With low attention, the cost of multitasking and distractions becomes too high that no productivity tool can recover it. With low commitment, we may stray from our objectives, only do the easy parts, or cut corners. Star days begin from this earlier stage of experience, focusing on attention and commitment as foundations.

One cannot be behind in a star day, because all they need is full presence with the mission.

Another motivation is that by declaring an entire day for one cause, we have more incentive to put in all the effort necessary and face hardships that require high mental preparation and perseverance. This is harder to do when you’re trying to squeeze them into a 2 hour slot window. This also allows momentum to build quicker since we can absorb the problem domain more deeply than if we had no clear purpose for day.

The star topic doesn’t have to be work-related only. It could be for a hobby you’ve always wanted to start, or social activities with friends!

How to fully autogenerate Starlight sidebars (without losing control)

Sun, 17 Aug 2025 00:00:00 GMT

Have you ever wanted to simplify sidebar generation in your Starlight project? Have you tried autogenerating the entire sidebar only to find it doesn’t let you customise the structure to your needs?

This post demonstrates two Starlight features that make fully autogenerated sidebars flexible and reduce maintenance.

Use case

In medium to large Starlight projects, the problem arises that the manual creation and maintenance of the Starlight sidebar configuration is a tedious and time-consuming task.

In the past, Starlight didn’t provide the right primitives for this, and the recommended approach was to move the autogeneration of the sidebar configuration one level deeper - so that only folders without nested subfolders were autogenerated. However, with the introduction of Route Data and the more recent generateId() hook of docsLoader, these scenarios can now be solved much more easily and efficiently.

Solving the ordering issue

A common problem always was: “How can I customise the order of sidebar folders if I autogenerate the sidebar?” Old issues like #1223 suggest a solution inspired by Nuxt Content where each segment of the whole route can be prefixed with numbers + dots to determine numeric ordering on a file-based level. An example for such a project could look like this:

src/content/docs/nested-folder
- 1.frameworks
  - 1.vue.md
  - 2.nuxt.md
- 2.examples
  - 1.vercel.md
  - 2.netlify.md

If you want to use this approach in Starlight, it doesn’t work out-of-the-box, but with a simple setup you can make it work.

Starlight 0.35.0 introduced a callback function which you can pass to docsLoader() that can manipulate the id (URL) of the generated page. By splitting the entry by "/" and removing any number + dot on the segment level, you have the same functionality now in Starlight:

src/content.config.ts

import { defineCollection } from "astro:content";
import { docsLoader } from "@astrojs/starlight/loaders";
import { docsSchema } from "@astrojs/starlight/schema";

const leadingNumberAndDotRegEx = /^\d+\./;
const fileExtensionRegEx = /\.(md|mdx)$/;

export const collections = {
  docs: defineCollection({
    loader: docsLoader({
      // Remove file extension and
      // leading numbers + dot from each segment
      generateId: ({ entry }) =>
        entry
          .replace(fileExtensionRegEx, "")
          .split("/")
          .map((segment) => segment.replace(leadingNumberAndDotRegEx, ""))
          .join("/"),
    }),
    schema: docsSchema(),
  }),
};

The URL to access the pages now changes e.g., from /nested-folder/1.frameworks/1.vue to /nested-folder/frameworks/vue.

However, the folder names in the sidebar still include the 1. prefixes. So let’s solve the sidebar manipulation as well:

Starlight 0.32.0 introduced Route Data, which we can now utilize to manipulate folder names in the sidebar to

remove any leading number + dot from the folder name and
apply “Title Case” so they don’t look completely lowercase

src/routeData.ts

import { defineRouteMiddleware } from "@astrojs/starlight/route-data";

const leadingNumberAndDotRegEx = /^\d+\./;
const wordSplitterRegEx = /\w\S*/g;

function toTitleCase(str: string) {
  return str.replace(wordSplitterRegEx, (word) => {
    return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
  });
}

function cleanGroupLabels(entries: any[]) {
  for (const entry of entries) {
    if (entry.type === "group") {
      // Remove leading number + dot
      let label = entry.label.replace(leadingNumberAndDotRegEx, "");
      // Convert to Title Case
      entry.label = toTitleCase(label);
      // Recurse into children
      cleanGroupLabels(entry.entries);
    }
  }
}

export const onRequest = defineRouteMiddleware((context) => {
  const { sidebar } = context.locals.starlightRoute;
  cleanGroupLabels(sidebar);
});

Don’t forget to add the routeData.ts file to your astro.config.mjs:

astro.config.mjs

    starlight({
      title: "Autogenerate whole sidebar",
      social: [{ icon: "github", label: "GitHub", href: "https://github.com/withastro/starlight" }],
      sidebar: [
        {
          label: "Root Folder",
          autogenerate: { directory: "nested-folder" },
        },
      ],
      routeMiddleware: "./src/routeData.ts",
    }),

Of course you can adjust the code to your needs (e.g., remove the “Title Case” transformation because your file names are already written correctly).

Using HiDeoo’s plugin

If you want to autogenerate your whole sidebar and still have the flexibility to customise everything you want, HiDeoo also made a dedicated plugin for such use cases: Starlight Auto Sidebar.

Especially those two features got mentioned in this article:

Controlling the order of individual directories
Adapting the displayed label of individual folders

However, if you want to automate the whole generation without having to specify labels and orders manually for each directory, coding the solution yourself (with some guidelines in this blog) is the preferred and recommended solution.

If you want to check out the code presented in this blog, feel free to visit the StackBlitz or the source code in the GitHub repo.

Stop Outsourcing Your Soul to AI

Sun, 10 Aug 2025 00:00:00 GMT

It has been more than two and a half years since the release of ChatGPT. The 30^th November, 2022 marked the beginning of a new era. The start of AI. Nowadays, many professions and people in private lives, especially in the information technology sector, use it on a daily basis. And we do not even know where we are on the Gartner hype cycle or if AI will improve following Kurzweil’s “Law of Accelerating Returns”.

The trend is still rising, but at the same time I have noticed a slight but steady degradation of knowledge on a human basis because people delegate more and more creative work to AI. As a result, I have decided to write a little blog post, where I can share my thoughts, trying to discourage the overuse of Artificial Intelligence which would ruin our cognitive capabilities. And although I know that very little people read this, it does not stop me from trying. Otherwise, I might have missed my opportunity in helping humanities future.

Disclaimer: This whole blog post is created from my observations of developments of social changes with special focus on ways of using Artificial Intelligence with my interpretation and is therefore very opinionated. I have not looked at any studies that would support or oppose my opinion.

How people tend to use AI

AI is awesome. I do not want to question this statement. It helped and still helps me improve my workflow, gathering new knowledge, diving into new waters and exploring new technologies. For people who are not interested in how AI works, such intelligent tools seem like magic. As a result, I like to see their eyes sparkle and their mouths left open when I explain to them that everything AI is based on is probability. What word is most likely to be the next one based on properties and emotions in a highly dimensional virtual space. But that is another topic.

What I would like to focus on is how people have come to use AI, especially over the past months - if not years. Since our brains are lazy by default, we tend to outsource more work to AI the less focused we are on a specific task. In other words, if you do not put most of your commitment into your current project, you are likely on the verge of just prompting an AI with it. Another potential reason for offshoring work to the AI world is ignorance of the underlying technologies, which makes it difficult for you to come up with your own solutions.

I am by no means a scientist, but I think that watching AI doing your work - because due to your incompetence the outcome you produce is not aligning with your vision - gives you so much dopamine that your brain wants to do it more often. Moreover, the human being as a social figure always aims to be connected to somebody and engaging with AI satisfies those needs. This behaviour is typical for our brains and also happens when watching social media or consuming explicit content. It is deeply marked in our cerebral cortex and the whole gaming industry and entertainment sectors use it recklessly to optimise for money.

I noticed this trend myself, as you can clearly see from some of my posts where I admittedly used AI to help me write them. But I think this is not a shame. Every content creator who uses AI should experience first-hand the pitfalls of creating content directly for the viewer or reader, in order to realise how little they subsequently know about the topic. This will enable them to learn from their mistake and be aware of how easily laziness can lead you down such a despised path. Only the excellent among us strove for hand-crafted content all along.

Negative side effects

I pointed out the main drawbacks of using AI too extensively that I observed. I will now give you two smaller reasons I have noticed in myself for why you should not use AI for expressive work.

Communication decline

While watching a promotion video from “The Browser Company™” (see the last link in the resource section below) I noticed that visions can be very far apart nowadays. I see this trend not only in the Dia browser, but in many different aspects of technology and parts of our lives. One side of the trend wants to integrate AI everywhere possible, widening our dependence on it. One example is using AI to compose and write messages to our closest friends and colleagues because it makes us more efficient. I believe that it just makes us stupid in the long run.

If people do not train their brains for coming up with words for communication, building useful sentences and meaning that can be understood by other human beings, our very foundation of interacting with each other is broken and we would be back at the level of Homo habilis - the last species that likely did not use fully developed verbal language. See, I used AI to help me research this very bit of information, but chose my words consciously to express myself. This way, I not only learned something new, but can now also remember it. A capability you will never have when outsourcing writing to AI.

Loneliness

Being alone on a mental level is in my opinion one of the most underrated modern dangers of society. The ironic part about it is, that if everyone is alone, we all have it in common, making us not alone with each one’s loneliness. But my thoughts are wandering in other oceans again.

AI strongly encourages us to be alone. It ~~acts~~ was intentionally trained to act as a perfect friend, colleague or whatever you wanna call it. Recently I noticed that ChatGPT’s responses explicitly include my name which feels very weird on multiple layers if you ask me. One could argue that this is private artificial doxxing, which of course is a oxymoron in itself as doxxing by definition is public. Nevertheless, the more you use AI, the more often you want to use AI. Particularly after the introduction of AI voice modes this trend kept rising like there is no tomorrow. Congratulations ClosedAI, you just reinvented addiction.

In worst case scenarios, this can leads people to fear talking with other people. Abandoning friendships. Withdrawal from society. Such habits are serious problems and should best be examined by a doctor or psychologist.

Proposal of AI usage layer model

Proposing a global solution for all people of such a problem is impossible. Since each individual has their own experiences with AI, their own thoughts and feelings, optimists or pessimists, I cannot speak for everyone. In fact, I think I can only speak for myself, learn and share my own ways of handling and limiting my usage of AI and hope that those experiences can help you as well.

My ideal experiences with AI - the optimal golden way between the overuse of AI alongside cognitive erosion and letting the hype pass besides you without taking any advantage of it - is using AI iff you and only you gain any benefits. In other words, control your usage and limit it to an extreme, where only ever you should come into contact with the content the AI produces. Such a limitation has many consequences, here are some examples to better demonstrate and emphasise what I mean:

Use AI for personal learning sessions: If you initially want to dive into a new, completely unknown topic, AI can give you general overviews and show you connections to other parts of knowledge and real-world uses. While this does not necessarily mean that you really learn faster or more efficiently, it helps to take the step forward and get the ball rolling.
Use AI for stupid and repetitive workloads and ask for help if you are certain that the problem or task has already been solved thousands of times by others. Current LLMs are trained based on existing data which means they are meant to be good at solving solved problems, not reinventing the wheel, but suggesting to use the existing round instrument.

Do not use AI to express yourself to other people. Think about what meaning you want to convey, what knowledge you want to share and pack your thoughts into your own words. This helps you immensely to harden your own thoughts and remember what you learned and feel much better.
Do not use AI to generate complex and creative work. Nowadays, there are hundreds - probably thousands - of tools, which help you create art, music, code, designs, plans, etc. with the help of or completely with AI. While this makes it seem that you can be more productive, it just makes you more ignorant the more often you fall back to those methods instead of doing what you love to do yourself. It is completely fine to say that small packages of the work can be outsourced to AI, mostly repetitive tasks that just take more time doing manually. Creative and original work, however, should remain human and made with love. If you do not like what you do at all, this is a signal that you should probably stop doing it at all.
Do not fall for all the shiny AI stuff out there. Tools like Lovable, GitHub Copilot, Cursor, ChatGPT Voice and new on the board: GPT-5, just to name a few, do not want to actually help you. They want either directly your data, or own your workflow so you cannot escape once you got used to it. Unfortunately, people get used to AI fascinatingly fast.

In short, what I mean is that AI should be used for brainstorming and helping each individual for creating an end product - not to be confused with AI creating the end product -, but not for communicating with other people and the final results themselves (eg image creation, writing blogs, posts on social media, communicating with chats, motivation speeches, essays, etc.). In my opinion, the human brain can only evolve and learn from its own mistakes and experience. And you can never learn from your mistakes when it was actually the AI generating them.

AI has a place in ideation, but expressive work should remain human.

The Paradigm

I recently discovered a software design pattern called the “Onion Architecture”. To keep the explanation short, the main key principle of this architecture is its division into layers, where each layer is only connected to its two neighbours (siblings excluded), the inner and outer layer.

To transfer this paradigm into the current context, you can imagine the AI as a tool available to you, which is unconnected to all other parts by being only surrounded by your brain, and only your brain can access, manipulate, create, and modify the outer layers - in this example, writing blogs, creating content, communicating with people via chats or speeches, or expressing yourself with art or design.

Here you can see an image that represents my idea of a limited, but ideal usage of AI:

If such an architectural approach and the paradigm in this context are optimal or just opinionated can be criticised in the comments below.

Conclusion

As I said in the beginning, this blog post is very opinionated and aims to just share my experience with everyone so you can also learn from my mistakes and optimise your own usage of AI and have it better under your control. In the end you can do whatever you want, but be aware of the degradation of your own brain when you also fall into the pitfall of overuse.

Also one thing to note: It took me several months to write this blog post, refine it and start from zero again. No blog is perfect as you might have noticed with this one. There are probably some grammatical error here and there, some sentences that actually do not make sense, but this makes humans human. Moreover, there are very likely many strong opinions in this blog where you would totally argue against and completely disagree with me (I’m eager to see your comments expressing your outrage.), however this makes me me. My brain, my thoughts, my opinion.

“errare humanum est”

Resources with better evidence

If you are interested in articles which are based on more scientific studies or approaches, feel free to read some or all of those. They are in no particular order, so just start in the middle and keep going upward or downward. 😊

Happy reading!

Vibe-coding a VS Code Extension for Terraform projects

Fri, 01 Aug 2025 00:00:00 GMT

Today, I want to talk about a small VS Code extension that I vibe-coded in a single day to make working with Terraform easier. I will first explain what Terraform is, and then jump right into the functionality and reasons behind this extension. Feel free to skip the first section if you are already familiar with Terraform.

What is Terraform?

Terraform is an infrastructure-as-code (IaC) tool that lets you define your entire cloud or on-prem infrastructure as code. Its configuration language, invented by HashiCorp, is called HCL (HashiCorp Configuration Language) and features an intuitive, human-readable syntax. The native syntax has the advantage that the learning curve is low, it is consistent for all providers and pleasant to read and write for humans, whilst the JSON-based variant is easier for machines to generate and parse.

What makes Terraform very powerful are two basic features: variables and modules. Variables enable you to create resources where the actual values can be inserted from somewhere else and modules group any number of resources, which has the advantage of reusability and nesting. While both features sound very basic, the combination of the two makes a dream team. Because the openness of Terraform enables you to define input variables for each module and also export variables via outputs.

A simple module is therefore structured like this:

azure-resource-group/
- main.tf
- variables.tf
- outputs.tf
- README.md

All files except main.tf are optional (the README.md isn’t Terraform-specific), but I prefer following best practices, so the example includes them.

Let’s look at a simple example. Imagine we want to manage a resource group in Azure with Terraform. In the variables.tf file we define what inputs we expect inside the module. Each of the two blocks represents the variable and properties of the variable, like the description or the type:

variables.tf

variable "name" {
  description = "Name of the resource group"
  type        = string
}

variable "location" {
  description = "Azure region"
  type        = string
  default     = "westeurope"
}

You might have noticed that the location variable also has a default property, which makes the variable optional and provides a fallback value if none is specified. These variables can then be used inside the main.tf file. In here, we define the actual resources we want to generate:

main.tf

provider "azurerm" {
  features {}
}

resource "azurerm_resource_group" "this" {
  name     = var.name
  location = var.location
}

In this case, we just define our simple resource group, which you can think of as a folder in Azure - very amateurish explanation. Now the last part which we can implement, is the outputs.tf file:

outputs.tf

output "resource_group_id" {
  description = "The ID of the resource group"
  value       = azurerm_resource_group.this.id
}

This is very useful if we want to use information like the ID of the resource group later in other parts of our Terraform project.

As I already wrote, the README.md is not actually part of the Terraform definitions, but helps us understand the purpose of the module:

# Azure Resource Group Module

A minimal Terraform module that creates an Azure Resource Group.

## Usage

```hcl
module "rg" {
  source = "./azure-resource-group"
  name   = "my-resource-group"
}
```

As the README.md already suggests, we can now use this module to create an Azure Resource Group anywhere inside our project. We just need to make sure that the path to the module folder is correct and Terraform knows how to interpret the main.tf, variables.tf and outputs.tf files. In this case, since we do not specify the location variable, it will be set to "westeurope".

module "rg" {
  source = "./azure-resource-group"
  name   = "my-resource-group"
}

I hope this section gave you a better basic understanding of what Terraform is and what you can do with it.

The tedious task of Terraform

You might have noticed that the source field of a module creates an awesome flexibility for the whole project since you can define modules anywhere and use them anywhere inside the project.

However, this feature also has a huge drawback when it comes to maintainability: Resolving the actual values behind variables can be very tedious. While in this simple example it might seem easy to manage, the bigger the project grows, the more nested it is, the harder and more time-consuming understanding and adapting Terraform code can be. Therefore, I made an extension.

What should the extension do? The main goal of the extension is to provide the actual values of the variables everywhere you use them. If a module gets called from multiple places or just multiple times, the information should provide which use case sets the variable to which value. If modules get nested deeply, the values should resolve until we reach the .tfvars files. These are the files where you can define the hard-coded values for variables.

How to start a VS Code extension

Creating the basic template project for a VS Code extension is as easy as running this command when you have Node installed:

npx --package yo --package generator-code -- yo code

This command temporarily installs the Yeoman (a generator software), and enters an interactive mode where some questions have to be answered, like the project name, type and description. In the following block you can see all questions and default answers:

# ? What type of extension do you want to create? New Extension (TypeScript)
# ? What's the name of your extension? HelloWorld
### Press <Enter> to choose default for all options below ###

# ? What's the identifier of your extension? helloworld
# ? What's the description of your extension? LEAVE BLANK
# ? Initialize a git repository? Y
# ? Which bundler to use? unbundled
# ? Which package manager to use? npm

# ? Do you want to open the new folder with Visual Studio Code? Open with `code`

For further information regarding VS Code extensions I want to link to the official documentation, as it is always up-to-date in contrast to my explanations here.

3… 2… 1… Vibe-Coding!

I like to start new projects by asking ChatGPT for general technical questions like:

How would you suggest achieving such a project?
How long do you estimate it will take me?
How difficult will it be?

Brainstorming with AI bots seems like a very sensible way to get a better overview of new projects, especially when diving into completely new waters. Creating a VS Code extension was exactly such a use case because I had never created anything for VS Code or any other IDE before. After this initial brainstorming phase, I prefer to use Claude for programming all the files necessary for such an extension since in my experience this AI bot really has the ability to nail code. I hardly encountered bugs or runtime issues with Claude code, so I use it exactly for such use cases – initial starters. The drawback of Claude is its very limited free trial, which is why I am always careful when choosing my words and try to think of as many possible mistakes the AI could make ahead of time. So this is how it began: I took some time to formulate my exact scenario and wish into the limited context windows of a random words machine called Claude and immediately received a huge extension.ts implementation. Of course there were obvious differences between my vision and the communication to this LLM, so I had to tell it another time what the important considerations are and in order to be able to receive more code, I also used my magic trick: “If this is too big for one file, just give me the whole extension.ts in multiple files, which should work of course.”

Claude then went on a long journey.

After some struggling to keep it going my tokens were all used and I had to figure out the remaining code myself. Nonetheless, I managed to get a running version since not much was missing and immediately realised some improvements that went unnoticed until now. Since I had to wait for my tokens to refill, I did exactly this.

The next morning the improvement session began, and after two long conversations, the context window was completely full and I could not even send messages in the same chat any more, although my tokens were not expired yet. However, all I wanted to achieve and get out of Claude was now available and I could run some tests in one of my bigger projects. After confirming and adjusting some code manually, I was satisfied for now and so I decided that the first public release was ready.

Some trial and error with GitHub Actions later, I managed to set up the publisher for a VS Code extension. And two patch versions later, I was quite happy with the results.

The Final Result

Try out the extension yourself by clicking on the button below. There are still many improvements to be made, so if you are interested in helping out, feel free to contribute on GitHub.

Install Terraform Variables Resolution

Here you can see the example from the Terraform explanation, showing how this extension visually adds the values of the variables in VS Code:

Earworms and the message hidden within the pattern

Wed, 23 Jul 2025 00:00:00 GMT

Yes, this title is a small nod to the excellent Netflix series “Arcane”, but that’s not what this post is about.

Today, I want to share some thoughts about earworms, a term that originated in German (“Ohrwurm”) and was later adopted into English as a literal translation. The meaning behind this rather abstract term is catchy tunes—sticky music, as Wikipedia calls it. This phenomenon often occurs unpredictably, especially when our thoughts drift away from the present moment.

While many of my blog-post ideas strike on train rides, while lying in bed, or when I’m simply reflecting on life, the inspiration for this post literally hit me whilst showering, as the good old shower thoughts are intended to be. The reason – as you might be able to guess from the topic – was an earworm about a melody where I could have sworn that I haven’t heard it for a long time, like 4–5 weeks.

And this always seems to be the confusing parts about earworms: Nobody really knows who decides when to play. Is it the brain hitting “play” when it’s a little numb? You know what I mean, those moments when you don’t really know what you are currently thinking and you don’t have to think about what to think, you are just enjoying the moment. There is another Austrian idiom for this exact scenario: “ins Narrenkastl schauen”, which means something like to stare into space. And I think that exactly those absent-minded moments are the origin and reason why earworms happen.

But this still leaves the question: Who decides what to play in someone’s head when it happens? Like who is the DJ? From my own experience I have noticed a repeating pattern, especially if you have just been listening to music in the last half of an hour. My brain at least, likes to repeat parts of the penultimate song heard, in other words the song, which was played before the last song. This theory works even better if the last song was paused in the middle or just not perfectly at the end of it.

The exact reason for that is completely unknown to me, but if I had to guess, I would say that the rhythms of the completed song (the penultimate one) are still ringing somewhere in your mind since the song itself was maybe one of those “I-just-fade-out-my-volume-to-end-me”-songs, which is not my favourite type of ending to music, but it encourages the brain to go on.

At least that’s what I think. I would be very interested if you have experienced similar patterns, so feel free to write your own blog post about it or just share this one with friends so you can discuss it with them!

How to create a Rehype plugin that turns GitHub links into beautiful badges

Sat, 12 Jul 2025 00:00:00 GMT

Recently, I added a very little neat feature to this blog, which you might have noticed as a regular reader. It’s nothing huge, but gives every blog this little lovely touch I, which I have longed for a long time. I am ~~talking~~ writing about all those green badges with profile pictures you can see in this blog as well.

The inspiration to create them was taken from none other than Antfu himself, as he has those badges all over the place on his website (as time of writing).

Initially I thought they would require some long and tedious programming session to accomplish the same visual beauty. However, after some Vibe Coding - as Andrej Karpathy coined the term - I quickly realised that those badges were just a small rehype plugin away from existence.

This is the whole code behind the rehype plugin:

src/lib/rehype-github-badge-links.ts

import { h } from "hastscript";
import { visit } from "unist-util-visit";

export default function rehypeGitHubBadgeLinks() {
  return (tree) => {
    visit(tree, "element", (node) => {
      if (
        node.tagName === "a" &&
        typeof node.properties?.href === "string" &&
        node.properties.href.startsWith("https://github.com/")
      ) {
        const match = node.properties.href.match(
          /^https:\/\/github\.com\/([\w-]+)\/?$/
        );
        if (match) {
          const username = match[1];

          // Add GitHub badge class
          node.properties.className = (node.properties.className || []).concat(
            "gh-badge"
          );

          // Build avatar image
          const avatarImg = h("img", {
            src: `https://github.com/${username}.png`,
            alt: username,
          });

          // Prepend avatar image to original children
          node.children.unshift(avatarImg);
        }
      }
    });
  };
}

Basically all this plugin does, is walking through the HTML, looking for links which reference to any GitHub profile. If it finds one, it adds an <img> tag before the text content with the profile picture of the GitHub user or organisation. This is possible very consistently thanks to GitHub’s feature of making the picture available as a resource behind the profile link appended with .png. Read more about that feature in this awesome article on dev.to.

With a little bit of additional styling it looks really cute in my opinion. Please note that since this is a Starlight page, I use available CSS variables, like in line four:

src/styles/custom.css

.gh-badge {
  display: inline-flex;
  align-items: center;
  background-color: var(--sl-color-accent-low);
  border-radius: 9999px;
  padding: 0em 0.5em 0 0.3em;
  font-size: 0.9em;
  text-decoration: none;
  color: inherit;
  font-weight: 500;
  transition: background-color 0.2s ease;
  transform: translateY(0.29rem);
  border: 1px solid var(--sl-color-accent);
}

.gh-badge:hover {
  background-color: var(--sl-color-accent);
}

.gh-badge img {
  border-radius: 9999px;
  width: 1.3em;
  height: 1.3em;
}

Now to put everything together, let’s say for example in an Astro site, you just need to add the rehype plugin to the configuration like this:

astro.config.mjs

import { defineConfig } from 'astro/config';
import rehypeGitHubBadgeLinks from "./src/lib/rehype-github-badge-links";

export default defineConfig({
  markdown: {
    rehypePlugins: [rehypeGitHubBadgeLinks]
  }
})

Read more about the injection of rehype plugins in Astro in their configuration reference.

Do not forget to add the CSS in a similar way depending on your framework - in Starlight you can configure custom global CSS styles following these instructions - and you can admire your own badge links too. Feel free to share this post with anyone you want to persuade to use these features too.

✨ Bones point

If you want to use such a badge for other links too, I recommend that you craft yourself a little Astro component like this one:

src/components/BadgeLink.astro

---
const { href, src, text, className = "gh-badge" } = Astro.props;
---

<a href={href} class={className}>
  <img src={src} alt={text} />
  {text}
</a>

Just make sure that the CSS is globally (or scope it in the component above) and it’s ready to be used:

import BadgeLink from "../components/BadgeLink.astro";

<BadgeLink
  href="https://github.com/withastro/starlight"
  src="/starlight.png"
  text="Starlight"
/>

Accelerating translations with continuous integration

Wed, 09 Jul 2025 00:00:00 GMT

For the last year, I have been working a lot in various Open Source Communities on GitHub in my free time and I have been enjoying these somehow relaxing contributions because they help me gain new knowledge on a daily basis.

After some time contributing I also got to know how kind and welcoming communities behind those projects are. These people have all one thing in common with you: They want to build great stuff in their leisure time. Especially the Astro community is the one and only I have enjoyed being in the most, since it’s the most rewarding and friendly at the same time. Not all communities can achieve such a great status among OSS.

Recently, I discovered another evolving project founded by pelikhan which aims to automatically translate all your documentation, blogs or shop sites whenever something changes with the help of AI. Whilst initially sceptical, reading more about the project in its README.md had me hooked.

The approach of strictly guiding AI into only translating little chunks - mostly sentences or paragraphs with perfectionist instructions - made me think that this could really work. So I tried it out in my own project, my blog. And to my surprise, those translations were much better than I expected. Of course you notice that it was translated by AI - handmade work will hopefully never be replaced entirely - but if you fairly mention that you use AI in an aside, this is much more accessibly for people than nothing.

So I took a closer look at the actual code of the project. After noticing some little inconsistencies, spaces for improvements and missing but very cool features here and there, I started contributing there as well. I mean, after one year of contributions in bigger project, PRs were nothing new to me.

You have to know that this was a Friday evening - almost night in my timezone - and Peli was currently online, also doing commits after commits to the project. I quickly noticed that, in contrast to the other projects I am part of, Peli did not waste any time merging PRs. It felt very rewarding this night because I just kept going until 1am, Peli merging faster than I could improve features, docs and fixes. Another aspect that felt great was that since this was a young project, Peli did not hesitate to just merge, try it out locally and then pushing little fixes I missed.

Fast-forward three days and I am now an official contributor to the project, making it greater and greater almost daily, mainly focusing on docs and the support for my heart project: Starlight - as you might already have guessed from my blogs.

Peli and I have our virtual productivity sessions between 4pm and 8pm UTC, extending longer on weekends. So if you want to join us as an early bird of the project or got interested in using it, feel free to check it out on GitHub.

Some aspects of creating a blog are really easy, and some are extremely difficult!

Tue, 08 Jul 2025 00:00:00 GMT

After a very interesting discussion in the Astro Discord - started by none other than core maintainer Alex himself (btw congratulations on this recent achievement 🎉) -, I joked around that someone could write a blog about reasons why it is so difficult for many people to not only write, but also maintain a blog as a whole.

The man who nominated me as an Astro Support Squad - Jacob (btw thank you very much for noticing me within this awesome community 😍) - took that quite literally and wrote a blog about it. No joke. Check it out: https://jacobjenkins.codes/posts/why-is-writing-blogs-so-hard/ This is his very first blog btw (and hopefully not his last one, as I really enjoyed reading his style).

Our beloved everywhere-helper, Blogger, Designer and StudioCMSer - Lou (btw thank you for giving me some blog writing tips in advance so I can more confidently write this 🤩) - jumped immediately on this awesome hype-train (as Twitch users might call it) and published his follow-up post within fricking 12 hours!!! Believe me, I checked the commits, Lou literally pushed within 4min of the 12h mark.

As I will include many references to both of their blogs, it’s best if you read theirs first. And then mine. Or maybe it’s better if you just read theirs, I’m not yet sure how mine will develop.

But what I can ~~say~~ write, is that mine will fully focus on just the writing skills.

How to setup a blog (technical challenges)

Whilst this blog doesn’t focus on how to build a blog, deploy it and all this technical stuff, I want to mention that everyone can do it. Like Lou mentioned, as a non-technical person, you can always just create an account on Medium and such alternatives. If you are a little into programming, you can let your creativity a little bit more space and thanks to the awesome Starlight Blog project from HiDeoo you do not need much knowledge to deploy your own website. Nowadays, where there are also PaaS (Platform as a Service) providers like Netlify, which make deploying stuff a Click-Ops adventure, there no more is any excuse in not being able to publish your blog because of technical difficulties.

Okay, jokes aside, now: Writing skills

But this blog should focus on mainly on the “Writing Skill” as I said, so let’s continue there. As I myself initially had a hard time writing blogs, I can totally agree with Jacob that getting started is hard. It’s not like reading through the Astro “Getting started” guide where you just have to follow the instructions and then ask on Discord what a InvalidContentEntryDataError means _{please use the #support thread if you do 🫶} (If you are still wondering).

On the other hand, the goal seems so close and doable. Just write some words. What’s so hard in writing those fricking words? Actually, I myself don’t know. Why are you asking me? The only thing that helped me getting out of the spiral of “You-Want-To-Write-But-Every-Time-You-Stare-At-The-Blinking-Cursor-Your-Brain-Goes-Numb” (let’s make that the hashtag of the week) was Lou’s tip of not wanting as much of yourself in your first blog. Why do you want a perfect blog to start with? Just because of your reputation? So people don’t think wrong of you? Feel disappointed? To be honest: That’s bullshit! Not just because your first blog will very likely not be read by anyone (with the exception of Jacob’s exceptional blog), but also because you are just making it harder for yourself. My personal mind ceiling was that I thought I must write at least 500 words to begin with. But who says that? To be honest, if I could look back, I sometimes think: “Man, it would have been so unique and cool if my first ever blog was just like a regular tweet”, or even extremer: One. Word. Nobody will stop you from publishing this blog:

Hello 👋

(Sorry if I now took your awesome idea, and included your whole blog post in here - wow cool, that rhymes)

See? I can do whatever I want, even being a fricking poet (typical German behaviour), and nobody will judge me. Okay, maybe someone will hate on this blog because it’s “a waste of time, no meaning in all this useless content”, but who c a r e s? It’s your blog, nobody asked for their opinions (unless you have a comment section under your blog 🙄 cough Lou). So don’t think about what others might think about your writing style, content, use of language or even if you make grammar mistakes. Those all make you human and getting everything perfect is not only completely unnecessary, it’s also hrad.

Another part of writing blogs is not just getting started, but the difficulty of maintaining one flow, one thought if you will. As a listener of well-written speeches you subconsciously notice that it was good, it was fulfilling, sublime. And that’s what I love about such blogs or speeches. They just feel right somehow. But I myself have accepted that I can’t accomplish such achievements in my own creative work. And I’m much better off with that acceptance. Because the benefit of accepting imperfection is getting things done. Not just 50%, not just 90%. Done. Completed, 100%. And this is something that many people struggle with, my past self included - actually just myself included.

But as Lou mentions, there are other easy methods to keep a common thread in the whole post, sticking to the story whilst thoughts might wander around in your own brain. Bringing all those thoughts on paper, or in this case on the keyboard can be challenging, especially when you are starting writing. But there is a reason why we learn such skills at school, they improve our cognitive health and development immensely. This is also why I heavily agree with Lou when he states that AI should never be used in the process of writing. It just has no benefits, neither for the reader and even less for you.

So I don’t want to repeat what Lou says, but bullet points have helped me out a lot in the past. They just give me the feeling of constant structure, while my mind can play around with different thoughts and theories. This makes sure that you always come back to what you initially wanted to include in your post. “And if you can’t come up with bullet points?”, you might ask. Then you might need some more brainstormings or just showers.

In the end, these are some tips I can give you along the way:

Develop your own writing style, not by training, but just writing. Sooner or later you will notice what types you might like, some things you want to adopt from other bloggers, but summa summarum what you write will always be yours. You just share it with the world. It’s up to you if you want to use a colon or hyphen here and there, use more dots, the past tense, imperativ, swear words or the more formal style. All those things will come automatically together and define you as a unique blogger. And you readers will value this individuality more than you know.
Don’t take on too much. Might sound easy, but everyone falls regularly into this trap. Or maybe just people like me, having a mix of autism and perfectionism - idk.
Although it always sounds stupid: Start writing. And if it doesn’t work, start writing the middle part. Because I know start and ending are always difficult, but imo the middle part goes down like butter.
Blogs have easy and hard sides: This is what the title says, but know that when I wrote all that I realised that I haven’t answered that question at all… Thank god, that Jacob didn’t type a question mark at the end of that suggestion. 🙏

Yeah, I guess that’s it. If you want to share you thoughts, leave them in Lou’s comments because I have none.

How to create a horizontal progress indicator for your Starlight site

Tue, 10 Jun 2025 00:00:00 GMT

In this post, we would like to show you how FrostyBee created a clean horizontal progress indicator for Starlight sites.

Prerequisites

You will need to have an existing Starlight website.

Create the progress indicator component

Let’s create a new component called ProgressIndicator.astro in the src/components/ directory. This component will be responsible for rendering the progress indicator.

We create a container which spans across the whole width with the progress bar <div> inside. The width of the inner <div> is the updated whenever the user scrolls (and when the page loads) to reflect the current scroll position.

src/components/ProgressIndicator.astro

<div class="progress-scroll-container" aria-hidden="true">
  <div id="progress-scroll"></div>
</div>

<script>
  window.addEventListener("scroll", function () {
    updateProgressScroll();
  });
  window.addEventListener("load", function () {
    updateProgressScroll();
  });

  function updateProgressScroll() {
    if (document) {
      const progressScroll = document.getElementById("progress-scroll");
      if (progressScroll) {
        var scrollTop = window.scrollY || document.documentElement.scrollTop;
        var scrollHeight =
          document.documentElement.scrollHeight - window.innerHeight;
        var progress = (scrollTop / scrollHeight) * 100;
        progressScroll.style.width = progress + "%";
      }
    }
  }
</script>

17 collapsed lines
<style>
  html:is(:not([data-has-hero]), [data-has-sidebar], [data-has-toc]) .progress-scroll-container {
    position: fixed;
    top: var(--sl-nav-height);
    left: 0;
    height: 0.25rem;
    width: 100%;
    background-color: transparent;
    z-index: 3;
  }

  #progress-scroll {
    height: 100%;
    width: 0px;
    background-color: var(--sl-color-accent-high);
  }
</style>

<style is:global>
  #starlight__on-this-page--mobile {
    margin-top: 0.25rem;
  }
</style>

In the hidden lines is the styling which makes sure that the progress bar looks like a typical progress bar. It is also suited to Starlight because the bar is automatically hidden when the site has no sidebar and table of contents, but a hero element as most landing pages do.

One thing to point out is what the global CSS (line 45) does: It pushes the mobile table of contents dropdown menu down to create more whitespace to the progress bar. This is a personal preference and you can remove it if you want.

Starlight Override

Now we can use this component in a Starlight override. In this case it makes sense to override the Header.astro component like this:

src/components/Header.astro

---
import Default from "@astrojs/starlight/components/Header.astro";
import ScrollIndicator from "./ScrollIndicator.astro";
---

<Default><slot /></Default>
<ScrollIndicator />

Do not forget to add this component override to your astro.config.mjs file:

astro.config.mjs

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs with a Progress Indicator',
      components: {
        // Override the default `Header` component.
        Header: './src/components/Header.astro',
      },
    }),
  ],
});

Source Code

You can find the whole project code on GitHub and in this Stackblitz example.

Conclusion

With this setup, the progress indicator will be displayed on every page (except landing pages) of your Starlight site. 🥳

You can also check out FrostyBee’s Starlight Scroll To Top plugin which also supports a built in Progress Ring since version 0.3.1. 🙌

How components open up endless possibilities

Tue, 13 May 2025 00:00:00 GMT

Using the Starlight Sidebar Topics plugin together with the Starlight Sidebar Topics Dropdown component, you can create a website that has a list of topics on desktop and a dropdown menu on mobile.

Prerequisites

You will need to have an existing Starlight website.

Install the packages

First, install the starlight-sidebar-topics plugin and also the starlight-sidebar-topics-dropdown component:

npm install starlight-sidebar-topics starlight-sidebar-topics-dropdown

pnpm add starlight-sidebar-topics starlight-sidebar-topics-dropdown

yarn add starlight-sidebar-topics starlight-sidebar-topics-dropdown

Afterwards, follow the setup guides from Starlight Sidebar Topics and Starlight Sidebar Topics Dropdown.

In the setup guide from the dropdown component, you have created a sidebar component, which only renders the dropdown menu. Now, you need to modify this component to also render the default sidebar if the user is on desktop.

src/components/Sidebar.astro

---
import Default from '@astrojs/starlight/components/Sidebar.astro';
import Topics from 'starlight-sidebar-topics/components/Sidebar.astro';
import TopicsDropdown from 'starlight-sidebar-topics-dropdown/TopicsDropdown.astro';
---

<div class="topics">
  <Topics/>
</div>
<div class="topics-dropdown">
  <TopicsDropdown/>
</div>
<Default><slot /></Default>

<style>
  /* Hide topics by default and show them on medium screens and larger */
  .topics {
    display: none;
  }

  @media (min-width: 800px) {
    .topics {
      display: block;
    }
  }

  /* Show topics dropdown on small screens and hide it on medium screens and larger */
  .topics-dropdown {
    display: block;
  }

  @media (min-width: 800px) {
    .topics-dropdown {
      display: none;
    }
  }
</style>

Result

If you follow these steps, your sidebar will look like this:

You can find the complete source code of this guide in this StackBlitz example.

Endless possibilities

You could also do it the other way around (list on mobile, dropdown on desktop) by swapping the display: block and display: none properties in the CSS.

Moreover, you could also create your own display component, which uses the route data from the Starlight Sidebar Topics plugin and renders the topics in a custom way. This is a bit more advanced, but you can find more information about this in the “Custom Topics List” documentation.

A short history of Starlight Sidebar Topics plugins

Mon, 05 May 2025 00:00:00 GMT

Maybe you have heard about this cool documentation framework before. I talk about it quite often and use it regularly. Not only because I’m an active contributor, but also because Starlight just grew to my heart. Its features: Simplicity and minimalism, but everything you need. Its performance: Faster than 98% of other websites out there. Its accessibility: Not even a question!

The Creation

However, one thing that’s objectively missing in my opinion is a granular way of separating broad topics inside your documentation. And I’m not alone with this subjectively general accepted opinion. HiDeoo is not only one of the most active maintainers of the project, but also the author of the most and imho best plugins you can find for Starlight. And they have also noticed this missing niche functionality about topics. That’s why they decided to create the Starlight Sidebar Topics plugin early on, back in October 2024, which allows you to make a sidebar with topics. Read more about the plugin’s functionalities in its documentation.

The one thing that bothered me personally in the early days of the plugin was the way topics were displayed in the sidebar. Because it doesn’t - like I imagined a solution could look like - use some kind of dropdown menu for switching between topics, but instead always shows all topics. This design choice was, as HiDeoo clearly points out, very intentional and not without any reason: All topics should be visible at once. Proven by the Astro docs themselves (Chris Swithinbank implemented the “tabbed sidebar” for the Astro v5 docs later in the same month), this approach definitely has many benefits over a dropdown menu. Nonetheless, I was still unsatisfied by this design, and so I created my own version.

Copying and pasting was my strength when it came to building a new Starlight plugin for the community. And so, I did just that. I took the Starlight Sidebar Topics plugin as a starting point and just had to adapt the Topics.astro component, which includes the HTML for rendering the topics in the sidebar. After struggling for some time with the implementation of a satisfying enough dropdown menu, which was pure HTML + CSS but also clean to look at (sorry for the self-praise, I’m just proud of myself), I finally found a solution that I’m very satisfied with and released this new plugin under the name Starlight Sidebar Topics Dropdown - how original.

The Adaptation

You might think that this story is now over because everyone could just use the variant they want, everyone is happy. But Starlight kept and keeps improving and around three months later, on the 15th of February, coming almost as a birthday present for me, was the long-awaited addition of route data in Starlight with the release of v0.32. This seemingly small addition opened up so many possibilities, which I myself never saw coming. HiDeoo once again was the leading inspiration for plugin authors and pushed this new functionality to its limits. It took them just two days to adapt over 11 plugins to the latest Starlight version back then and they later improved and refactored much of the code to make even more use of this powerful feature.

And so comes the day when HiDeoo contacts me to tell me that the Starlight Sidebar Topics plugin now uses Starlight’s new route data feature. At first, I didn’t quite understand what benefits these implementation changes would have, but then HiDeoo took the time to explain to me that I could now turn the Starlight Sidebar Topics Dropdown plugin into a simple component which uses the route data from his plugin. Intuitively, I was opposed to this smart idea because it felt like my only plugin that made some popularity was turned into some useless component. I couldn’t have been further from the truth.

The Union

Eventually, I decided to refactor my plugin into a component - this refactoring casually eliminated exactly 1210 lines of code and added 68 lines of changelog - and I noticed, how little code it now took to turn the Topics.astro list into a dropdown from a user’s perspective. I was confident that this really was the right direction for the ~~plugin~~ component. And so I updated the whole documentation - more like: deleted more than 200 lines of text (feels good) - and released the new version 0.5.

Now you might wonder how such mature plugins could still improve over time. To be honest, I myself was very surprised when HiDeoo casually dropped a bomb in my Discord DMs. His idea was and still is ingenious. Otherwise, I wouldn’t even think about this topic anymore. But here I am, writing a whopping 800 words just to prepare you for what’s to come. Drum roll please! Fasten your seatbelt! This statement from HiDeoo is going to blow your mind:

“One could have something like the default built-in list on a desktop view, and on mobile use your component, or something like that 🧠” — HiDeoo, 21/03/2025 09:54

Profound. Timeless. Golden.

And that single, beautiful spark of an idea? It’s precisely what I’ll guide you through in the post “Starlight Topics Dropdown and List together”.

How to make your Starlight sidebar items look better

Sun, 27 Apr 2025 00:00:00 GMT

Have you ever wondered why your Starlight sidebar doesn’t look that appealing? Did you know how important the space between items in your sidebar unconsciously is? The font size, the weight and little colour differences? In this guide, we’ll take a look at how you can customize the appearance of your Starlight sidebar with some quick and easy steps.

Prerequisites

First, you need to set up your Starlight site. Afterward, Starlight offers a guide on customizing styles applied to your Starlight site, which is the feature we’ll use in today’s post.

As described in this guide, you need to create a .css file somewhere inside your src/ directory, where you can define your CSS styles. Don’t forget to add the path to this .css file to Starlight’s customCss array in astro.config.mjs:

astro.config.mjs

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Docs With Custom CSS',
      customCss: [
        // Relative path to your custom CSS file
        './src/styles/custom.css',
      ],
    }),
  ],
});

After completing these preparation steps, you are ready to try out some nice adjustments to Starlight’s sidebar design.

Customizations

There are endless different possibilities that you can play around with just with your custom CSS. I will give you some ideas that I found very helpful while playing around with the sidebar design myself. While some of these ideas might look silly to you, I promise that the combination of a few of them will make your Starlight sidebar look even better.

But before I do that, I’ll show you how the default styling of the Starlight sidebar currently looks like:

On the root level of your Starlight sidebar, there are two different types of elements: pages and groups. While the default styling is pretty decent, I found the whitespaces - this is the margin between items which itself doesn’t include any content - to be a bit too large, especially between root-level items. With this example of custom CSS down below, I made the margin between root-level items smaller while keeping the margin between groups the same. The important CSS styling is highlighted in the code block.

src/styles/custom.css

sl-sidebar-state-persist ul.top-level > li:not(:has(details)) {
  margin-top: 0rem;
}
sl-sidebar-state-persist ul.top-level > li:has(details) {
  margin-block: 0.5rem; /* default value */
}

Perhaps, this will not be as useful to you because you don’t use root-level pages in your sidebar, so this effect won’t be noticeable to you. But if you do, give this a try.

Imho the one thing that triggers me the most about Starlight’s root-level items in the sidebar, is their boldness. This is probably a very opinionated take, but if you ask me, one single page can’t possibly be as important as an entire group of pages in your documentation. Therefore, I made the font weight of root-level items thinner as you can see in the code block below.

src/styles/custom.css

sl-sidebar-state-persist ul.top-level > li > a[aria-current="page"] {
  font-weight: 600; /* default value */
}
sl-sidebar-state-persist ul.top-level > li > a:not([aria-current="page"]) {
  font-weight: 400;
}

A small but subtle change: I made unselected root-level items appear dimmer in the code block below.

If you choose to use this design as well, I recommend that you only apply the second CSS manipulation since the first one is just for demonstrating how you could adjust the styling of selected root-level items – this rule also applies to the other code blocks in this blog if they are marked as default value.

src/styles/custom.css

sl-sidebar-state-persist ul.top-level > li > a[aria-current="page"] {
  color: var(--sl-color-text-invert); /* default value */
}
sl-sidebar-state-persist ul.top-level > li > a:not([aria-current="page"]) {
  color: var(--sl-color-gray-2);
}

Although I don’t recommend it, you can also adjust the font size of sidebar items. With this example of custom CSS down below, I made the font size of root-level items smaller.

src/styles/custom.css

sl-sidebar-state-persist ul.top-level > li > a {
  font-size: var(--sl-text-sm);
}

Recommendations

Summing everything up, I recommend that you apply some mix of the above customization options, which you can conveniently see in a single .css file.

Note that I also use Cascade Layers, supported since Starlight 0.34.0, and recommend using them to specify the order in which CSS styles are applied.

src/styles/custom.css

@layer starlight, my-starlight-sidebar;

@layer my-starlight-sidebar {
  sl-sidebar-state-persist ul.top-level > li:not(:has(details)) {
    margin-block: 0rem;
  }
  sl-sidebar-state-persist ul.top-level > li > a:not([aria-current="page"]) {
    font-weight: 400;
    color: var(--sl-color-gray-2);
  }
}

Deep Thoughts | Deep Thoughts

Rising community at tomorrow's horizon

🔗 Resources

Recommended Git Config

Automatic rebase

Default branch: main

Adding co-authors

Summary

Resources

Uncommon Git Commands

Checkout a remote branch on fork

Rename the commit message of an older commit

Clean up local branches

Remove tracked files with .gitignore

Summary

Resources

What open source really is about

tl;dr

Freedom

Experience

Community

Motivation

Journey

Reciprocity

Interest

Enjoyment

Comparing minor features of Spotify and YouTube Music

Crossfade

Shuffle

Volume

Adding songs to playlists

Mixes and Smart Shuffle

Track Sorting

Playlist Sorting

Library Filtering

Lyrics

Discoverability

Integrations and Ecosystem

Stats for nerds

Conclusion

Add Additional Content to Starlight's Table of Contents

Append content

Prepend content

Place content at bottom

Mobile support

Source code

Customize the "Overview" title of your Starlight Table of Contents

Global definition

Frontmatter override

Source code

How VS Code Snippets can improve your workflow when working with Astro

The need for snippets

Creating a snippet

Using the snippet

Further resources

Star Days ★

1 Quick Description

2 Purpose

3 On anti-productivity

4 Motivation

How to fully autogenerate Starlight sidebars (without losing control)

Use case

Solving the ordering issue

Solving the sidebar folder naming issue

Using HiDeoo’s plugin

Stop Outsourcing Your Soul to AI

How people tend to use AI

Negative side effects

Communication decline

Loneliness

Proposal of AI usage layer model

The Paradigm

Conclusion

Resources with better evidence

Vibe-coding a VS Code Extension for Terraform projects

What is Terraform?

The tedious task of Terraform

How to start a VS Code extension

3… 2… 1… Vibe-Coding!

The Final Result

Default branch: `main`