Feature Request: Automatic filename sanitization on upload

Feature Request: Automatic filename sanitization on upload

Summary

When uploading images or files through Keystatic, filenames should be automatically sanitized to remove spaces, special characters, and other problematic characters that can cause issues with Git, URLs, and various file systems.

Problem

Currently, Keystatic accepts filenames as-is from the user's file system. This leads to several issues:

1. Broken builds/deploys: Filenames with spaces or special characters (e.g., Screenshot 2025-12-15 (1).jpg) can cause GraphQL errors when committing to GitHub:

   [GraphQL] A path was requested for deletion which does not exist as of commit oid `...`
   

2. URL encoding issues: Spaces become %20 in URLs, parentheses and other characters can break paths

3. Cross-platform problems: Different file systems handle special characters differently

4. Poor developer experience: Users have to manually rename files before every upload

Expected behavior

When a file is uploaded, Keystatic should automatically sanitize the filename:

Original filename	Sanitized filename
Screenshot 2025-12-15 (1).jpg	screenshot-2025-12-15-1.jpg
My Document.pdf	my-document.pdf
Über File — Recipe.png	uber-file-recipe.png

Suggested implementation

1. Convert to lowercase
2. Replace spaces with hyphens
3. Remove or transliterate special characters ((), [], &, etc.)
4. Remove or transliterate accented characters
5. Collapse multiple hyphens into one
6. Trim hyphens from start/end

Optionally, this could be:

• A configurable option in keystatic.config.ts
• Enabled by default with an option to disable

Environment

• Keystatic Cloud
• Astro + Netlify
• GitHub storage mode

Additional context

This is standard behavior in most CMS platforms (WordPress, Drupal, Sanity, etc.) and would significantly improve the user experience, especially for non-technical content editors who don't think about filename conventions.

The Keystatic upload tool documentation already notes that filenames should "only contain alphanumeric characters, dashes and underscores" — it would be great if Keystatic enforced/fixed this automatically.

---

Happy to help test or contribute if needed!

# Feature Request: Automatic filename sanitization on upload

Summary

When uploading images or files through Keystatic, filenames should be automatically sanitized to remove spaces, special characters, and other problematic characters that can cause issues with Git, URLs, and various file systems.

Problem

Currently, Keystatic accepts filenames as-is from the user's file system. This leads to several issues:

1. Broken builds/deploys: Filenames with spaces or special characters (e.g., Screenshot 2025-12-15 (1).jpg) can cause GraphQL errors when committing to GitHub:

   [GraphQL] A path was requested for deletion which does not exist as of commit oid `...`
   

2. URL encoding issues: Spaces become %20 in URLs, parentheses and other characters can break paths

3. Cross-platform problems: Different file systems handle special characters differently

4. Poor developer experience: Users have to manually rename files before every upload

Expected behavior

When a file is uploaded, Keystatic should automatically sanitize the filename:

Original filename	Sanitized filename
Screenshot 2025-12-15 (1).jpg	screenshot-2025-12-15-1.jpg
My Document.pdf	my-document.pdf
Über File — Recipe.png	uber-file-recipe.png

Suggested implementation

1. Convert to lowercase
2. Replace spaces with hyphens
3. Remove or transliterate special characters ((), [], &, etc.)
4. Remove or transliterate accented characters
5. Collapse multiple hyphens into one
6. Trim hyphens from start/end

Optionally, this could be:

• A configurable option in keystatic.config.ts
• Enabled by default with an option to disable

Environment

• Keystatic Cloud
• Astro + Netlify
• GitHub storage mode

Additional context

This is standard behavior in most CMS platforms (WordPress, Drupal, Sanity, etc.) and would significantly improve the user experience, especially for non-technical content editors who don't think about filename conventions.

The [Keystatic upload tool documentation](https://github.com/JedWatson/keystatic-upload-tool) already notes that filenames should "only contain alphanumeric characters, dashes and underscores" — it would be great if Keystatic enforced/fixed this automatically.

---

Happy to help test or contribute if needed!

Start with the upload-tool documentation and the upload handling path, then review keystatic.config.ts to determine whether sanitization should be configurable. Compare the documented filename constraints with the examples in this issue and define behavior for extensions, transliteration, collisions, and disabling the feature. Done means uploads consistently produce the agreed safe filenames in GitHub storage mode.