# LabTab Markdown Sync

Download selected LabTab wiki and meeting notes into your Obsidian vault.
Edit shared notes in LabTab and keep personal notes alongside the downloaded
copies in Obsidian.

The plugin is free and requires a LabTab account with access to a lab.
Hosted LabTab plans are billed separately. See [LabTab pricing](https://labtab.app/pricing).
Custom deployments need to support the LabTab Markdown Sync API.

## Installation

Requires Obsidian desktop 1.11.4 or later. Mobile support has not been tested
and is disabled in this release.

Until the plugin is listed in Community plugins, install it manually:

1. Download `main.js` and `manifest.json` from the
   [latest release](https://github.com/labtabapp/labtab-obsidian-plugin/releases/latest).
2. Create `.obsidian/plugins/labtab-markdown-sync/` inside your vault.
3. Copy both files into that folder.
4. Reload Obsidian and enable **LabTab Markdown Sync** under **Settings → Community plugins**.

## Connect and download

1. Open the plugin settings. The address defaults to `https://labtab.app`.
   Change it if your lab uses a custom LabTab address.
2. Select **Connect** and approve read-only access in your browser.
3. Return to Obsidian and select **Choose notes**.
4. Select wiki notes, meeting notes, or individual notes. Leave **Include future
   notes** enabled to include new notes from the selected categories.
5. Select **Preview download**, review the files, then select **Start mirror**.

New connections use `LabTab/<lab name>`, for example `LabTab/Example Lab`.
The plugin creates the folders when it downloads notes. You can choose another
folder in settings. Existing connections and folders keep their current paths.
Renaming a lab does not move downloaded files.

Starting the mirror enables automatic refresh every minute while Obsidian is
open. You can pause it in settings or select **Refresh** to check manually.
The plugin also checks when you return to Obsidian or reconnect to the network.

## Everyday use

Edit shared notes in LabTab. Each downloaded note includes an **Open in LabTab
to edit** link. Changes made in Obsidian do not update LabTab.

Keep personal annotations in separate notes and link to a downloaded note:

```markdown
See [[LabTab/Example Lab/Meetings/Experiment planning]].

Questions to discuss at the next meeting:
- Should we repeat the control experiment?
```

Wiki references become local links when their destination is included in the
mirror. Person references create local reference pages. Links to other wiki
notes open LabTab.

## Local files and edits

- If you edit a downloaded note, the next refresh saves your version in a
  separate `.local-edits.md` file before replacing the mirror with LabTab's
  version. Further copies get numbered filenames.
- Existing unrelated files are preserved. Filename collisions get a new path.
- Renaming a note in LabTab keeps its existing local filename so links still work.
- Deleted, inaccessible, deselected, or unsupported notes already downloaded
  stay in your vault but stop receiving updates.
- Changing the destination folder keeps the previous folder. Files moved or
  deleted locally are downloaded again at their tracked paths on refresh.

Notes without saved content, or with content the exporter does not support,
are marked **Unavailable** in the note selector. Other selected notes still
download. Attachments are not included.

This release supports one lab connection per vault. Importing local Markdown
into LabTab is a separate operation and is not provided by this plugin.

## Network access and privacy

The plugin connects to the LabTab address configured in settings. It uses the
network to pair your device, verify read-only access, list available notes, and
download selected notes. Pairing opens that LabTab site in your browser.

Pairing sends a generated device identifier, the plugin version, the requested
read-only permission, and the device approval code. Authenticated requests send
your access token and the identifiers needed to request notes. The plugin
never uploads vault content or local annotations.

The access token is stored in Obsidian SecretStorage. The vault's plugin settings
store the server address, selected notes, local paths, and refresh state. The
plugin lists and reads Markdown files within the selected mirror folder using
Obsidian's vault API. It does not list the rest of your vault or access files
outside the vault. It includes no analytics, advertising, or session replay code.

LabTab's server processes requests and records operational and security metadata.
The browser approval page is part of the LabTab web application. Its data
handling is described in the [LabTab privacy notice](https://labtab.app/privacy).
For a custom deployment, check the operator's privacy policy.

Earlier write-capable connections must be paired again. Pending uploads from
older versions are discarded without deleting local notes.

## Development

Use Node.js 22 or later:

```sh
npm ci
npm run check
```

This runs TypeScript checks, tests, the production build, and release-file checks.
`npm run dev` rebuilds the plugin when source files change.
The build produces a readable `main.js` without a source map. Test fixtures use
example data and are not included in the bundle.

## Releases

Update the version in `manifest.json`, `package.json`, `package-lock.json`,
`versions.json`, and the pairing client version in `src/api.ts`. Run
`npm run check` and commit the rebuilt `main.js` with the source changes.

Push a tag that exactly matches the manifest version, without a `v` prefix.
The release workflow runs the checks again, generates GitHub artifact
attestations, and attaches `main.js` and `manifest.json` to a GitHub release.
You can verify a downloaded file with
`gh attestation verify main.js --repo labtabapp/labtab-obsidian-plugin`.
A release can then be submitted through the
[Obsidian Community directory](https://community.obsidian.md).

## Support and license

Report problems through [GitHub issues](https://github.com/labtabapp/labtab-obsidian-plugin/issues).
Include the plugin and Obsidian versions and the steps that caused the problem.
Remove tokens, private note content, and personal details from any logs or screenshots.

Released under the [MIT license](LICENSE). This plugin is maintained by LabTab
and is not an official Obsidian product.