mdspec

Sync Markdown files between your local workspace and the mdspec platform — manually, explicitly, and safely.

No auto-sync. No background uploads. Nothing happens without you clicking a button.

Features

Sync local .md files to mdspec — upload a new spec or push a new revision with one click
Pull latest content from mdspec — overwrite a local file with the latest remote version
See remote specs not yet on your machine — browse specs from all your projects and link or download them locally
Preview remote specs — view rendered Markdown from any remote spec without downloading it
Download as editable copy — grab any remote spec as an independent local file you can edit and sync back
Hash-based change detection — the sidebar shows which files have changed since the last sync
Path-based slug generation — slugs are derived from the file path so files with the same name in different folders never conflict
Config-driven — all state lives in .mdspec/config.json, shareable with your team via git

Getting Started

1. Open the sidebar

Click the mdspec icon in the Activity Bar (left side of VS Code).

2. Log in

Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P), run mdspec: Login, and sign in through the browser window that opens. Your credentials never touch the extension — only the session token is stored securely in VS Code's secret storage.

3. Link your project

Run mdspec: Set Project from the Command Palette and enter your project in org-slug/project-slug format (e.g. my-org/product-docs). This is saved to .mdspec/config.json.

4. Track files

The sidebar lists all .md files in your workspace. Check a file to start tracking it. Only tracked files can be synced.

5. Sync and pull

Click the ↑ upload icon next to a tracked file to push it to mdspec. Click the ↓ download icon to pull the latest version down.

The Sidebar

mdspec
├── Project: my-org / product-docs
│
├── Local Specs
│   ☑ auth.md              ↓  ↑
│   ☑ api.md               ↓  ↑
│   ☐ notes.md
│   ☑ security.md    ●        ↑
│
├── Remote Only  (3)
│   my-org/product-docs
│   │   Onboarding Flow     👁  ↓
│   other-project
│   │   Billing Spec        👁  ↓  🔗
│   │   Auth Guide          👁  ↓  🔗
│
└── Open in Web

Element	Meaning
☑	File is tracked
☐	File is not tracked — check it to start tracking
↑	Upload this file to mdspec
↓	Pull latest content from mdspec (local files) or download as editable copy (remote files)
●	Local changes detected — download blocked, upload available
👁	Preview the remote spec as rendered Markdown
🔗	Link this remote spec as a read-only local file (other-project specs only)
Remote Only (n)	Number of projects with specs not yet linked locally
Open in Web	Opens your mdspec project in the browser

Local Specs

Tracking files

Check a file in the sidebar to track it. Uncheck to stop tracking. Only tracked files appear on mdspec.

Syncing (uploading)

Click the upload icon next to a tracked file.

First sync — creates a new spec on mdspec. The spec name is taken from the first # Heading in the file (falling back to the filename). The slug is derived from the file path relative to the workspace root, so docs/api/reference.md becomes the slug docs-api-reference. This ensures files with the same name in different folders never conflict on the server.
Subsequent syncs — uploads a new revision of the existing spec. If the content is identical to the latest revision, no new revision is created.
Config recovery — if your .mdspec/config.json is lost or reset, the first sync will detect the existing spec on the server (via the path-based slug) and re-establish the local mapping automatically, then upload a new revision. No data is lost.

Pulling (downloading)

Click the download icon next to a tracked file to overwrite your local copy with the latest content from mdspec.

Download is blocked if your local file has changed since the last sync. You will see: "Cannot download — you have local changes. Sync first or discard your changes." This prevents you from accidentally losing work.

Remote Only

The Remote Only section lists specs from all your projects that have no local file yet. The section label shows the number of projects with unlinked specs. It is hidden when you are not logged in.

Specs are grouped by project. Your configured project always appears at the top, even if all its specs are already tracked locally.

Server-side linked proxy specs are never shown — only original source specs appear here.

Previewing a remote spec

Click the 👁 eye icon to open the spec as a rendered Markdown preview. The content is fetched from the server and written to a temporary file ({os.tmpdir()}/mdspec-preview-{slug}.md), then opened in VS Code's built-in Markdown preview. Nothing is added to your workspace or config.

Downloading as an editable copy

Click the ↓ download icon next to any remote spec to save it as an independent local file you can edit and sync back. You will be prompted for a local path (pre-filled as <specRoot>/<slug>.md). The file is tracked as a regular spec — not a read-only link — so you can push revisions back to mdspec just like any locally created spec.

If a file already exists at the chosen path, you will be asked to confirm before overwriting.

Linking a spec from another project

Click the 🔗 link icon (only available for specs from other projects) to create a read-only local copy that stays in sync with the remote source. You will be prompted for a local path. The extension creates a server-side linked proxy and downloads the current content. Linked files show a linked label in Local Specs and can only be pulled — not synced back.

Change Detection

The extension uses SHA-256 hashing, not timestamps.

When you sync a file, a hash of the content is saved. On subsequent saves or refreshes, the current hash is compared with the saved one. If they differ, the file shows a ● in the sidebar.

Edit and save a file → dot appears
Undo edits until content matches the last sync → dot disappears
Whitespace-only changes still count as changes

Configuration

The extension stores its state in:

.mdspec/config.json

This file is created automatically. It contains your linked project, which files are tracked, the remote slug and spec ID for each file, and the last synced content hash.

You can commit this file to your repository so your whole team shares the same tracked file mappings.

Settings

Setting	Default	Description
`mdspec.apiBaseUrl`	`https://mdspec.dev/api`	Base URL for the mdspec API
`mdspec.project`	(empty)	Project in `org-slug/project-slug` format

Open Settings (Cmd+, / Ctrl+,) and search for mdspec.

Supported Frontmatter

When updating via the API or editing content, you can use YAML frontmatter to automatically update this document's metadata. If you use frontmatter to define a field, it will overwrite the metadata configured in the UI interface.

---
status: planned | in-progress |
        completed
maturity: draft | review |
          stable | deprecated
progress: 0-100
tags: ["api", "backend"]
---

Commands

Command	Description
`mdspec: Login`	Sign in via browser
`mdspec: Logout`	Clear stored session
`mdspec: Set Project`	Link this workspace to an mdspec project

Syncing, pulling, and linking remote specs are done via the inline buttons in the sidebar.

What This Extension Does Not Do

Delete local files
Delete specs from mdspec
Auto-sync in the background
Show diffs
Manage comments, users, or billing

Troubleshooting

"Not authenticated" error Your session may have expired. Run mdspec: Login again.

File not showing in the sidebar

Confirm it has a .md extension
Confirm it is not inside node_modules, .git, dist, or .mdspec
Click the refresh button at the top of the sidebar
If specRoot is set in your config, the file must be under that folder

"Cannot download — you have local changes" Your local file has been modified since the last sync. Upload your changes first, or revert the file to its last synced state, then try pulling again.

Sync failed with 409 Conflict Two different files in your workspace are producing the same path-based slug (e.g. docs/auth.md and auth.md after stripping special characters). Move one of the files to a different folder so their paths are unique, then sync again.

"Usage limit reached" error when syncing You have hit the spec limit on your current plan. Click the Upgrade Plan button in the error notification to open your account settings.

Remote Only section is not showing Make sure you are logged in. The section only appears after authentication. Click the refresh button to reload.