Import player-safe Recap Raven session recaps into your vault as structured Markdown, with previews, duplicate detection, safe filenames, campaign indexes, and create-only writes.
Import player-safe Recap Raven session recaps into your vault as structured, local Markdown, with optional normalised transcripts in linked notes beneath each recap. Imports are manual and create-only: existing notes are never overwritten or deleted.
The plugin uses a campaign-bound Obsidian export key and never uploads vault content. Transcript importing is off by default and requires explicit permission in both the key and plugin settings. Transcripts may contain private GM material; use a vault intended to hold that material.
Once the plugin is listed in the Obsidian Community Plugins directory, install and enable Recap Raven from Settings → Community plugins.
Before the Community listing is available, download main.js, manifest.json, and styles.css from the latest GitHub release. Place them in .obsidian/plugins/recap-raven/ inside a dedicated vault, reload Obsidian, and enable Recap Raven under Community plugins. Only install release assets published by the Recap Raven GitHub organization.
recap-raven-api-key, then paste your campaign-bound raven_obs_… key as its value.The export key fixes the campaign on the server. The integration cannot select another campaign or broaden the key's access. New keys can be created for active campaigns; an existing key continues to support importing history after its campaign is archived.
Select the download icon in the ribbon, or open the command palette and run one of these commands:
Campaign index.md contains different content, the plugin creates Campaign index (Recap Raven).md alongside it.By default, notes are created under:
Recap Raven/<Campaign name>/Sessions/YYYY-MM-DD - Session <number> - <Title>.md
The recorded-date prefix keeps notes in chronological filename order. When a recorded date is unavailable, the filename begins with the session number instead.
If a destination is already occupied by an unrelated note, the importer uses a stable short session-ID suffix. If the session ID is in the plugin's private import index, the recap is skipped. Files are never overwritten, updated, renamed, moved, or deleted.
To include normalised session transcripts, create an export key with transcript access and enable Include session transcripts in the plugin settings. This is off by default. Transcripts may contain private GM material; enable it only for a vault intended to hold that material. Each transcript is created at <recap filename>/Transcript.md, with a link back to the recap. New recaps also link to their transcript. Existing recaps can receive a missing transcript without changing the recap; existing transcript files are preserved. If a transcript write fails after its recap is created, repeat the import to retry the missing transcript. For an existing campaign index, run Create campaign index to create a recap-only index alongside it; existing files are preserved.
Existing export keys continue to work for recaps. To enable transcripts for an active campaign with an existing key, revoke that key, create a replacement with transcript access, and select the replacement secret in Obsidian before enabling Include session transcripts. Only one export key can be active per campaign. Rotating a key preserves its permissions and does not enable transcript access.
Each session note includes YAML properties similar to:
recap_raven_session_id: "00000000-0000-4000-8000-000000000000"
recap_raven_campaign_id: "00000000-0000-4000-8000-000000000001"
recap_raven_campaign: "The Glass Archive"
session_number: 7
title: "Through the Silver Door"
recorded_at: "2026-08-15T18:30:00Z"
ready_at: "2026-08-16T01:00:00Z"
artifact_created_at: "2026-08-16T00:59:00Z"
source_url: "https://recapraven.com/recaps/00000000-0000-4000-8000-000000000000"
content_sha256: "..."
tags: ["recap-raven", "session-recap"]
Before writing a note, the integration validates the campaign and session identities, source URL, content integrity, and size, and rejects potentially active content.
This integration requires a Recap Raven account and a campaign-bound export key. Plugin-initiated network activity occurs only when you:
API requests are sent only to https://api.recapraven.com. They use read-only endpoints to download the bound campaign's player-safe metadata and recap Markdown, plus normalised transcripts when enabled in both the export key and plugin settings. Transcript identities, size, and SHA-256 integrity are checked before the text is escaped for safe Markdown display. Requests include the export credential and ordinary connection and request metadata. Recap Raven keeps limited operational and security logs, including API-key use and IP-related security events, as described in the Recap Raven Privacy Policy.
The plugin does not upload vault notes, attachments, filenames, or other vault content to Recap Raven, and contains no client-side analytics or tracking.
Opening a recap uses https://recapraven.com. The URL is reconstructed from the validated session ID rather than trusting an editable URL in note properties.
Imported recaps and non-secret preferences are stored in the current vault. Non-secret settings and a private duplicate-detection index containing only imported session IDs and their local paths are written to .obsidian/plugins/recap-raven/data.json. The API-key value is stored through Obsidian SecretStorage; data.json retains only the selected secret's name.
Obsidian does not isolate SecretStorage entries from other installed community plugins. Another plugin running in the same Obsidian instance may be able to request a secret by name, so install only plugins you trust. SecretStorage is local to a vault/device and is not a substitute for revoking a key that may have been exposed.
Imported notes are ordinary vault files and may be copied by your Obsidian Sync, backup, sharing, or Publish configuration.
Removing or revoking a credential does not delete Markdown files already imported into your vault.
The plugin is desktop-only while mobile behavior is tested. The implementation uses Obsidian's request and Vault APIs so mobile support can be evaluated later without changing the security model.
When upgrading from 1.2.0 or earlier, the plugin discovers prior imports only inside the selected campaign's managed Sessions folder. A prior import moved elsewhere while the plugin was disabled cannot be discovered without scanning unrelated vault files; importing that session again may therefore create another note. The plugin intentionally accepts this narrow migration limitation to avoid vault-wide enumeration.
make check
The Makefile runs installation, ESLint and Obsidian Community CSS linting, tests, coverage, type-checking, and the production build inside the pinned Node container; no host Node installation is required.
For manual testing, copy main.js, manifest.json, and styles.css into a folder named recap-raven under a dedicated test vault's plugins directory. Do not develop or test import behavior in your primary vault.
Release tags exactly match the semantic version in manifest.json and do not use a v prefix. Each GitHub release contains:
main.jsmanifest.jsonstyles.cssMaintainers prepare a version with make version VERSION=1.0.1. This updates package.json, package-lock.json, manifest.json, and versions.json; the release workflow rejects mismatched versions, tags, or assets.
This is an owner-maintained repository. Please open an issue for bugs and improvement proposals; external code pull requests are closed without running contributed code. See CONTRIBUTING.md for the rationale and development standards.
Use the repository issue tracker for bugs and feature requests. Do not include API keys, authorization headers, SecretStorage contents, or private campaign material in an issue.
For a suspected credential exposure, revoke the key immediately from the Recap Raven API-key page. Report vulnerabilities privately using the process in SECURITY.md, never a public issue.