GitHub Wiki

Obsidian plugin that allows a vault to be stored in a Github Wiki, or edit existing Wikis with Obsidian.

Network use

This plugin makes outbound HTTPS requests to github.com to clone, fetch, and push your wiki repository. There are four user-controlled triggers for these requests (all toggleable in Settings → GitHub Wiki):

1. The Sync now command, ribbon icon, or status-bar click.
2. Sync on startup — once when the plugin loads.
3. Auto-sync on file change — debounced after edits to files inside the wiki folder.
4. Periodic sync interval (minutes) — re-syncs on a self-rescheduling timer while Obsidian is running. Disabled by default (0); set to a positive number to opt in.

No data is sent to anywhere other than the GitHub wiki repository you configure (https://github.com/<owner>/<repo>.wiki.git). The plugin does not collect telemetry, analytics, or crash reports.

Authentication

The plugin offers two ways to authenticate with GitHub:

1. Sign in with GitHub (recommended) — click Sign in with GitHub in settings. The plugin uses GitHub's OAuth device flow: it shows a short code, you enter it in your browser, and the plugin receives an access token automatically. No personal access token to create or paste. This goes through an OAuth App owned by the plugin author; it requests the repo scope (required to read and write the private .wiki.git repository) and no client secret is involved. Signing out removes the token from your device only — to fully revoke the grant, use GitHub → Settings → Applications → Authorized OAuth Apps.
2. Personal access token — alternatively, paste a classic PAT with repo scope (generate at https://github.com/settings/tokens). Use this if you'd rather not authorize the shared OAuth App.

Local development

Obsidian loads plugins from <vault>/.obsidian/plugins/<plugin-id>/. The plugin id for this project is obsidian-github-wiki. Three files must live in that folder for Obsidian to load it: main.js, manifest.json, styles.css.

You can either keep this repo somewhere else and symlink it into a vault, or clone it directly inside the vault's plugins folder. Symlink is recommended — one checkout, multiple test vaults.

1. Build the plugin

npm install
npm run dev   # esbuild watch; rebuilds main.js on every save

Leave this running. npm run build instead for a one-shot production build.

2. Link the repo into a test vault

Pick or create a scratch vault (a normal folder is fine — Obsidian → Open another vault → Create new vault). Then link this repo as the plugin folder:

Windows (PowerShell, run as admin OR with Developer Mode enabled):

$vault = "C:\path\to\YourVault"
New-Item -ItemType Junction -Path "$vault\.obsidian\plugins\obsidian-github-wiki" -Target "C:\Users\ben\projects\obsidian_github_wiki"

macOS / Linux:

VAULT=~/path/to/YourVault
ln -s "$PWD" "$VAULT/.obsidian/plugins/obsidian-github-wiki"

(If .obsidian/plugins/ doesn't exist yet, mkdir -p it first.)

3. Enable in Obsidian

1. Open the vault in Obsidian.
2. Settings → Community plugins → turn off Restricted mode if it's on.
3. Under Installed plugins, you'll see GitHub Wiki. Toggle it on.
4. A new GitHub Wiki tab appears in Settings — fill in:
   • Authentication — click Sign in with GitHub, or paste a personal access token (see Authentication above).
   • Repository owner / Repository name — the repo whose wiki you want to sync.
   • Wiki folder — defaults to Wiki. Top-level files inside this vault folder map to wiki pages.
5. The wiki on github.com must already have at least one page; GitHub doesn't initialize the .wiki.git repo until you save a page through the web UI.

4. Iterate

• Edit code → esbuild rebuilds main.js.
• In Obsidian, reload the plugin: open the command palette and run Reload app without saving, or toggle the plugin off/on in Settings → Community plugins. The community Hot Reload plugin (search for it in Community plugins → Browse) auto-reloads on main.js change and is worth installing for plugin work.
• Trigger a sync: ribbon icon (refresh-cw), the Sync now command in the palette, click the status bar entry, or just edit a file in the wiki folder and wait for the debounce.

5. Mobile

The plugin is mobile-compatible (isDesktopOnly: false). To test on Obsidian mobile, you need the built files inside a vault that syncs to your device — Obsidian Sync, iCloud, Syncthing, etc. The dev-mode symlink trick doesn't work on mobile; just npm run build and copy main.js, manifest.json, styles.css into the synced vault's plugins folder.