GitHub stars in Obsidian

This plugin for Obsidian imports your GitHub stars into your vault as separate documents. So, when import is done you will be able to:

• Create internal links to your starred repositories in your vault
• See a history of your stars on GitHub
• Have a index of your starred repositories grouped by programming languages
• Have a index grouped by owners of your starred repos

Table of contents

• Demo
• Use cases
• Features
• How to use
• Roadmap to 1.0
• Implementation details
• Inspiration sources

Demo

demo.webm

Use cases

• You have many unorganized stars on GitHub
• You want to make your own notes about your starred repositories
• You want to use links to your favorite projects in some researches (e.g. dependencies of new programming project)
• You want to have better than GitHub navigation in your favorites repositories

Features

• Create document for each starred repository
• Each repository document's FrontMatter has properties:
  • URL
  • Homepage URL
  • Count of stars
  • Count of forks
  • Topics
  • Dates of:
    • Repository creation on GitHub
    • Last push
    • Repository was starred
    • Repository has been updated
    • Import to your vault
• Create index pages of all starred repositories sorted by:
  • Date
  • Owners
  • Main programming languages
• Use fine grained GitHub token with limited access to your stars

How to use

Prepare

To work with this plugin, you need to have a GitHub account and a fine grained access token. To generate a fine grained access token, follow these steps:

1. Go to your GitHub account's personal access tokens page.
2. Click on "Generate new token".
3. Confirm access if you have two-factor authentication enabled.
4. Give your token a name.
5. Setup expiration date (and optionally description).
6. Select read-only access to "Starring" (see "Account permissions" settings).
7. Click on "Generate token".
8. Copy generated token value and paste it into the plugin settings after plugin will be installed.

Installation

You have two options to install this plugin:

1. Install this plugin from community plugin list in Obsidian. NB only after this PR will be merged.
2. Use BRAT plugin to use this plugin version directly from GitHub.

Usage

First synchronization

1. Open the plugin settings.
2. Enter your GitHub token in "GitHub API access token" field (see a demo video above).
3. Wait a second, and plugin will save your token to settings.
4. Press Cmd + P (Mac) or Ctrl + P (Windows/Linux) to open the Obsidian command palette.
5. Type "GitHub stars" and select plugin command GitHub stars: Synchronize your starred repositories.
6. If API token is valid, plugin will start synchronization process. In dependence of count of your starred repositories it will take some time. For example, if you have around 2500 starred repositories, it will take about 5 minutes with page size set to 50 (about 5 seconds to request/response). The reason of this is that GitHub GraphQL API uses pagination to fetch data, which means that the plugin needs to make multiple requests to the API to retrieve all the data. By default page size is set to 50, but you can change it in the plugin settings.
7. After synchronization is complete you will have a new folder with your starred repositories in your vault. Name of the folder is set to "GitHub" by default, but you can change it in the plugin settings too.
8. Inside of this folder will be:
   • GitHub/db subfolder. This is the place where plugin stores SQLite database with information about your starred repositories.
   • GitHub/repositories subfolder. This is the place where plugin stores markdown files with information about your starred repositories. Each repository will be placed in subfolder with its owner name. For example, star of this repository will be placed in file GitHub/repositories/vovanbo/obsidian-github-stars.md.
   • Three index files:
     • Stars by days.md. This file contains a list of all your starred repositories grouped by the day they were starred.
     • Stars by owners.md. This file contains a list of all your starred repositories grouped by the owner of the repository.
     • Stars by languages.md. This file contains a list of all your starred repositories grouped by the main programming language used in the repository.

Structure of Markdown repository file

Content

Each repository file created from the empty file template that have the following structure:

<!-- GITHUB-STARS-START -->

<!-- GITHUB-STARS-END -->

---

Between the <!-- GITHUB-STARS-START --> and <!-- GITHUB-STARS-END --> tags will be placed generated content. So, don't edit content inside these tags manually. It will be overwritten on each update. Don't worry, these HTML comments are the valid Markdown syntax.

Any of your notes related to this repository should be placed after horizontal rule line (---). They will be never touched by this plugin.

That exactly will be placed inside tags you can see in the demo video above. In short:

• Name of repository
• URL to repository
• Description of repository (if available)
• Homepage URL
• URL to repository owner page on GitHub
• Information about latest release if available
• List of programming languages used in the repository
• Funding links (if available)

Frontmatter

Each repository Markdown page will have the following frontmatter:

---
url: <repository URL>
homepageUrl: <homepage URL>
isArchived: <boolean>
isFork: <boolean>
isPrivate: <boolean>
isTemplate: <boolean>
stargazerCount: <number>
forkCount: <number>
createdAt: <date>
importedAt: <date>
pushedAt: <date>
starredAt: <date>
updatedAt: <date>
topics: <list of topics>
---

Incremental update

Documentation will be updated soon.

Remove unstarred repositories

Documentation will be updated soon.

Roadmap to 1.0

• Automatically remove files related to removed stars
• Incremental update
• Use Obsidian views to:
  • Make a full text search
  • Show statistics
  • Show ratings
• i18n / l10n
• Fetch README file content on a starred repository page
• Global changes log
• Highlight archived, deprecated and unmaintained repositories
• Customizable templates of pages
• Test suite

Implementation details

Dependencies

• Bun (TypeScript, build, WASM binary import)
• SQL.js (SQLite in browser via WASM)
• octokit.js (API client for GitHub)
• Handlebars (Templates for pages)
• neverthrow (unified error handling and result types)
• luxon (date and time library)
• Biome (lint, format, etc)
• git-cliff (bump versions and change log generation)

Inspiration sources

• starred — creating your own Awesome List by GitHub stars!
• starred_repos_organizer — Organize your starred repositories
• bun-obsidian-plugin-build-scripts — Scripts to build Obsidian plugins with Bun, SCSS with Grass, and Rust to WASM