v1.2.0: {name} filename placeholder + collision numbering

Adds a `{name}` placeholder to the filename pattern that produces a
human-readable filename component: case and spaces preserved, only
filesystem-illegal characters (< > : " / \ | ? *) and control chars are
stripped, plus a few characters that confuse Obsidian's wiki-link parser
(# ^ [ ]). Suitable for vaults that want titled files like
"The Sagebrush Rebellion.md" rather than slug-style names.

When two items would produce the same filename — for example two
articles titled "The Sagebrush Rebellion" from different sources, both
rendered with `{name}` — the second and later get OS-style suffixes:
"The Sagebrush Rebellion (2).md", "The Sagebrush Rebellion (3).md", etc.
The check is case-insensitive (matches typical Windows/macOS filesystem
behavior) and looks at both files already on disk and filenames used
earlier in the same export batch.

Default filename pattern is unchanged. The new behavior is fully opt-in
by writing a pattern that uses {name}. Idempotency continues to work via
the frontmatter-embedded tropy_hash, so any pattern still re-runs safely.

Refactored applyFilenamePattern: filename variables are now pre-formatted
to their natural display form (slugified or sanitized as appropriate) and
the pattern substitution is a pure 1:1 replacement.

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

Author: hepplerj

README.md

@@ -99,8 +99,10 @@ Template for the output filenames (`.md` is appended automatically).
 Default: `tropy-{hash}-{slug}`. Available placeholders:
 
 - `{hash}` — 8-character content hash (drives idempotency)
-- `{slug}` — short slugified title (≤60 chars)
+- `{slug}` — short slugified title, lowercase + hyphens (≤60 chars)
 - `{title}` — full slugified title (no length cap)
+- `{name}` — human-readable title: case and spaces preserved, only
+  filesystem-illegal characters (`< > : " / \ | ? *`) stripped
 - `{date}` — the item's date as it appears in Tropy
 - `{type}` — the doc type (e.g. `letter`, `newspaper`)
 - `{creator}` — slugified creator name
@@ -109,11 +111,19 @@ Missing values collapse cleanly so a missing `{date}` doesn't leave a stray
 hyphen. Idempotency reads the `tropy_hash:` value from existing files'
 frontmatter, so any pattern works without breaking new exports.
 
+When two items would produce the same filename — for example two
+articles titled "The Sagebrush Rebellion" from different newspapers,
+both rendered with `{name}` — the second and later get an OS-style
+suffix: `The Sagebrush Rebellion (2).md`, `The Sagebrush Rebellion (3).md`,
+and so on.
+
 Examples:
 
 | Pattern | Result |
 |---|---|
 | `tropy-{hash}-{slug}` (default) | `tropy-a1b2c3d4-letter-from-pinchot.md` |
+| `{name}` | `Letter from Pinchot to Roosevelt.md` |
+| `{date} {name}` | `1907-10-15 Letter from Pinchot to Roosevelt.md` |
 | `{date}-{slug}` | `1907-10-15-letter-from-pinchot.md` |
 | `{type}/{slug}` | `letter/letter-from-pinchot.md` |
 

index.js

@@ -1,6 +1,6 @@
 'use strict'
 
-// Tropy.md — v1.1.1
+// Tropy.md — v1.2.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
@@ -156,6 +156,27 @@ function slugify(s, maxLen = 60) {
     .replace(/^-+|-+$/g, '')
 }
 
+function sanitizeFilename(s, maxLen = 150) {
+  // Produces a filesystem-safe but human-readable filename component:
+  // case and spaces preserved, only the characters that confuse Windows,
+  // macOS, or Obsidian's wiki-link parser are stripped. Suitable for
+  // titles like "The Sagebrush Rebellion" — the result reads naturally
+  // in a vault while still being a valid filename on every common OS.
+  return String(s || '')
+    // Filesystem-illegal everywhere: < > : " / \ | ? * and control chars.
+    .replace(/[<>:"/\\|?*\x00-\x1f]/g, '')
+    // Stripped to keep Obsidian's wiki-link parser happy: # ^ [ ].
+    .replace(/[#^[\]]/g, '')
+    // Collapse runs of whitespace.
+    .replace(/\s+/g, ' ')
+    .trim()
+    // Trim trailing dots — Windows treats "name." and "name" as the same.
+    .replace(/\.+$/, '')
+    .trim()
+    .slice(0, maxLen)
+    .trim()
+}
+
 function shortHash(item) {
   // Hash a content fingerprint built from the whole item, not just the first
   // photo's checksum. Tropy can ship `checksum: "d41d8cd9..."` (md5 of empty
@@ -182,28 +203,36 @@ function shortHash(item) {
 }
 
 function applyFilenamePattern(pattern, vars) {
-  // Substitutes {key} placeholders. Missing/empty values render as empty,
-  // and the result is then cleaned of double-hyphens / leading-trailing
-  // hyphens so a missing piece doesn't leave a stray separator.
+  // Substitutes {key} placeholders with values from `vars`. Values are
+  // expected to be pre-formatted (slugified or sanitized as appropriate
+  // for that variable). Missing/empty values render as empty; the result
+  // is then cleaned of double-hyphens and leading/trailing hyphens or
+  // whitespace so a missing piece doesn't leave a stray separator.
   let out = String(pattern || '').replace(/\{(\w+)\}/g, (_, k) => {
     const v = vars[k]
-    return v == null ? '' : slugify(v, 1000)
+    return v == null ? '' : String(v)
   })
   out = out
     .replace(/-{2,}/g, '-')
-    .replace(/^-+|-+$/g, '')
+    .replace(/^[-\s]+|[-\s]+$/g, '')
     .trim()
   return out
 }
 
 function filenameFor(item, hash, opts) {
+  // Variables come in two flavors: slug-style (lowercase + hyphens, safe
+  // for any filesystem and any URL) and human-readable (case + spaces
+  // preserved via sanitizeFilename). Pattern authors choose between them
+  // by picking the right placeholder name.
+  const title = item.title || ''
   const vars = {
     hash,
-    slug: slugify(item.title),
-    title: slugify(item.title, 1000),
-    date: item.date || '',
-    type: item.type || '',
-    creator: item.creator || ''
+    slug:    slugify(title),
+    title:   slugify(title, 1000),
+    name:    sanitizeFilename(title),
+    date:    item.date || '',
+    type:    item.type ? slugify(item.type, 1000) : '',
+    creator: slugify(item.creator || '', 1000)
   }
   const stem = applyFilenamePattern(opts.filenamePattern, vars)
     || `tropy-${hash}`  // fallback if pattern collapses to empty
@@ -545,6 +574,20 @@ class MarkdownPlugin {
     return dir || null
   }
 
+  async existingFilenames(outDir) {
+    // Returns a case-insensitive Set of filenames already in the output
+    // directory. Used to resolve filename collisions when two items would
+    // otherwise want the same name (e.g. two articles titled "The
+    // Sagebrush Rebellion" from different sources, both rendered with
+    // the human-readable {name} placeholder).
+    try {
+      const files = await fs.readdir(outDir)
+      return new Set(files.map(f => f.toLowerCase()))
+    } catch {
+      return new Set()
+    }
+  }
+
   async existingHashes(outDir) {
     // Reads the `tropy_hash:` value out of each existing .md file's
     // frontmatter. This is robust to any filename pattern the user has
@@ -636,6 +679,7 @@ class MarkdownPlugin {
 
     const opts = this.buildOpts()
     const seen = await this.existingHashes(outDir)
+    const usedNames = await this.existingFilenames(outDir)
     let wrote = 0
     let skipped = 0
     let failed = 0
@@ -658,7 +702,22 @@ class MarkdownPlugin {
           continue
         }
         const md = assembleMarkdown(item, hash, opts)
-        const target = path.join(outDir, filenameFor(item, hash, opts))
+        // Resolve filename collisions: if the computed filename already
+        // exists in the output directory (or has been used earlier in
+        // this batch), append `(2)`, `(3)`, etc. until unique. Matches
+        // the OS-level rename behavior users already recognize.
+        let candidate = filenameFor(item, hash, opts)
+        if (usedNames.has(candidate.toLowerCase())) {
+          const stem = candidate.replace(/\.md$/, '')
+          let n = 2
+          do {
+            candidate = `${stem} (${n}).md`
+            n++
+          } while (usedNames.has(candidate.toLowerCase()))
+        }
+        usedNames.add(candidate.toLowerCase())
+
+        const target = path.join(outDir, candidate)
         await fs.writeFile(target, md, 'utf8')
         seen.add(hash)
         wrote++
@@ -698,6 +757,7 @@ module.exports._internals = {
   renameYamlKey,
   dispatchTags,
   slugify,
+  sanitizeFilename,
   shortHash,
   filenameFor,
   applyFilenamePattern,

package.json

@@ -1,7 +1,7 @@
 {
   "name": "tropymd",
   "productName": "Tropy.md",
-  "version": "1.1.1",
+  "version": "1.2.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",
@@ -79,7 +79,7 @@
       "type": "string",
       "label": "Filename pattern",
       "default": "tropy-{hash}-{slug}",
-      "hint": "Template for output filenames (`.md` is appended). Placeholders: {hash} 8-char content hash, {slug} short title (≤60 chars), {title} full slugified title, {date}, {type}, {creator}. Missing values collapse cleanly. Idempotency reads the `tropy_hash:` value from frontmatter, so any pattern works without breaking re-runs."
+      "hint": "Template for output filenames (`.md` is appended). Placeholders: {hash} 8-char content hash, {slug} short slugified title (≤60 chars), {title} full slugified title, {name} human-readable title with case and spaces preserved (filesystem-illegal characters stripped), {date}, {type}, {creator}. Missing values collapse cleanly. When two items would produce the same filename, the second and later get `(2)`, `(3)`, etc. suffixes. Idempotency reads the `tropy_hash:` value from frontmatter, so any pattern works without breaking re-runs."
     },
     {
       "field": "embedPhotos",