About files and workspaces

Workspace

Obsidian lets you configure what content is visible at any given time. Hide the file explorer when not needed, display multiple documents side by side, or show an outline of your document while working on it. The configuration of visible content within your application window is known as the workspace.

The workspace is implemented as a tree data structure, where each node in the tree is called a workspace item. There are two types of workspace items: parents and leaves. The main difference is that parent items can contain child items, including other parent items, whereas leaf items cannot contain any workspace items.

There are two types of parent items, splits and tabs, which determine how the children are displayed to the user:

• A split item arranges its child items sequentially along a vertical or horizontal direction.
• A tabs item displays only one child item at a time and hides the others.

The workspace has three special split items: left, right, and root. The following diagram shows an example of a typical workspace layout:

A leaf is a window that can display content in different ways. The type of leaf determines how content is displayed and corresponds to a specific view. For example, a leaf of type graph displays the graph view.

Splits

By default, the root split direction is set to vertical. When you add a new leaf, Obsidian creates a new column in the user interface. When you split a leaf, the resulting leaves are added to a new split item. While there is no defined limit to the levels under the root split, each additional level has diminishing utility.

The left and right splits work slightly differently. When you split a leaf in the side docks, Obsidian creates a new tabs item and adds the new leaf under it. This limits them to a maximum of three levels of workspace items, with any direct children being tabs items.

Lifecycle in Workspace

Plugins can add leaves of any type to the workspace and define new leaf types via custom views. For more options, refer to the Workspace's API.

Unless explicitly removed, any leaves a plugin adds remain even if the plugin is disabled. Plugins are responsible for removing any leaves they add to the workspace.

To remove a leaf from the workspace, call detach() on the desired leaf. You can also remove all leaves of a certain type by using detachLeavesOfType().

Leaf Groups

You can create linked panes by assigning multiple leaves to the same group with setGroup().

leaves.forEach((leaf) => leaf.setGroup('group1'));

Files

Obsidian stores notes as Markdown-formatted plain text files within a vault. A vault is a folder on your local file system, including any subfolders.

Because notes are plain text files, you can use other text editors and file managers to edit and manage them. Obsidian automatically refreshes your vault to reflect any external changes.

You can open multiple folders as individual vaults, for instance, to separate work and personal notes.

Warning

Vaults within vaults: Since Internal links are local to a vault, creating vaults within vaults is discouraged, as links may not update correctly.

Editor Extensions

Editor extensions allow customization of the note-editing experience in Obsidian. Obsidian uses CodeMirror 6 (CM6) as the Markdown editor. Just like Obsidian, CM6 has plugins, called extensions. Thus, an Obsidian editor extension is a CodeMirror 6 extension.

The API for building editor extensions is unconventional and requires a basic understanding of CM6's architecture. This section provides enough context and examples to help you get started. For more detailed information, refer to the CodeMirror 6 documentation.

While CM6 supports several types of extensions, two common ones are View plugins and State fields.

Cache

To enhance performance, Obsidian maintains a local record of file metadata in your vault, known as the metadata cache. This metadata powers various features in the app, from the Graph view to the Outline view.

Obsidian keeps this cache synchronized with vault files, but it can become out of sync with the underlying files. If this occurs, you can rebuild your metadata cache in the app settings under Files and links.

Files in Practice

As mentioned under the workspace section, Obsidian operates on a "leaf principle," where every file acts as a leaf. In this context, the workspace resembles a tree structure, with each file as part of this system (considering the file system, workspace, and vault as synonymous in this context):

• create()

Triggered when a file is created. This is also called when the vault is first loaded for each existing file.

Warning

The create event is also called when the vault loads. To avoid create events on vault load, register your event handler within Workspace.onLayoutReady().

• delete()

Called when a file is deleted.

• rename()

Called when a file is renamed.

• modify()

Called when a file is modified.