Publish from Obsidian
The Sitepaste plugin for Obsidian publishes notes from your vault to your site without leaving the editor. It handles single notes and whole folders, with a confirmation step before anything is sent.
Publishing through the plugin requires an API token, which is a Pro plan feature.
Setup
- Install the Sitepaste plugin from Obsidian’s community plugins.
- Open Settings > Sitepaste.
- Enter an API token from the Sitepaste dashboard, under Account > Tokens. See authentication for details on tokens.
- If your workspace has more than one site, optionally set a site ID. Leave it empty to publish to your default site.
Publishing
There are three ways to publish:
- Click the upload icon in the ribbon to publish the note you are editing.
- Run “Publish current file” from the command palette.
- Right-click a file or folder in the file explorer and choose “Publish to Sitepaste” or “Publish folder to Sitepaste”.
Before anything is sent, the plugin shows a confirmation listing every page that will be created or updated. Folder publishes show progress as pages sync.
After publishing, the plugin writes two fields into the note’s front matter: sitepaste-slug, which tells the plugin to update the same page next time instead of creating a new one, and sitepaste-published, the time of the last publish. Note that once sitepaste-slug exists, it is what identifies the page. Editing a slug field will not move the published page.
Settings
| Setting | Default | Description |
|---|---|---|
| API key | Your Sitepaste API token. | |
| Site ID | Optional target site. Leave empty for your default site. | |
| Default content type | docs | Used for notes that do not set one in front matter. Options: docs, blog, standalone. |
| Trigger build | On | Deploys the site after publishing. Turn off to batch several publishes into one deploy and save quota. |
| Dry run | Off | Validates and shows a summary without sending anything. |
Front matter
All fields are optional. Without front matter, the slug comes from the filename and the title from the slug.
| Field | Description |
|---|---|
| slug | URL slug for the page. |
| title | Page title. |
| contentType | docs, blog, standalone, or homepage. |
| section | Groups the page under a path: /docs/guides/page for docs and blog, /guides/page for standalone. See Sections. |
| description | Meta description. |
| draft | Set to true to keep the page off the deployed site. |
| tags | A list of tags. |
| date or publishedAt | Publish date. |
Your vault’s folder structure is not used. Unlike the GitHub Action, the plugin takes sections only from front matter. This means you can organize your vault however you like and decide the site structure per note.
Folder publishing
Publishing a folder includes every Markdown file inside it, subfolders included. The plugin checks for duplicate slugs and validates everything before sending. Very large folders are split into batches automatically, and the deploy is triggered only after the final batch succeeds. Homepage pages must be published individually, since a site has only one.
Errors
Problems surface as a notice with a plain message, such as an invalid API key, a Pro plan being required, a storage or deploy quota limit, or a validation error naming the field that failed. If a large publish times out, the pages may still have been saved; check the dashboard before retrying.
The plugin source lives in the integrations repository. For the underlying API, see the pages and builds reference.