Using the Obsidian plugin

The Valeon plugin connects your Obsidian vault to the author dashboard. With it, you can:

• Draft posts locally, in Obsidian, with everything offline.
• Publish a draft to the dashboard with one command.
• Pull a post back from the dashboard for further editing.
• Sync your whole vault against the dashboard, or restore your vault from scratch.
• Validate (“lint”) a post against Valeon’s editorial rules before publishing.

It handles the small details for you: media uploads, cover image rewriting, cross-post link translation, and conflict detection.

In Obsidian:

1. Open Settings → Community plugins. If you haven’t before, turn on community plugins.
2. Click Browse, search for Valeon, and install it.
3. Enable the plugin once installation finishes.

The plugin authenticates against the dashboard using a personal API key.

1. Open the dashboard at author.valeon.blog and go to Settings → API keys (see API keys for the full flow).
2. Create a key — name it after the device it’ll live on (e.g., “Laptop Obsidian”).
3. Copy the key. The dashboard only shows it once.
4. In Obsidian, open the Valeon plugin settings and paste it into the API token field (the plugin still uses the older “token” label).
5. Click Test connection. You should see a success modal with your name, slug, and the key’s name.

Once you’ve connected, run Valeon: Sync template from server from Obsidian’s command palette. This downloads the current schema and taxonomy (categories, series, allowed fields) from the dashboard and writes them to a local cache.

Without this step, the plugin doesn’t know what categories you can pick from or how the frontmatter should be shaped. Re-run this command whenever an editor adds new categories or series so your local linter and Valeon: New post stay current.

The plugin expects each post in its own folder, with a specific layout:

vault-root/
├── 2026-05-21-your-post-slug/
│   ├── post.md
│   └── assets/
│       ├── cover.png
│       └── diagram.svg
└── 2026-05-18-another-post/
    └── post.md

The folder name is YYYY-MM-DD-slug. The post itself is always post.md inside that folder. Media for the post lives in an assets/ subfolder. The cover image is referenced from the post’s frontmatter as ./assets/cover.png.

Creating

Run Valeon: New post from the command palette. You’ll be prompted for a title; the plugin creates the dated folder, drops in a post.md pre-filled with frontmatter, and opens it.

Linting

Before publishing, run Valeon: Lint post. The linter checks the post against the dashboard’s rules — required fields, valid categories, slug format, excerpt length, cross-post references that resolve, etc. A panel lists any errors and warnings, grouped by field. Errors block publishing; warnings don’t.

Publishing

Run Valeon: Publish. The plugin lints first, then:

1. Hashes every asset referenced by the post.
2. Uploads any that aren’t already on the server (deduplicated by hash).
3. Rewrites the body’s local image paths to the dashboard’s /m/{id} URLs (for the upload only — your local file isn’t changed).
4. Creates a new post in the dashboard (first publish) or updates the existing one.
5. Writes the returned post ID and timestamps back into your local frontmatter under a valeon: block.

The first publish creates a draft in the dashboard. Subsequent publishes update it. Going from draft to live still happens in the dashboard’s publishing flow.

If you edit a post in the dashboard and want those changes in your vault, three commands cover the different cases:

• Valeon: Pull post (published) — fetches the latest published version.
• Valeon: Pull post (draft buffer) — fetches the in-progress draft, if there is one; otherwise falls back to the published version.
• Valeon: Pull metadata — refreshes only the metadata in your valeon: block (publish date, reading time, audio URL). Doesn’t touch the body — useful right after a publish so your local file knows the live URL.

All three download any new media into the post’s assets/ folder and rewrite the body’s media URLs back to local paths.

A few commands act across the whole vault rather than the current note.

• Valeon: Sync vault — pulls every post in your vault that’s been updated on the server since the last sync. Conflicts get auto-backed up (a copy named post.local-backup-{timestamp}.md lands next to the original). A report is written to _reports/.
• Valeon: Restore vault from server — reconstructs your whole vault from the dashboard. Useful for setting up a new device or recovering from a disaster. Idempotent: re-running it is safe.
• Valeon: Reconcile vault (preview) — matches existing posts in your vault to posts on the server by slug and title and writes a dry-run report. Use this if you have a vault that pre-dates the plugin.
• Valeon: Reconcile vault (apply) — applies the matches by writing the right post ID into each note’s frontmatter. Run preview first.
• Valeon: Pull metadata (vault) — refreshes metadata across every linked note. Handy after a wave of dashboard edits.
• Valeon: Slugify tags (current file / vault) — rewrites every tag value to kebab-case. Useful tidying before publishing.
• Valeon: Open in dashboard — opens the current post’s editor page in your browser.

You can link from one post to another in two ways inside Obsidian:

• A relative link to the folder, like ../2026-05-18-other-post/post.md.
• A canonical Valeon URL, like https://valeon.blog/2026/05/21/some-post.

On push, both forms are translated into the stable cross-post format used by the dashboard. On pull, the reverse happens — links to posts in your vault become relative paths, links to posts you don’t own become canonical URLs. Query strings and anchors (like #a-section) are preserved end-to-end. See Cross-post references for the dashboard side of this feature.

Every linked post has a valeon: block at the end of its frontmatter. The plugin uses this block to remember which post a file maps to and when it was last synced. You don’t edit it directly — the plugin writes to it on push and pull.

It typically contains:

• postId— the post’s permanent identifier on the dashboard.
• publishedAt — when (or whether) the post is live.
• lastPushedAt and lastPushedBodyHash — used for conflict detection.
• remoteUpdatedAt — the server’s last-modified time as of your last sync.
• media— a map from your asset hashes to their storage IDs on the dashboard. Lets the plugin skip re-uploading anything that hasn’t changed.

This block is stripped before the post is sent to the server. It’s purely local state.

A conflict happens when you have local changes that haven’t been pushed yet, and the post on the dashboard has also been updated since the last time you synced. Pulling in that situation would overwrite your work.

The plugin detects this and shows a modal with three options:

• Save local as backup & pull — writes a backup copy of your file (named post.local-backup-{timestamp}.md) next to the original, then pulls. Safest choice — you keep your unpushed changes.
• Force pull, discard local — overwrites your file with the server version. Use only if you’re sure your local edits don’t matter.
• Cancel — leave the file untouched.

The bulk Sync vault command auto-backs up conflicting files without prompting, so a full sync never destroys local work.

The plugin works on the Obsidian mobile apps (iOS and Android) as well as the desktop. Every command, setting, and sync flow is available on mobile. The plugin uses Obsidian’s built-in HTTP and YAML primitives instead of Node.js libraries so the same code runs cross-platform.

If you use the same vault on multiple devices via Obsidian Sync (or another vault sync), expect the usual considerations — don’t edit the same post on two devices without syncing in between.

If you use the popular Obsidian Linter plugin, the Valeon plugin’s README has a recommended configuration: an explicit YAML key order, formatting for the pubDate and updatedDate timestamps, and a rule to ignore the _templates/ folder. Following it keeps your frontmatter tidy and consistent without conflicting with the Valeon plugin’s expectations.