v1.0.0: field rename, first stable release

Adds a `fieldRename` option for renaming top-level YAML field names in
the frontmatter. Comma-separated `from=to` rules. The motivating case is
correspondence templates: Tropy stores the recipient as `dc:audience`,
which the plugin emits as `audience:` — users whose convention is
`recipient:` configure `audience=recipient` and get exactly that.

Rename applies to standard frontmatter fields (title, creator,
publication, date, doc_type, source, archive, collection, box, folder,
tags, photos) and to custom template properties that flow through the
passthrough. Tag-dispatched entity fields are unaffected — those are
already configurable via tagPrefixDispatch. The internal `tropy_hash:`
field is also non-renamable since idempotency depends on reading it.

This is also the first stable release. The release.yml workflow no
longer marks tags as pre-release; v1.0.0 lands as a real GitHub release.
README roadmap marks v1.0.0 done.

Verified end to end:
- fieldRename: creator=author, audience=recipient produces author/
  recipient YAML keys with values intact
- tropy_hash preserved (not renamable)
- All 3 fixture exports still idempotent under default config

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

Author: hepplerj

.github/workflows/release.yml

@@ -34,6 +34,6 @@ jobs:
         uses: ncipollo/release-action@v1
         with:
           artifacts: ${{ steps.meta.outputs.artifact }}.zip
-          prerelease: true
+          prerelease: false
           generateReleaseNotes: true
           token: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -150,6 +150,36 @@ require vault-relative paths or a specific image-loading config — if your
 editor doesn't render the embed, that's a path-resolution issue, not a
 plugin bug.
 
+### Field rename
+
+Comma-separated `from=to` rules that rename top-level YAML field names.
+Useful for matching the conventions of whatever Markdown vault you're
+exporting into. Default: empty (no renames).
+
+The most common case: Tropy's correspondence template stores the
+recipient as `dc:audience`, which the plugin emits as `audience:` by
+default. If your convention is `recipient:`, configure:
+
+```
+audience=recipient
+```
+
+Other examples:
+
+```
+creator=author, audience=recipient
+publication=published-in
+photos=attachments
+```
+
+The rule applies to standard frontmatter fields (`title`, `creator`,
+`publication`, `date`, `doc_type`, `source`, `archive`, `collection`,
+`box`, `folder`, `tags`, `photos`) and to custom template properties
+that flow through the passthrough. It does **not** apply to
+tag-dispatched entity fields — use the Tag prefix dispatch setting to
+name those. The internal `tropy_hash:` field is also non-renamable, since
+idempotency depends on it.
+
 ### Compose source fields
 
 On by default. When enabled, the standard archival fields (`source`,
@@ -249,7 +279,8 @@ a re-export of an item, delete its file from the output directory.
 - [x] **v0.4.0** — selection-attached notes; ontology-aware labels for
   custom template fields; configurable filename pattern; optional photo
   embedding in the body.
-- [ ] **v1.0.0** — feature-complete, polished docs, stable API.
+- [x] **v1.0.0** — field rename support; documentation polish; first
+  stable release.
 
 ## Development
 

index.js

@@ -1,6 +1,6 @@
 'use strict'
 
-// Tropy.md — v0.4.0
+// Tropy.md — v1.0.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
@@ -26,6 +26,37 @@ function parseCsvSet(s) {
   )
 }
 
+function parseFieldRename(s) {
+  // Parses the fieldRename config into a Map<from, to>.
+  //
+  // Format: comma-separated `from=to` pairs. The keys are the YAML field
+  // names the plugin would have written by default; the values are the
+  // names to use instead. Example:
+  //
+  //   creator=author, audience=recipient, publication=published-in
+  //
+  // Useful for matching downstream conventions (e.g. Tropy stores
+  // correspondence "recipient" as dc:audience, which the plugin emits
+  // through its passthrough as `audience:` — users who want `recipient:`
+  // map it explicitly here).
+  const map = new Map()
+  for (const entry of String(s || '').split(',')) {
+    const trimmed = entry.trim()
+    if (!trimmed) continue
+    const eq = trimmed.indexOf('=')
+    if (eq < 0) continue
+    const from = trimmed.slice(0, eq).trim()
+    const to = trimmed.slice(eq + 1).trim()
+    if (from && to) map.set(from, to)
+  }
+  return map
+}
+
+function renameYamlKey(opts, key) {
+  if (!opts.fieldRename) return key
+  return opts.fieldRename.get(key) || key
+}
+
 function parseDispatch(s) {
   // Parses the tagPrefixDispatch config into an ordered list of
   //   { prefix, field }
@@ -310,28 +341,36 @@ function buildFrontmatter(item, hash, opts) {
 
   const { fields, fieldOrder, leftover } = dispatchTags(allTags, opts.dispatch)
 
+  // Helper to keep emit sites readable. fieldRename is consulted at every
+  // YAML-key emission so users can match any downstream convention. The
+  // internal `tropy_hash:` and dispatched entity fields are intentionally
+  // not renamable — the former because idempotency depends on it, the
+  // latter because tagPrefixDispatch already names those fields directly.
+  const k = name => renameYamlKey(opts, name)
+
   const lines = ['---']
-  lines.push(`title: ${yamlScalar(item.title)}`)
-  if (item.creator) lines.push(`creator: ${yamlScalar(item.creator)}`)
-  if (item.publisher) lines.push(`publication: ${yamlScalar(item.publisher)}`)
-  if (item.date) lines.push(`date: ${yamlScalar(item.date)}`)
-  if (item.type) lines.push(`doc_type: ${yamlScalar(item.type)}`)
+  lines.push(`${k('title')}: ${yamlScalar(item.title)}`)
+  if (item.creator) lines.push(`${k('creator')}: ${yamlScalar(item.creator)}`)
+  if (item.publisher) lines.push(`${k('publication')}: ${yamlScalar(item.publisher)}`)
+  if (item.date) lines.push(`${k('date')}: ${yamlScalar(item.date)}`)
+  if (item.type) lines.push(`${k('doc_type')}: ${yamlScalar(item.type)}`)
 
   // Source: either composed into one string, or emitted as separate fields.
   if (opts.composeSource) {
     const source = composeSource(item)
-    if (source) lines.push(`source: ${yamlScalar(source)}`)
+    if (source) lines.push(`${k('source')}: ${yamlScalar(source)}`)
   } else {
     for (const part of SOURCE_PARTS) {
-      if (item[part]) lines.push(`${part}: ${yamlScalar(item[part])}`)
+      if (item[part]) lines.push(`${k(part)}: ${yamlScalar(item[part])}`)
     }
   }
 
   // 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.
   // URI-shaped keys are preferentially resolved through Tropy's ontology
-  // for human-readable labels; falls back to the URI's local name.
+  // for human-readable labels; falls back to the URI's local name. The
+  // fieldRename map applies on top so users can rename whatever they like.
   const handled = new Set([
     ...STRUCTURAL_KEYS,
     ...RENDERED_EXPLICITLY,
@@ -343,7 +382,7 @@ function buildFrontmatter(item, hash, opts) {
     if (looksLikeUri(key)) {
       yamlKey = ontologyLabel(opts.ontology, key) || localName(key)
     }
-    emitYamlValue(lines, yamlKey, item[key])
+    emitYamlValue(lines, k(yamlKey), item[key])
   }
 
   // Dispatched entity fields, in declaration order.
@@ -362,18 +401,18 @@ function buildFrontmatter(item, hash, opts) {
 
   // Leftover (unmatched) tags as a flat list.
   if (leftover.length === 0) {
-    lines.push('tags: []')
+    lines.push(`${k('tags')}: []`)
   } else {
-    lines.push('tags:')
+    lines.push(`${k('tags')}:`)
     for (const tag of leftover) lines.push(`  - ${yamlScalar(tag)}`)
   }
 
   if (opts.includePhotoPaths) {
     const paths = extractPhotoPaths(item)
     if (paths.length === 0) {
-      lines.push('photos: []')
+      lines.push(`${k('photos')}: []`)
     } else {
-      lines.push('photos:')
+      lines.push(`${k('photos')}:`)
       for (const p of paths) lines.push(`  - ${yamlScalar(p)}`)
     }
   }
@@ -526,6 +565,7 @@ class MarkdownPlugin {
       composeSource: this.options.composeSource !== false,
       filenamePattern: this.options.filenamePattern || 'tropy-{hash}-{slug}',
       embedPhotos: this.options.embedPhotos === true,
+      fieldRename: parseFieldRename(this.options.fieldRename),
       ontology
     }
   }
@@ -603,7 +643,8 @@ MarkdownPlugin.defaults = {
   wikiLinkEntities: false,
   composeSource: true,
   filenamePattern: 'tropy-{hash}-{slug}',
-  embedPhotos: false
+  embedPhotos: false,
+  fieldRename: ''
 }
 
 module.exports = MarkdownPlugin
@@ -612,6 +653,8 @@ module.exports = MarkdownPlugin
 module.exports._internals = {
   parseCsvSet,
   parseDispatch,
+  parseFieldRename,
+  renameYamlKey,
   dispatchTags,
   slugify,
   shortHash,

package.json

@@ -1,7 +1,7 @@
 {
   "name": "tropymd",
   "productName": "Tropy.md",
-  "version": "0.4.1",
+  "version": "1.0.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",
@@ -87,6 +87,13 @@
       "label": "Embed photos in the body",
       "default": false,
       "hint": "When enabled, each page's notes are preceded by an `![](photo path)` line that embeds the scan image. Useful for editors that render image links inline. Single-photo items skip the page marker; multi-photo items get both the marker and the embed."
+    },
+    {
+      "field": "fieldRename",
+      "type": "string",
+      "label": "Field rename (frontmatter keys)",
+      "default": "",
+      "hint": "Comma-separated `from=to` rules that rename top-level YAML field names. Useful for matching downstream conventions — e.g. correspondence items use `dc:audience` for the recipient, which the plugin emits as `audience:` by default; configure `audience=recipient` to land it in your conventional `recipient:` field. Apply equally to the standard fields (creator, publication, date, doc_type, source, archive, collection, box, folder, tags, photos) and any custom template properties that pass through. Tag-dispatched entity fields are unaffected — use the Tag prefix dispatch setting to name those."
     }
   ]
 }