Skip to main content

Vault

From the official documentation on Working with multiple Vaults:

Each collection of notes in Obsidian is known as a Vault. A Vault consists of a folder, and any sub-folders within it.

While your plugin can access the file system like any other Node.js application, the Vault module aims to make it easier to work with files and folders within a Vault.

The following example recursively prints the paths of all Markdown files in a Vault:

const files = this.app.vault.getMarkdownFiles()

for (let i = 0; i < files.length; i++) {
console.log(files[i].path);
}
tip

If you want to list all files, and not just Markdown documents, use getFiles() instead.

Read files

There are two methods for reading the content of a file: read() and cachedRead().

  • If you only want to display the content to the user, then use cachedRead() to avoid reading the file from disk multiple times.
  • If you want to read the content, change it, and then write it back to disk, then use read() to avoid potentially overwriting the file with a stale copy.
info

The only difference between cachedRead() and read() is when the file was modified outside of Obsidian just before the plugin reads it. As soon as the file system notifies Obsidian that the file has changed from the outside, cachedRead() behaves exactly like read(). Similarly, if you save the file within Obsidian, the read cache is flushed as well.

The following example reads the content of all Markdown files in the Vault and returns the average document size:

main.ts
import { Notice, Plugin } from "obsidian";

export default class ExamplePlugin extends Plugin {
async onload() {
this.addRibbonIcon("info", "Calculate average file length", async () => {
const fileLength = await this.averageFileLength();
new Notice(`The average file length is ${fileLength} characters.`);
});
}

async averageFileLength(): Promise<number> {
const { vault } = this.app;

const fileContents: string[] = await Promise.all(
vault.getMarkdownFiles().map((file) => vault.cachedRead(file))
);

let totalLength = 0;
fileContents.forEach((content) => {
totalLength += content.length;
});

return totalLength / fileContents.length;
}
}

Delete files

There are two methods to delete a file, delete(), and trash(). Which one you should use depends on if you want to allow the user to change their mind.

  • delete() removes the file without a trace.
  • trash() moves the file to the trash bin.

When you use trash(), you have the option to move the file to the system's trash bin, or to a local .trash folder at the root of the user's Vault.

Is it a file or folder?

Some operations return or accept a TAbstractFile object, which can be either a file or a folder. Always check the concrete type of a TAbstractFile before you use it.

const folderOrFile = this.app.vault.getAbstractFileByPath("folderOrFile");

if (folderOrFile instanceof TFile) {
console.log("It's a file!");
} else if (folderOrFile instanceof TFolder) {
console.log("It's a folder!");
}