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. The token needs the content and deploy scopes. Content publishes the notes, and deploy puts them live through POST /sites/{siteId}/deployments, which the plugin posts after the notes have been saved. With content alone the notes still publish and only the build is refused, which is the same outcome as turning Trigger build off. See authentication for details on tokens and scopes.
- If your workspace has more than one site, optionally set a site ID, either the short ID shown in the dashboard or the full UUID. 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, as a short ID or UUID. 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. |
| api_endpoint | Marks the page as an API reference, like GET /sites/{siteId}/pages. See API reference pages. |
| draft | Set to true to keep the page off the deployed site. |
| show_listings | Homepage only: whether recent posts and section listings show below the content. true or false. |
| tags | A list of tags. Casing is kept as the display name: iOS is stored as ios and displays as iOS. |
| date or publishedAt | Publish date. |
| author | Author to credit the page to, as an author ID from GET /sites/{siteId}/authors (not a name, because names are not unique). Empty string removes the author. |
| password | Password-protects the page (min 8 chars, Pro). Empty string removes the protection. Your vault is private, so a password here is as safe as typing it in the dashboard. Do not use this field in a vault you sync to a shared repository. |
| og_image_url | Social preview image URL. |
| language | Language tag for the page, like en or pt-BR. |
| theme, primary_color, primary_color_dark, font_size, code_theme_light, code_theme_dark, gallery_download_position | Per-page theme overrides. Empty string resets a field to inherit from the site. |
| show_toc | Table of contents. |
| show_social_share | Social share buttons. |
| show_comments | Comments. |
| show_next_prev | Next/previous post navigation. |
| show_newsletter_cta | Newsletter signup CTA. |
| show_tags | Tag chips. |
| show_dates | Publish dates. |
| show_author | Author byline. |
| show_reading_time | Reading time estimate. |
| show_breadcrumbs | Breadcrumbs. |
| show_copy_markdown | Copy-as-Markdown button. |
| show_gallery_download | Gallery “Download all” button, which serves the gallery as a ZIP. |
| show_gallery_item_download | Download buttons on individual gallery photos and videos, in the grid and the lightbox. |
| full_width_gallery | Full-width gallery grid (photographer theme). |
| masonry_gallery | Masonry gallery grid (photographer theme). |
The boolean theme overrides above are tri-state: true, false, or "inherit" to fall back to the site setting. Front matter names them in snake_case; the API names the same fields in camelCase.
Colors are hex in the form #RRGGBB. Put them in quotes, as in primary_color: "#336699", because YAML reads an unquoted # as the start of a comment and the color is then ignored.
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 token that is missing the content scope, a Pro plan being required, a storage or deploy quota limit, or a validation error naming the field that failed. A token missing the deploy scope is reported on its own, because it fails the deploy request rather than the publish that came before it. 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 deployments reference.