Multi Vault Support

Goals

Users should be able to create multiple vaults for a given workspace. Each vault is a folder that can contain any number of hierarchies.

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

From Workspace

Go to text →

From Workspace

Go to text →

A workspace is a collection of one or more vaults. This is a folder that contains all the files necessary to manage your information in Dendron.

From Vaults

Go to text →

From Vault

Go to text →

A vault is a collection of notes, files, and configuration files.

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.

From Concepts

Go to text →

Hierarchies

From FAQ

Go to text →

Users of other note-taking tools often balk at Dendron's focus on hierarchies. The common counterpoint is that the real world is not constrained by hierarchy and that this approach isn’t flexible enough for what they want to do. These users argue for graphs and backlinks as a better primary model for managing knowledge.

A graph is indeed more flexible. If we were building a digital brain for computers to perfectly model the world, we would probably go with this approach. But we are not building a tool for computers to capture every facet of the world; we are building a tool to help humans make sense of it. The challenge we face as humans is information overload. There is too much of it and we need ways of constraining that complexity. Filtering large amounts of information into exponentially smaller subsets is what hierarchies are built for (and why they are used as the core primitive in every database ever created).

With a hierarchy, you have one source of truth where a note can be filed and a filtering process to help you find the right place to file. Note that this doesn't limit you to creating secondary associations using backlinks, tags, and keywords.

The traditional failings of past hierarchies were that they were too rigid. Most people’s experience with hierarchies are folder hierarchies that ossify from the moment that they are created. These hierarchies are hard to change and so people don’t change them, even as their underlying understanding of the domain changes. It is because of this friction that most new tools focus on note creation without any predefined structure. This approach makes creating notes easy but finding notes hard.

Dendron has flexible hierarchies. They provide a structure for your notes but these structures can be easily changed. In programming, developers can refactor code and change its structure — the IDE will make sure that all references pointing to the original code are updated. In Dendron, you can refactor notes and hierarchies and Dendron will make sure that your PKM is consistent throughout. This means that you have the best of both worlds: a basic structure for the organization but the flexibility to change it.

From Hierarchies

Go to text →

Dendron organizes your notes into hierarchies. These are . ("dot" or "period") delimited Markdown files.

Example

Below is a hypothetical hierarchy for a file tree:

.
└── project1/
    ├── designs/
    │   └── promotion.png
    ├── paperwork/
    │   └── legal.md
    └── tasks/
        ├── task1.md
        └── 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.

From Concepts

Go to text →

Domain

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

Specs

a workspace can have one or more vaults
a workspace can have one or more workspace configs
vaults have a path relative to the workspace and an optional name

Flow

Initialization

To facilitate separation and re-usability of vaults, we are changing how the initial workspace is laid out in Dendron.

Today, all files (configuration, vaults, docs) are located directly inside the workspace root.

From Multi Vault Support

Go to text →

.
└── Dendron
    ├── .git
    ├── dendron.code-workspace
    ├── dendron.yml
    ├── docs 
    ├── pods
    ├── vault1
    │   ├── foo.md
    │   └── foo.two.md
    └── vault2
        ├── foo.md
        └── foo.one.md

With multivault, workspace configuration will be moved underneath a separate folder underneath the configuration root. By default, this will inside a folder named config.

From Multi Vault Support

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

Inside a multi-vault workspace, each vault and config will be initialized as separate and independent git repositories. To initialize a multi-vault workspace, you can run Dendorn: Initialize MultiVault Workspace to bootstrap the folder layout that you see above.

We will also be releasing a migration script that can convert a single vault workspace into a multi-vault workspace.

Configuration

The dendron.yml file will be modified to have additional metadata for vaults that have remote repositories associated with them. A remote root is not required unless you plan on cloning your workspace to other computers.

vaults:
  - fsPath: vault1
    remote:
      type: git
      url: /path/to/vault1/repo
  - fsPath: vault2
    remote:
      type: git
      url: /path/to/vault2/repo
      branch: nightly # optional, target specific branch

Cloning

Cloning is the act of checking out a workspace on another machine. To clone, Dendron will have the Dendron: Clone Workspace command. It will take the url of a remote workspace configuration repo as input as well as a local path for the workspace root. Cloning will checkout the workspace configuration underneath the workspace root and also checkout all the vaults that are associated with the configuration underneath the workspace.

Add a new Vault

run Dendron: Add Vault
- specify file path relative to the current workspace root
- specify an optional user friendly name for the vault
  - if no name is set, the last component of the file path will be used
when the user hits enter, the vault is created as an "empty vault"
- empty vaults will contain a root.md and root.schema.yml file

Lookup

From Multi Vault Support

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

lookup: {empty query}
- show all top level results of all vaults. note how the vault name shows up in parenthesis next to the result
- results
```
root (vault1)
root (vault2)
foo (vault1)
foo (vault2)
```
lookup: vault1/
- by prefixing lookup with the vault name, you can narrow results to a particular vault
- results
```
root (vault1)
foo (vault1)
```
lookup: foo.
- Dendron will merge all results from all vaults when you do a lookup
- results
```
foo.one (vault2)
foo.two (vault1)
```
lookup: foo.new
- when you lookup a note that doesn't exist, you'll have the option of creating the note in either vault
- results
```
Create New (vault2)
Create New (vault1)
```

Navigating Links

From Multi Vault Support

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
- the UI should be similar to the Peek Action
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

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.

Publishing Notes

From Multi Vault Support

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

configuration to publish everything under foo

config

vaults:
- name: main
    path: vault1
- name: private
    path: vault2
publish:
    siteHierarchies: [foo]

published notes:

vault1/foo.md
vault1/two.md
vault2/foo.md
vault2/one.md

configuration that denies publication from vault2

config

vaults:
- name: main
    path: vault1
- name: private
    path: vault2
    allowPublish: false
publish:
    siteHierarchies: [foo]

published notes:
```
vault1/foo.md
vault1/two.md
```

Special Cases

Adding a vault under another vault

you want to put all notes from vault2 under vault1 under the vault2 node
eg: lookup should see the following hierarchy

├── foo.md
├── foo.two.md
├── vault2.foo.md
└── vault2.foo.one.md

This can be achieved with the following config

vaults:
- name: main
    path: vault1
- name: private
    path: vault2
    mountUnder: vault2

Reference

File Layout for Legacy Workspace

.
└── Dendron
    ├── .git
    ├── dendron.code-workspace
    ├── dendron.yml
    ├── docs 
    ├── pods
    ├── vault1
    │   ├── foo.md
    │   └── foo.two.md
    └── vault2
        ├── foo.md
        └── foo.one.md

File Layout for Multi-Vault Workspace

.
└── Dendron
    |── .git
    |── dendron.code-workspace
    |── dendron.yml
    |── pods
    |── docs
    ├── vault1
    │   |── .git
    │   ├── foo.md
    │   └── foo.two.md
    └── vault2
        |── .git
        ├── foo.md
        └── foo.one.md

Configuration

vaults

top level directive in dendron.yml
collection of one or more vaults

{vault}.name

name of vault

{vault}.path

path to vault

{vault}.mountUnder

NOTE: this is not implemented yet

optional
by default, all hierarchies are mounted at the root
you change this by adding a mountpoint which is equivalent of adding a prefix to all files within the vault

Additional Resources

Discussions

Children

Backlinks