v1.3.0: emit tropy_url deep link recovered from Tropy's Redux store

Each exported file now gets a `tropy_url:` field in its frontmatter,
pointing back to the source item in Tropy:

  tropy_url: "tropy://project/current/items/14410/14411"

Clicking the URL from a Markdown editor opens Tropy to that item with
its cover photo selected — the canonical way to review a transcription
against the original scan without leaving the analytical layer.

The challenge is that Tropy's JSON-LD export payload contains no
internal item IDs. The plugin recovers them by reading `state.items`
and `state.photos` from Tropy's Redux store (via
`this.context.window.store.getState()`) and building a
Map<photoPath, itemId> at the start of each export. Each JSON-LD item is
then matched to its store record by its first photo's path (more
reliable than checksum, which Tropy occasionally ships as
md5-of-empty-string for unprocessed photos). Once matched, the URL is
built from the item ID and either `cover_image_id` (rare) or the first
photo ID (typical), matching the behavior of the original Python
export script.

Graceful degradation: if the store isn't accessible (e.g. an older
Tropy version with a different shape), the lookup returns null and the
`tropy_url:` field is simply omitted. Nothing else in the export is
affected.

The field is renamable via the fieldRename setting, like any other
top-level YAML key. README updated with a "Tropy deep links" section
explaining the behavior and a sample tropy_url entry in the output-
shape example.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hepplerj

README.md

@@ -238,6 +238,7 @@ publication: ""
 date: "1907-10-15"
 doc_type: "letter"
 source: "Library of Congress, Gifford Pinchot Papers, Box 12, Folder 3"
+tropy_url: "tropy://project/current/items/14410/14411"
 people:
   - "[[Gifford Pinchot]]"
   - "[[Theodore Roosevelt]]"
@@ -281,6 +282,20 @@ is found, the key falls back to the URI's local name. **Collisions across
 namespaces are still possible** when two distinct URIs share the same
 local name and neither has an ontology label.
 
+## Tropy deep links
+
+Each exported file's frontmatter includes a `tropy_url:` field with a
+`tropy://project/current/items/<id>/<photo>` URL that, when clicked,
+opens Tropy to that item with its cover photo selected. Useful for
+jumping back to the source scan from inside your Markdown editor —
+particularly when reviewing a transcription against the original.
+
+The plugin recovers Tropy's internal item ID from the live project
+state (Tropy's JSON-LD export doesn't include it directly). If the
+state isn't accessible for any reason — e.g. an older Tropy version
+with a different store shape — the field is simply omitted; nothing
+else in the export is affected.
+
 ## Idempotency
 
 Each output filename embeds an 8-character `tropy_hash` derived from a

index.js

@@ -1,6 +1,6 @@
 'use strict'
 
-// Tropy.md — v1.2.0
+// Tropy.md — v1.3.0
 //
 // Exports each selected Tropy item to its own Markdown file in a chosen
 // directory. Markdown-editor neutral by default — no wiki-links, no opinionated
@@ -330,6 +330,49 @@ function extractPhotoPaths(item) {
   return photos.map(p => (p && p.path) || '').filter(Boolean)
 }
 
+function buildItemIdIndex(state) {
+  // Builds a Map<photoPath, itemId> from Tropy's Redux store so we can
+  // recover the internal item ID for a JSON-LD item — the export hook
+  // doesn't surface item IDs anywhere in its payload, but the store knows
+  // them. Matching on first-photo path is reliable: paths are unique per
+  // item and stable across exports (unlike checksums, which Tropy
+  // sometimes ships as md5-of-empty-string when it hasn't fully processed
+  // an import).
+  const items = (state && state.items) || {}
+  const photos = (state && state.photos) || {}
+  const index = new Map()
+  for (const item of Object.values(items)) {
+    const photoIds = (item && item.photos) || []
+    if (photoIds.length === 0) continue
+    const firstPhoto = photos[photoIds[0]]
+    if (firstPhoto && firstPhoto.path) {
+      index.set(firstPhoto.path, item.id)
+    }
+  }
+  return index
+}
+
+function tropyUrlFor(item, state, itemIndex) {
+  // Returns a `tropy://project/current/items/<itemId>/<photoId>` URL when
+  // we can recover the internal IDs from the store, or null otherwise.
+  // The plugin emits the URL into the frontmatter as `tropy_url:` when
+  // present so users can click back into Tropy from their Markdown editor.
+  if (!itemIndex || !state) return null
+  const photos = Array.isArray(item.photo) ? item.photo : []
+  if (photos.length === 0 || !photos[0] || !photos[0].path) return null
+  const itemId = itemIndex.get(photos[0].path)
+  if (itemId == null) return null
+  const storeItem = state.items && state.items[itemId]
+  if (!storeItem) return `tropy://project/current/items/${itemId}`
+  // Prefer cover_image_id when set (rare in practice); otherwise the
+  // first photo in the item's photos array — matches the Python script.
+  const coverId = storeItem.cover_image_id != null
+    ? storeItem.cover_image_id
+    : (Array.isArray(storeItem.photos) ? storeItem.photos[0] : null)
+  if (coverId == null) return `tropy://project/current/items/${itemId}`
+  return `tropy://project/current/items/${itemId}/${coverId}`
+}
+
 function photoEmbedMarkdown(photo) {
   // Returns a Markdown embed line for a photo, or null if the photo has
   // no path. Format:
@@ -434,6 +477,12 @@ function buildFrontmatter(item, hash, opts) {
     }
   }
 
+  // Tropy deep-link back to the source item. Constructed from internal
+  // IDs recovered via the Redux store; null when the lookup fails (e.g.
+  // running against a Tropy version with a different store shape).
+  const tropyUrl = tropyUrlFor(item, opts.state, opts.itemIndex)
+  if (tropyUrl) lines.push(`${k('tropy_url')}: ${yamlScalar(tropyUrl)}`)
+
   // Custom template properties — anything else on the item that isn't
   // structural or already rendered. Lets users with custom Tropy templates
   // see their data without us needing to know each field in advance.
@@ -626,19 +675,23 @@ class MarkdownPlugin {
   }
 
   buildOpts() {
-    // Pull Tropy's ontology if available so we can resolve custom-property
-    // URIs to human-readable labels. Older Tropy versions or different
-    // store shapes degrade gracefully — `ontologyLabel` returns null when
-    // a lookup fails.
-    let ontology = null
+    // Pull Tropy's ontology + items/photos index from the Redux store. The
+    // ontology gives us human-readable labels for custom-property URIs;
+    // the index lets us recover internal item IDs (not in the JSON-LD
+    // payload) so we can build `tropy://` URLs back to each item. Older
+    // Tropy versions or different store shapes degrade gracefully — both
+    // lookups return null on any failure and the rest of the plugin
+    // adjusts.
+    let state = null
     try {
-      const state = this.context.window && this.context.window.store
+      state = this.context.window && this.context.window.store
         ? this.context.window.store.getState()
         : null
-      ontology = (state && state.ontology) || null
     } catch {
-      ontology = null
+      state = null
     }
+    const ontology = (state && state.ontology) || null
+    const itemIndex = state ? buildItemIdIndex(state) : null
 
     return {
       workflowTags: parseCsvSet(this.options.workflowTags),
@@ -650,7 +703,9 @@ class MarkdownPlugin {
       filenamePattern: this.options.filenamePattern || 'tropy-{hash}-{slug}',
       embedPhotos: this.options.embedPhotos === true,
       fieldRename: parseFieldRename(this.options.fieldRename),
-      ontology
+      ontology,
+      state,
+      itemIndex
     }
   }
 
@@ -769,6 +824,8 @@ module.exports._internals = {
   extractPages,
   extractPhotoPaths,
   photoEmbedMarkdown,
+  buildItemIdIndex,
+  tropyUrlFor,
   localName,
   looksLikeUri,
   ontologyLabel,

package.json

@@ -1,7 +1,7 @@
 {
   "name": "tropymd",
   "productName": "Tropy.md",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Export Tropy items as Markdown files (one per item) with YAML frontmatter, suitable for Obsidian and other Markdown editors.",
   "icon": "icon.svg",
   "main": "index.js",