CodeRef - Live GitHub Snippet Sync Plugin for Obsidian

Copy-pasting code into Obsidian docs is fine until the repo changes and your docs lie to every developer who reads them. CodeRef is an Obsidian plugin that syncs live code snippets from GitHub using an @include syntax — docs that never go stale.

𝕏 Post Reddit HN

Difficulty

intermediate

What is it?

Developers using Obsidian for internal docs constantly paste static code snippets that drift out of sync with the actual repo within weeks. CodeRef adds a simple @include(github:owner/repo/path/to/file#L10-L25) syntax to Obsidian markdown, auto-fetches the live snippet on note open, and diffs it on demand. The plugin targets technical writers and dev teams using Obsidian as a second brain for architecture docs. Teams of 5+ pay $29/month for the hosted sync relay that bypasses GitHub rate limits. Why buildable now: Obsidian's plugin API is stable, GitHub REST API supports line-range fetches natively, and the Obsidian community has 1M+ users actively installing plugins.

Why now?

Obsidian crossed 1M users in 2024 and the plugin ecosystem is the primary growth driver — a live code sync plugin has been requested in GitHub issues and Discord threads repeatedly with no shipped solution.

▸@include(github:owner/repo/path#L10-L25) syntax parsed and resolved on note open.
▸Diff badge showing when live snippet diverges from embedded version.
▸Private repo support via GitHub OAuth token stored in Obsidian settings.
▸Team sync relay server bypassing GitHub API rate limits for 5+ users.

Target Audience

Technical writers and dev teams using Obsidian for internal docs — roughly 200k technically-oriented Obsidian users globally.

Example Use Case

A senior engineer at a 20-person startup writes architecture docs in Obsidian, embeds @include snippets from their monorepo, and every teammate reading the doc sees the current code — no more 3-month-stale copy-paste accidents.

User Stories

▸As a senior engineer, I want to embed live GitHub snippets in my Obsidian architecture docs, so that teammates always read current code.
▸As a technical writer, I want a diff badge when the repo changes, so that I know which docs need updating.
▸As a team lead, I want private repo snippet support, so that internal code never leaks through public API calls.

Done When

✓Snippet render: done when user writes @include block and sees live code appear in reading view within 3 seconds
✓Diff badge: done when repo line changes and a yellow badge appears on the note without manual refresh
✓Settings: done when user enters GitHub token and sees a green connected indicator
✓Team billing: done when team lead pays Stripe and all 5 teammates bypass rate limits via relay.

Is it worth building?

$29/month x 80 team plans = $2,320 MRR at month 4. Assumes 2% conversion from plugin installs via Obsidian community plugin browser.

Unit Economics

CAC: $5 via Obsidian Discord organic posts. LTV: $348 (12 months at $29/month). Payback: under 1 month. Gross margin: 92%.

Business Model

Free for solo users (10 syncs/day). $29/month team plan (5+ users, unlimited syncs, private repo support).

Monetization Path

Free plugin drives installs, private repo support and team sync relay triggers upgrade, Stripe handles billing.

Revenue Timeline

First dollar: week 3 via first team plan. $1k MRR: month 4. $3k MRR: month 8.

Estimated Monthly Cost

Supabase Edge Functions: $10, GitHub API: free tier sufficient, Stripe fees: ~$10 at early MRR. Total: ~$20/month at launch.

Profit Potential

Side-income viable at $1k-$3k MRR, full-time if Notion plugin ships.

Scalability

Medium — can expand to GitLab and Notion plugin, add webhook-triggered auto-refresh.

Success Metrics

500 plugin installs in month 1. 20 team plan conversions by month 3. Under 5% monthly churn.

Launch & Validation Plan

Post WIP plugin to Obsidian Discord dev channel, get 10 installs and 3 paying beta teams before publishing to community plugin browser.

Customer Acquisition Strategy

First customer: post a demo GIF in the Obsidian Discord plugins channel and offer free team plan for 60 days to first 5 teams who reply. Ongoing: Obsidian community plugin browser listing, r/ObsidianMD subreddit, developer Twitter/X.

What's the competition?

Competition Level

Low

What's the roadmap?

Feature Roadmap

V1 (launch): @include syntax, live fetch, diff badge, private repo OAuth. V2 (month 2-3): GitLab support, webhook auto-refresh on push. V3 (month 4+): Notion plugin, VS Code extension parity.

Milestone Plan

Phase 1 (Week 1-2): Plugin parses @include, fetches and renders snippets locally. Phase 2 (Week 3): Relay server live, Stripe billing working, diff modal shipped. Phase 3 (Month 2): 20 team plan customers, plugin listed in Obsidian browser.

How do you build it?

Tech Stack

TypeScript, Obsidian Plugin API, GitHub REST API, Supabase Edge Functions, Stripe — build with Cursor for plugin logic and API integration

Suggested Frameworks

Obsidian Plugin API, Octokit (GitHub SDK), Supabase Edge Functions

Time to Ship

2 weeks

Required Skills

TypeScript, Obsidian Plugin API, GitHub OAuth, Supabase Edge Functions.

Resources

Obsidian plugin developer docs, Octokit README, Supabase Edge Functions quickstart.

MVP Scope

src/main.ts (plugin entry point and @include parser), src/github-client.ts (Octokit fetch and line-range logic), src/sync-modal.ts (diff viewer modal), src/settings.ts (GitHub token and relay config), src/styles.css (snippet block styling), manifest.json (plugin metadata), supabase/functions/relay/index.ts (rate-limit relay Edge Function), .env.example (required env vars)

Core User Journey

Install plugin -> add GitHub token -> write @include block -> see live snippet render -> share note with teammate -> teammate upgrades to team plan.

Architecture Pattern

Note opens -> @include syntax detected -> Octokit fetches GitHub line range -> snippet rendered in note -> diff badge compares cached vs live -> team relay proxies API calls for rate limit safety.

Data Model

Plugin local config has one GitHubToken. Note has many IncludeDirectives. IncludeDirective has one CachedSnippet. Team relay has many APIKeys mapped to UserWorkspaces.

Integration Points

GitHub REST API for snippet fetching, Octokit SDK for API wrapper, Supabase Edge Functions for relay server, Stripe for team billing, Obsidian Plugin API for note rendering.

V1 Scope Boundaries

V1 excludes: GitLab support, Notion plugin, webhook-triggered auto-refresh, CI/CD integration, syntax highlighting themes.

Success Definition

A dev team the founder has never met installs the plugin, upgrades to the team plan via Stripe, and uses it daily for 90 days without filing a support ticket.

Challenges

Distribution inside the Obsidian ecosystem depends entirely on the community plugin browser ranking — without early reviews and installs, discovery is near-zero.

Avoid These Pitfalls

Do not require a backend for the free solo tier — Obsidian users distrust plugins that phone home. Do not launch on community browser before testing on 10 real vaults. Finding the first 10 paying teams will take 3x longer than building — budget distribution time accordingly.

Security Requirements

GitHub tokens stored in Obsidian local settings only, never sent to relay except as hashed team API key, HTTPS only on relay, input validation on all @include path params.

Infrastructure Plan

Obsidian plugin distributed via community browser, Supabase Edge Functions for relay, Stripe for billing, GitHub Actions for plugin build and release — total ~$20/month at launch.

Performance Targets

Snippet fetch under 800ms on note open, diff comparison under 100ms local, relay handles 500 req/min at team scale, plugin bundle under 200KB.

Go-Live Checklist

☐Security audit complete
☐Stripe team plan tested end-to-end
☐Sentry error tracking in relay live
☐Relay uptime monitor configured
☐Plugin manifest validated by Obsidian bot
☐Privacy policy published
☐5 beta team vaults tested
☐Rollback plan documented
☐Obsidian Discord and r/ObsidianMD launch posts drafted.

First Run Experience

On first run: a sample note with 2 pre-written @include directives pointing to a public GitHub repo is shown in the plugin welcome modal. User can immediately click render and see live snippets without entering a token. No manual config required: public repo fetching works with no GitHub token set.

How to build it, step by step

1. Define @include syntax spec and cached snippet schema in a types.ts file. 2. Scaffold plugin with Obsidian plugin template via npm create obsidian-plugin. 3. Build Octokit GitHub client with line-range fetch and error handling. 4. Build markdown post-processor that detects and replaces @include blocks on note render. 5. Build settings tab for GitHub token and relay URL configuration. 6. Build diff modal comparing cached vs live snippet with line-level highlights. 7. Deploy Supabase Edge Function as GitHub API relay with rate limit pooling. 8. Add Stripe payment link for team plan with webhook to provision relay API key. 9. Write manifest.json and submit to Obsidian community plugin browser. 10. Verify: open a note with an @include block, confirm live snippet renders, change a line in GitHub, reopen note, confirm diff badge appears.

Generated

April 20, 2026

Model

claude-sonnet-4-6

← Previous

PulseKeep - Self-Hosted Uptime Monitor With a Status Page That Doesn't Look Like 2009

ChurnLens - NLP Support Ticket Churn Predictor for SaaS Teams

Disclaimer: Ideas on this site are AI-generated and may contain inaccuracies. Revenue estimates, market demand figures, and financial projections are illustrative assumptions only — not financial advice. Do your own research before making any business or investment decisions. Technology availability, pricing, and market conditions change rapidly; always verify details independently.