Multi Vault Setup

Summary

A multi vault setup refers to a workspace with multiple to managing multiple vaults.

Use Cases

for sensitive notes, multi-vault enables local only vaults vs vaults that can be synced on file sharing services like Dropbox
for modularizing knowledge, multi-vault enables users to mix and match existing vaults depending on context
for federating and curating knowledge, multi-vault enables users to publish/subscribe to public vaults using protocols like git
for access control, multi-vault lets users configure specific vaults to be private which turns off publication and sharing of any notes inside said vault

Topics

Lookup

Lookup supports multiple vaults. When using lookup to find a note, each search result is labeled with which vault it belongs to.

Vault Location when Creating a Note

When creating a note in lookup, Dendron will try to create your note in the correct vault. By default, it will place the note into the same vault as the currently opened note. But if it detects that the new note matches an existing hierarchy in a different vault, you will get prompted to pick the destination vault:

Prompt for Vault Selection Each Time

From Configuration

Go to text →

lookupConfirmVaultOnCreate

This setting is scheduled for deprecation 📆

Use confirmVaultOnCreate instead.

With this set, you will be prompted to select the vault location each time you create a note when you have multiple vaults in your workspace.

To enable, add lookupConfirmVaultOnCreate: true in the Dendron configuration. Instructions to do so below.

Dendron: Configure (yaml)
add lookupConfirmVaultOnCreate: true so your configuration looks like the following:

version: 0
...
lookupConfirmVaultOnCreate: true

Moving Notes Between Vaults

This can be done with the Move Note command.

From Dendron: Move Note

Go to text →

Move a note to another vault and update all backlinks to that note.

Navigating Links

Using plain links like [[recipes.pasta]]:
- If there is only one note with that name across all vaults, Dendron will open that note
- If there are notes in multiple notes with that name across different vaults, Dendron will ask which one you wanted to open
Using cross-vault links like [[dendron://cooking/recipes.pasta]], it will always open recipes.pasta in the vault cooking even if there are notes with the same name in other vaults.

Note References

When you make a reference, Dendron will include the note from the same note. You can create a reference to a note in a different vault by using cross vault links.

Publishing

You can publish your notes from a multi-vault workspace just as you would from a single vault workspace.

We have added a new configuration, duplicateNoteBehavior, which controls how Dendron handles duplicate notes across multiple vaults.

Version Control

For multi-vault, there are several approaches to version control. If you are using Git, you can either commit everything as one repo or version control each vault separately as separate, distinct repos.

Separate Repositories

If you want to keep your vaults in separate repositories, then you'll want to use remote vaults. You can convert existing local vaults to remote vaults, or if you already have vaults in git repositories you can add them into your workspace as remote vaults.

From Vaults

Go to text →

A remote vault is what you get when you run the Add Existing Vault command and select a remote vault. This is a vault that is cloned from a git repo. It will be listed in a similar format as what you see below in your configuration file.

vaults:
  - fsPath: dendron
    remote:
      type: git
      url: "git@github.com:dendronhq/dendron.git"

When someone pulls down a workspace with a dendron.yml that contains a remote vault, Dendron will automatically initialize the vault at the given fsPath. If the vault is a Vaults, Dendron will pull down the workspace to {workspaceName}/fsPath.

If you put a vault in a git repository with a remote without using the Vault Convert command, then it will be missing the correct configuration. Dendron can fix the configuration for you with the fix remote vaults doctor action.

Single Repository

If you want to keep all your vaults in the same repository, then create a local vault using using Create New Vault command, and don't convert them to remote vaults.

Instead, open the .gitignore file at the root of your workspace and remove any lines that that reference vaults, for example <path-to-your-vault>/vaultName should be removed. Then you should be able to add and commit these vaults into the same repository.

⚠️ If you add multiple vaults into the same repository, you won't be able to use that vault as a remote vault in another workspace. You'll need to set up separate repositories if you need that.

File Layout for Multi-Vault Workspace

.
└── Dendron
    ├── .git
    ├── dendron.code-workspace
    ├── dendron.yml
    ├── notes
    │   ├── root.md
    │   └── ...
    └── dependencies
        ├── github.com
        │  └── dendronhq
        │     └── dendron-site
        │         ├── root.md
        │         └── ...
        └── gitlab.com
           └── username
              └── vault
                  ├── root.md
                  └── ...

Examples

Dendron uses a multi-vault setup with remote vaults to document the Dendron code. You can look at our public repository to see what our setup looks like. Because the vaults are remote, you won't see them in the folder itself: they get cloned automatically if you open the repository with Dendron.

This setup allows us to access the documentation when coding, while also allowing us to access these vaults in other workspaces and publish them independently.

Children

Backlinks