# Obsidian 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

```sh
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):**
```powershell
$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:**
```sh
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](#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.