obsidian-plugin/flyingnobita_obsidian-github-stars
1
0
Fork 0
mirror of https://github.com/flyingnobita/obsidian-github-stars.git synced 2026-07-22 05:42:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

chore(release): 1.4.0 docs and metadata

Browse source
This commit is contained in:
flyingnobita 2026-03-20 00:21:43 +08:00
parent 082be15e07
commit 731e300b00
No known key found for this signature in database
3 changed files with 100 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
CHANGELOG.md
View file

@ -1,5 +1,24 @@
# Changelog
- Mar-19, 2026 - 10:59 PM +08 - [Refined refresh behavior, added tests, and updated docs]
## [1.4.0] - 2026-03-19
### Added
- Unit tests covering cache refresh and embedded star update behavior
- Refresh token warning setting for missing or invalid GitHub tokens
- Repo-local `AGENTS.md` and `dev-docs/SPECS.md`
### Changed
- `Refresh for current note` now bypasses valid cache entries for repositories in the active note
- Refreshes can update existing embedded stars without embedding plain links
- When enabled, embedded star updates can also happen on Reading View and Live Preview refresh paths
- Updated README and internal specs to match current behavior
### Fixed
- Invalid GitHub tokens now fall back to unauthenticated requests for public repositories
- Failed refreshes leave existing embedded star text unchanged and show one notice per refresh attempt
## [1.3.0] - 2026-03-19
### Removed

22
README.md
View file

@ -1,7 +1,7 @@
# GitHub Stars Plugin
[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.3.0-green?style=for-the-badge)](CHANGELOG.md)
[![Version](https://img.shields.io/badge/version-1.4.0-green?style=for-the-badge)](CHANGELOG.md)
[![Obsidian Downloads](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fobsidianmd%2Fobsidian-releases%2FHEAD%2Fcommunity-plugin-stats.json&query=%24%5B%22github-stars%22%5D.downloads&logo=obsidian&label=downloads&style=for-the-badge&color=7C3AED)](https://obsidian.md/plugins?id=github-stars)
An Obsidian plugin that automatically displays GitHub star counts next to repository links in your notes — in both Reading View and Live Preview. Star counts can also be embedded directly into your markdown, making them visible outside Obsidian.
@ -38,20 +38,34 @@ The plugin can be configured in the Settings tab:
- **Number Format**: Choose between full numbers (e.g., 1,234) or abbreviated format (e.g., 1.2k)
- **GitHub API Token**: Optional personal access token to increase the API rate limit from 60 to 5,000 requests per hour. To generate one:
1. Go to [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens)
2. Click "Generate new token"
3. Give it a name and select the "public_repo" scope
2. Create a fine-grained personal access token or a classic token with access suitable for public repository metadata
3. Give it a name and ensure it can access public repository metadata
4. Click "Generate token"
5. Copy the token and paste it in the plugin settings
- **Update embedded stars on refresh**: Enabled by default. When enabled, refreshing updates the star count written in the Markdown file next to a GitHub URL.
- **Show token warnings on refresh**: Enabled by default. When enabled, the plugin warns during manual refresh if the GitHub token is missing or invalid.
## 🔄 Refresh And Cache Behavior
- Rendering in Reading View and Live Preview uses cached star counts when the cache entry is still fresh.
- Cache expiry is lazy. When a cache entry expires, the plugin fetches new data the next time that repository is looked up. Expiry does not trigger a background refresh on its own.
- `Refresh for current note` is stronger than normal rendering. It fetches fresh star counts from GitHub for every repository in the active note even if those cache entries are still valid.
- If `Update embedded stars on refresh` is disabled, embedded star text is left unchanged and may show an older value than the refreshed star count.
## 💻 Commands
The plugin adds the following commands:
- **Refresh for current note**: Refreshes all GitHub star counts in the current note
- **Refresh for current note**: Fetches fresh star counts from GitHub for all repositories in the current note and rerenders the note. If `Update embedded stars on refresh` is enabled, it also updates already-embedded star text.
- **Clear cache**: Clears the cached star counts
- **Embed star counts in current note**: Writes star counts (e.g. `⭐ 1.2k`) directly into the markdown file after each GitHub link. Re-running updates existing counts.
- **Remove embedded star counts from current note**: Strips all embedded star counts from the file
## 🧪 Development
- `npm test`: Runs the unit tests with Vitest
- `npm run build`: Type-checks and builds the plugin bundle
## ❤️ Support This Project
You can support this project in a few simple ways:

63
dev-docs/SPECS.md Normal file
View file

@ -0,0 +1,63 @@
# Specs
## Commands
- `Clear cache` removes all stored cached star counts.
- `Refresh for current note` fetches fresh GitHub star counts for repositories in the active note, updates the cache, and may also update already-embedded star text depending on the refresh setting.
- `Embed star counts in current note` writes star counts into the active note as embedded `⭐ ...` text.
- `Remove embedded star counts from current note` removes embedded `⭐ ...` text from the active note.
## User Settings
- `Cache expiry` controls how long cached star counts remain fresh.
- `Number format` controls whether star counts are displayed as full numbers or abbreviated values.
- `GitHub API token (optional)` allows authenticated GitHub API requests for higher rate limits.
- `Update embedded stars on refresh` controls whether refreshes update embedded `⭐ ...` text in the active note.
- `Show token warnings on refresh` controls whether manual refresh warns when the GitHub token is missing or invalid.
## Refresh Behavior
- `Refresh for current note` only applies to the active note.
- `Refresh for current note` fetches fresh star counts from GitHub for repositories in the active note even if their cache entries are still valid.
- When `Update embedded stars on refresh` is enabled, refresh updates only links that already have embedded `⭐ ...` text in the active note and then rerenders the note.
- When `Update embedded stars on refresh` is enabled, Reading View and Live Preview refresh paths also update existing embedded `⭐ ...` text for repositories whose star counts were refreshed.
- If the same repository appears multiple times in the active note, refresh fetches it once and applies the result to all matching occurrences.
- When `Update embedded stars on refresh` is disabled, refresh rerenders the note without changing embedded `⭐ ...` text.
- If a refresh fetch fails for a repository, existing embedded star text for that repository is left unchanged.
- If one or more repository refreshes fail during a manual refresh, the plugin shows a single failure notice for that refresh attempt.
## Rendering Modes
- Reading View injects star counts into rendered HTML after GitHub repository links.
- Live Preview injects star counts as CodeMirror widgets after visible GitHub repository links.
- Embedded star text in the markdown file is distinct from transient rendered star counts.
## Embedded Star Rules
- The plugin detects existing embedded `⭐ ...` text and skips adding duplicate stars during normal rendering.
- Refresh never embeds stars for plain links. It only updates embedded `⭐ ...` text that already exists when the refresh setting is enabled.
- `Embed star counts in current note` writes or updates embedded `⭐ ...` text directly in the markdown file.
- `Remove embedded star counts from current note` removes embedded `⭐ ...` text while leaving the GitHub links intact.
## Authentication Behavior
- If no GitHub API token is configured, requests use the lower unauthenticated GitHub API rate limit.
- During a manual refresh of a note, token warnings are shown at most once even if the refresh processes multiple GitHub links.
- If GitHub rejects the configured token, the plugin logs a warning, shows a notice, and retries public repositories without authentication.
## Cache Behavior
- GitHub star counts are cached per repository using `owner/repo` as the cache key.
- Each cache entry stores the fetched star count and a timestamp.
- Cache expiry is lazy, not proactive. When an entry expires, the plugin does not schedule or run a background refresh automatically.
- A fresh API request only happens the next time the plugin tries to resolve stars for that repository and sees that the cached entry is missing or expired.
- Star lookups can be triggered by rendering a note in Reading View, rendering visible GitHub links in Live Preview, running `Refresh for current note`, or running `Embed star counts in current note`.
- If a cached entry is still within the configured expiry window, the cached value is used and no network request is made.
- If a request fails and a stale cache entry exists for the same repository, the stale cached value may still be returned.
- Clearing the cache removes stored cache entries but does not remove star text that is already rendered in the current UI.
## Supported URLs
- The plugin only processes GitHub repository URLs.
- Repository parsing extracts `owner/repo` from standard GitHub URLs and strips a trailing `.git` suffix from the repository name.
- Non-repository GitHub URLs and malformed links are ignored.