The Vault class is the primary interface for working with files and folders in an Obsidian vault. It provides methods for creating, reading, modifying, and deleting files, as well as listening to file system events.
Properties
The data adapter that handles low-level file system operations.
Path to the config folder. This value is typically .obsidian but it could be different.
Methods
getName
Gets the name of the vault.
Returns: The vault name.
Since: 0.9.7
getFileByPath
getFileByPath(path: string): TFile | null
null if the file does not exist.
Vault absolute path to the file.
null.
Since: 1.5.7
getFolderByPath
getFolderByPath(path: string): TFolder | null
null if the folder does not exist.
Vault absolute path to the folder.
null.
Since: 1.5.7
getAbstractFileByPath
getAbstractFileByPath(path: string): TAbstractFile | null
instanceof TFile. To check if it is a folder, use instanceof TFolder.
Vault absolute path to the folder or file, with extension, case sensitive.
null.
Since: 0.11.11
getRoot
Get the root folder of the current vault.
Returns: The root folder.
Since: 0.9.7
create
create(path: string, data: string, options?: DataWriteOptions): Promise<TFile>
Vault absolute path for the new file, with extension.
Text content for the new file.
createBinary
createBinary(path: string, data: ArrayBuffer, options?: DataWriteOptions): Promise<TFile>
Vault absolute path for the new file, with extension.
Binary content for the new file.
createFolder
createFolder(path: string): Promise<TFolder>
Vault absolute path for the new folder.
read
read(file: TFile): Promise<string>
cachedRead() otherwise for better performance.
Returns: Promise resolving to the file contents.
Since: 0.9.7
cachedRead
cachedRead(file: TFile): Promise<string>
read().
Returns: Promise resolving to the file contents.
Since: 0.9.7
readBinary
readBinary(file: TFile): Promise<ArrayBuffer>
getResourcePath
getResourcePath(file: TFile): string
The file to get the resource path for.
delete
delete(file: TAbstractFile, force?: boolean): Promise<void>
The file or folder to be deleted.
Should attempt to delete folder even if it has hidden children.
trash
trash(file: TAbstractFile, system: boolean): Promise<void>
The file or folder to be deleted.
Set to false to use local trash by default.
rename
rename(file: TAbstractFile, newPath: string): Promise<void>
FileManager.renameFile() instead.
Vault absolute path to move file to.
modify
modify(file: TFile, data: string, options?: DataWriteOptions): Promise<void>
modifyBinary
modifyBinary(file: TFile, data: ArrayBuffer, options?: DataWriteOptions): Promise<void>
append
append(file: TFile, data: string, options?: DataWriteOptions): Promise<void>
appendBinary
appendBinary(file: TFile, data: ArrayBuffer, options?: DataWriteOptions): Promise<void>
process
process(file: TFile, fn: (data: string) => string, options?: DataWriteOptions): Promise<string>
The file to be read and modified.
fn
(data: string) => string
required
A callback function which returns the new content of the note synchronously.
await app.vault.process(file, (data) => {
return data.replace('Hello', 'World');
});
copy
copy<T extends TAbstractFile>(file: T, newPath: string): Promise<T>
The file or folder to copy.
Vault absolute path for the new copy.
getAllLoadedFiles
getAllLoadedFiles(): TAbstractFile[]
getAllFolders
getAllFolders(includeRoot?: boolean): TFolder[]
Should the root folder (/) be returned.
getMarkdownFiles
getMarkdownFiles(): TFile[]
getFiles
Get all files in the vault.
Returns: Array of all files.
Since: 0.9.7
recurseChildren
static recurseChildren(root: TFolder, cb: (file: TAbstractFile) => any): void
The folder to start from.
cb
(file: TAbstractFile) => any
required
Callback function called for each file/folder.
Events
The Vault class extends Events and emits the following events:
create
on(name: 'create', callback: (file: TAbstractFile) => any, ctx?: any): EventRef
Workspace.onLayoutReady.
Since: 0.9.7
modify
on(name: 'modify', callback: (file: TAbstractFile) => any, ctx?: any): EventRef
delete
on(name: 'delete', callback: (file: TAbstractFile) => any, ctx?: any): EventRef
rename
on(name: 'rename', callback: (file: TAbstractFile, oldPath: string) => any, ctx?: any): EventRef
Examples
Creating and reading a file
// Create a new file
const file = await this.app.vault.create('MyNote.md', '# Hello World');
// Read the file content
const content = await this.app.vault.read(file);
console.log(content); // "# Hello World"
Modifying a file
const file = this.app.vault.getFileByPath('MyNote.md');
if (file) {
await this.app.vault.modify(file, '# Updated Content');
}
Listening to file changes
this.registerEvent(
this.app.vault.on('modify', (file) => {
console.log(`File modified: ${file.path}`);
})
);
Processing a file atomically
const file = this.app.vault.getFileByPath('MyNote.md');
if (file) {
await this.app.vault.process(file, (content) => {
// Replace all instances of 'old' with 'new'
return content.replace(/old/g, 'new');
});
}
Getting all markdown files
const markdownFiles = this.app.vault.getMarkdownFiles();
console.log(`Found ${markdownFiles.length} markdown files`);
