Obsidian Stats logoObsidian Stats

Vault Reorganizer

by michellegdyason
5
4
3
2
1
Score: 50/100
Install Code

Description

Reviews

No reviews yet.

Stats

2
stars
796
downloads
0
forks
76
days
76
days
76
days
1
total PRs
0
open PRs
0
closed PRs
1
merged PRs
0
total issues
0
open issues
0
closed issues
7
commits

Latest Version

0.1.22
2 months ago

Changelog

Changelog

0.1.22

  • Renamed the settings tab heading to avoid the reserved word settings in Obsidian review checks.

0.1.21

  • Kept the deletion preference path compatible with the declared Obsidian minAppVersion by feature-detecting FileManager.trashFile() before falling back to adapter removal.
  • Renamed the settings tab heading so it does not repeat the plugin name.

0.1.20

  • Updated source to satisfy Obsidian review checks for settings headings, config-folder handling, network requests, confirmation modals, deletion preferences, active document/window usage, and deprecated browser APIs.
  • Replaced the deprecated builtin-modules build dependency with Node's node:module built-in module list.

0.1.19

  • PDF splitting now loads PDF.js only while converting an oversized handwritten PDF, instead of registering its worker at plugin startup.
  • This avoids interfering with Obsidian's built-in PDF viewer.

0.1.18

  • Handwriting apply now refuses to create non-Markdown output or files outside the configured handwritten notes folder.
  • The final apply confirmation now names the handwriting destination folder when creating Markdown notes.

0.1.17

  • Specifically listed oversized handwriting PDFs can now be rendered into temporary page images and converted into one combined Markdown note.
  • Added settings to enable oversized PDF splitting and limit the number of PDF pages per handwritten note.

0.1.16

  • Handwriting conversion now reports the actual file size when a file is too large for direct conversion.
  • Oversized PDFs now tell you to split, compress, or export smaller page images instead of only saying the file is over 20 MB.

0.1.15

  • Specific handwriting files now accept obsidian://open URLs and extract the target file path.

0.1.14

  • Treat explicitly listed handwriting files as handwritten note sources instead of running the handwriting detector first.
  • Improved the handwriting prompt for OneNote/iPad Pencil PDF exports.

0.1.13

  • Added a Specific handwriting files setting for targeted handwriting conversion.
  • Specific handwriting files can be pasted as vault paths, filenames, or wikilinks, one per line.
  • Specific files bypass the folder scan order and handwriting preview limit.
  • Raised the default handwriting folder scan limit from 10 to 50 files.

0.1.12

  • Added PDF support to the handwriting-to-Markdown preview.
  • Checks Images and Attachments by default for handwriting sources.
  • Allows comma-separated handwriting source folders.

0.1.11

  • Added an OpenAI-powered handwriting-to-Markdown preview.
  • Added settings for handwriting source folder, Markdown note destination, model, supported image formats, preview limit, and detail level.
  • Creates Markdown notes only after preview approval and links each created note back to its source image.
  • Skips images that are not detected as handwritten notes.

0.1.10

  • Made image subject naming tolerate per-image OpenAI request failures.
  • Retries each image naming request once before falling back to moving the image to Images with its current filename.
  • Keeps the image rename preview running when one image returns a browser-level Failed to fetch error.

0.1.9

  • Added configurable Videos and Sound destinations.
  • Routed video and audio extensions before the general attachments folder.
  • Added settings for video and sound extension lists.
  • Updated the recommended structure to the Nine folder vault strategy.

0.1.8

  • Added a configurable Images destination and route image files there before the general attachments folder.
  • Added an OpenAI-powered image rename preview for generic image filenames.
  • Added settings for the OpenAI API key, image naming model, supported naming formats, preview limit, and detail level.
  • Updated planner/report wording to cover file moves and image renames.

0.1.7

  • Added the Six folder vault strategy label with Bases support.
  • Added configurable destination folders for notes, attachments, templates, canvases, Bases, and other files.
  • Added cleanup reporting for hidden blockers in visible folders.
  • Excluded hidden dot paths and generated Vault Reorganizer reports from reorganization.
  • Added rename fallbacks for root-flattening moves that Obsidian refuses.
See all version on GitHub

README file from

Github

Vault Reorganizer

Vault Reorganizer is an Obsidian plugin for previewing and applying bulk vault cleanup plans. It is designed for vaults that have grown into hundreds of folders and need to be flattened into a smaller, easier-to-maintain structure.

Recommended structure

For a large vault, a practical target is usually nine folders:

  • Notes for Markdown notes
  • Images for image files
  • Videos for video files
  • Sound for audio files
  • Attachments for PDFs, Office files, archives, and other embedded assets
  • Templates for reusable Markdown templates
  • Canvases for Obsidian canvas files
  • Bases for Obsidian Bases .base files
  • Files for miscellaneous non-note files
  • Archive for material you do not want the plugin to move

If you prefer a very flat vault, use the Markdown in root strategy. It moves Markdown notes to the vault root, while attachments and other files still go into their configured folders.

What the plugin does

  • Generates a preview before moving anything
  • Moves files with Obsidian's file manager so links can be updated by Obsidian
  • Resolves filename conflicts by adding a numeric suffix
  • Avoids target names that collide with existing folder-note style folders
  • Retries Folder already exists rename failures with Obsidian's lower-level vault rename
  • Uses a copy/delete fallback for stubborn root moves that both Obsidian rename methods refuse
  • Moves image files into a configurable Images folder before the general attachments folder
  • Moves video files into a configurable Videos folder before the general attachments folder
  • Moves audio files into a configurable Sound folder before the general attachments folder
  • Can use OpenAI vision to preview subject-based filenames for generic image names such as IMG_1234.jpg, screenshots, pasted images, and hash-like names
  • Can use OpenAI vision to preview handwritten-note images as Markdown notes before creating them
  • Moves images to Images during the image rename preview even when a file already has a human-readable name
  • Moves Obsidian Bases .base files into a configurable Bases folder
  • Lets users rename the destination folders in settings
  • Can centralize attachments without moving notes
  • Can optionally remove empty folders after files are moved
  • Can remove empty folders as a standalone cleanup action after a previous run
  • Can optionally remove visible OS metadata files such as Thumbs.db and desktop.ini before checking whether folders are empty
  • Always ignores hidden dotfiles and dot-folders such as .obsidian, .trash, .git, .DS_Store, and .localized
  • Reports hidden dotfiles and dot-folders that are blocking cleanup in normal visible folders so users can review them manually
  • Combines Obsidian's indexed folder tree with direct filesystem scanning when finding empty folders
  • Excludes Vault Reorganizer Reports from reorganization so generated reports stay put
  • Reports folders that still contain files or subfolders after cleanup
  • Leaves non-empty folders in place during cleanup instead of failing the whole run
  • Can copy a run report or create a report note in the vault
  • Lets you exclude folders such as Archive

Strategies

Nine folder vault

Moves files into the configured destinations:

  • Markdown notes to Notes
  • Images to Images
  • Videos to Videos
  • Audio to Sound
  • Other attachments to Attachments
  • Templates to Templates
  • Canvas files to Canvases
  • Bases files to Bases
  • Other files to Files

Markdown in root

Moves Markdown notes to the vault root. Attachments, templates, canvases, and other files still go to their configured destinations.

Centralize attachments only

Moves attachment file types into Attachments and leaves notes where they are.

How to use

  1. Back up or sync your vault before running a bulk move.
  2. Install the plugin in your vault's .obsidian/plugins/vault-reorganizer folder.
  3. Enable the plugin in Obsidian.
  4. Open the command palette and run Vault Reorganizer: Open vault reorganization planner.
  5. Pick a strategy and click Generate preview.
  6. Review the planned moves.
  7. Click Apply previewed moves only when the preview looks right.
  8. If anything fails, use Create report note to save the exact file and folder paths that need attention.

To clean up folders after a previous run, open the planner and click Remove empty folders now, or run Vault Reorganizer: Remove empty folders from the command palette.

To rename generic image filenames, add your OpenAI API key in the plugin settings, then open the planner and click Generate image rename preview. The preview sends only the generic image files it needs to name to OpenAI, up to the configured limit, and shows the proposed filenames before anything is changed. PNG, JPEG, WebP, and non-animated GIF are enabled by default for AI naming. Other configured image types can still be moved to Images without AI naming.

To transform handwritten notes, add your OpenAI API key in the plugin settings, then click Generate handwriting Markdown preview. By default, the plugin checks supported images and PDFs in Images and Attachments, skips files that are not detected as handwritten notes, previews the Markdown output, and creates Markdown notes in Notes/Handwritten only after you apply the preview. To target particular files, put one vault path, filename, wikilink, or obsidian://open URL per line in Specific handwriting files; when that field is set, the plugin checks only those files, treats them as handwritten note sources, and skips the folder-scan detection gate. Very large specifically listed PDFs, including some OneNote exports, can be rendered into temporary page images and converted into one combined Markdown note when Split oversized handwriting PDFs is enabled. The split pages are not saved as separate vault files, and handwriting output is restricted to .md files in the handwritten notes destination.

Install from GitHub

BRAT

If you use the BRAT plugin, add this repository:

MichelleGDyason/vault-reorganizer

Manual release install

Download these files from a GitHub release and place them in .obsidian/plugins/vault-reorganizer:

  • main.js
  • manifest.json
  • styles.css

Installation from this folder

Run:

npm install
npm run build

Then copy these files into .obsidian/plugins/vault-reorganizer in the target vault:

  • main.js
  • manifest.json
  • styles.css

Release process

The GitHub release workflow builds the plugin and attaches the required Obsidian files to a release when a version tag is pushed:

git tag 0.1.22
git push origin 0.1.22

Notes

The plugin intentionally does not infer semantic categories like projects, areas, or topics. Folder names are often inconsistent in old vaults, so the safest first pass is file-type cleanup. The image rename tool is limited to visible image subjects for filenames. After that, use Obsidian links, tags, properties, search, and Dataview-style queries to build organization that does not depend on deep folder nesting.

Sponsors