Link Search Menu Expand Document

Multi Vault

Summary

Multi vault refers to managing multiple vaults within your workspace.

Use Cases

  • for sensitive notes, multi-vault enables local only vaults vs vaults that can are 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

Concepts

Workspace

From dendron.ref.workspace
Go to text →

In Dendron, your workspace is the root of where all your files are located. It's set when you first run Dendron: Initialize Workspace. The folder that contains your workspace is also known as your workspace root.

A workspace has a dendron.yml file that specifies its vaults.

Commands

Workspace: Add and Commit

Add and commit all notes across all vaults to git.

Workspace: Sync

Synchronizes all notes across all vaults with git. Any changes you made will be pushed back to remote, and any changes in the remote will be pulled.

In more detail: Dendron will first commit all your changes, then pull changes from the remote, and finally push everything back to the remote. This workflow is good in most cases: private notes, internal shared vaults, or your personal writings. This workflow doesn't work as well in some cases however, so we offer per-vault configuration options which you can use to adjust how your notes are synchronized.

You can set these configuration options in your dendron.yml, either for each vault with the sync option, or for all workspace vaults with the workspaceVaultSync option. The configuration will look like this:

... rest of your dendron.yml
workspaceVaultSync: noPush
vaults:
    -
        fsPath: my-website
        sync: noCommit
        remote:
            type: git
            url: 'git@github.com:my-username/my-website.git'
    -
        fsPath: my-notes
        sync: sync
        type: git
            url: 'git@github.com:my-username/my-notes.git'

configuration options

sync

Dendron will try to synchronize everything: Dendron will first commit all your changes, then pull changes from the remote, and finally push everything back to the remote. This is the default for regular vaults.

noCommit

Pull and push updates if the workspace is clean, but don't commit. You manually commit your local changes, but automatically share them once you committed. This is good for vaults where you want to write a meaningful commit message and control what is being committed, for example a shared knowledge base or wiki. This is the default for Workspace Vaults.

noPush

Commit any changes and pull updates, but don't push. You can watch the repository and make local changes without sharing them back. This is good if you want to watch the updates in a vault and maybe even note your own thoughts in the vault without sharing them, for example an organization handbook that you don't want to edit yourself.

skip

Don't do any synchronization. This may be useful if you use some other tool to synchronize this vault.

Vaults

From dendron.ref.vaults
Go to text →

Your workspace is made up of vaults. A dendron vault stores a collection of related notes. If you're familiar with git, it's just like a code repo. By default, Dendron creates a vaults folder when you first initialize a workspace. All your notes are stored on a per vault basis.

.
└── workspace
    ├── vault.main
    │   ├── foo.md
    │   ├── foo.one.md
    │   └── foo.two.md
    └── vault.secret (hypothetical)
        ├── secret.one.md
        └── secret.two.md

By default, when you look for notes in Dendron, it will search over all vaults.

Hierarchies

From dendron.concepts
Go to text →

From dendron.topic.hierarchies
Go to text →

Within a vault, your notes are stored hierarchically as . delimited markdown files.

Below is a hypothetical hierarchy for a file tree:

.
└── project1/
    ├── project1/designs/
    │   └── project1/designs/promotion.png
    ├── project1/paperwork/
    │   └── project1/paperwork/legal.md
    └── project1/tasks/
        ├── project1/tasks/task1.md
        └── project1/tasks/task2.md

The same hierarchy in Dendron would look like the following:

.
├── project1.md
├── project1.designs.md
├── project1.designs.promotion.md
├── project1.paperwork.md
├── project1.paperwork.legal.md
├── project1.tasks.md
├── project1.tasks.task1.md
└── project1.tasks.task2.md

You can read more about hierarchies here

Domain

From dendron.concepts
Go to text →

A domain is the root of a hierarchy. In the example below, project1 would be the domain.

.
├── project1.md
├── project1.designs.md
├── project1.designs.promotion.md
├── project1.paperwork.md
├── project1.paperwork.legal.md
├── project1.tasks.md
├── project1.tasks.task1.md
└── project1.tasks.task2.md

Topics

Commands

Vault Add

From dendron.topic.commands
Go to text →

From dendron.ref.vaults
Go to text →
  • shortcuts: none

Add a new vault to your workspace.

When you add a vault, you can choose between adding a local vault or a remote vault.

Vault Remove

From dendron.topic.commands
Go to text →

From dendron.ref.vaults
Go to text →
  • shortcuts: none

Remove a vault

Remove a vault from your workspace. Note that the underlying files will not be deleted - the vault will lose its association with your workspace.

Lookup

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

When creating a note in lookup, the currently opened note's vault is used as the vault for the new note.

Specify Vault Location when Creating a Note

From dendron.topic.config.dendron
Go to text →

lookupConfirmVaultOnCreate

With this set, you can pick the vault for new notes.

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

  1. Dendron: Configure (yaml)

  2. add lookupConfirmVaultOnCreate: true so your configuration looks like the following:
version: 0
...
lookupConfirmVaultOnCreate: true
  • Sample workspace

From dendron.roadmap.project.n.2020.multi-vault
Go to text → 
.
└── Dendron
    |── .git
    |── dendron.code-workspace
    |── dendron.yml
    |── pods
    |── docs
    ├── vault1
    │   |── .git
    │   ├── foo.md
    │   └── foo.two.md
    └── vault2
        |── .git
        ├── foo.md
        └── foo.one.md

  • navigating to [[foo]] will result in a display prompting the user to select the vault to navigate to
  • navigating to [[foo.two]] will directly navigate to the note since it is unique across all vaults
  • navigating to [[vault1/foo]] will open foo in vault1
  • navigating to [[dendron://vault2/foo]] will open foo in vault1

Note References

Note references are vault specific 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 from a multi-vault enabled workspace if you are using dendron-11ty to publish.

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

Preset Remote Vaults

When you add a remote vault, you can either add a vault using a custom git url or select from one of the pre-defined endpoints. Currently, Dendron provide the following remote 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 your workspace and each vault separately as distinct repos.

If you use Vault: Add with a remote vault, Dendron will automatically add the remote properties to your dendron.yml file. See example below.

From dendron.ref.vaults
Go to text → 
vaults:
    -
        fsPath: handbook-vault
        workspace: handbook-workspace
        name: handbook
workspaces:
    handbook:
        remote:
            type: git
            url: 'git@github.com:dendronhq/handbook.git'

This will have the following file layout

.
└── workspace
    └── handbook-workspace
        └── handbook-vault

Versioned controlled vaults will be auto-initialized when someone pulls in the workspace.

If you want to convert a local vault to a remote vault, you can follow the instructions here.

File Layout for Multi-Vault Workspace

.
└── Dendron
    ├── .git
    ├── dendron.code-workspace
    ├── dendron.yml
    ├── ...
    ├── vault1
    │   ├── .git
    │   ├── root.md
    │   └── ...
    └── vault2
        ├── .git
        ├── root.md
        └── ...

Examples

  • Sample Multi-Vault workspace