Config Overrides

[kevinslin]

46 Config Overrides

Goals

Enable local configuration overrides for vaults

Context

Dendron vaults are often shared in different environments and might be used by multiple people. Users of a vault depend on a common dendron.yml for all configuration which means that local customization isn't feasible

Proposal

Introduce local configuration overrides. On initialization, dendron will look for a .dendronrc.yml file in the following order:

• .dendronrc.yml file in the same directory as the vault
• .dendronrc.yml file in the user $HOME directory

The layout of these yml files will be exactly the same as dendron.yml and will be merged with existing options when a matching key is found

Example

The following shows a vault with a single vault with a local override that adds an additional local vault

Layout

• File structure

- seed
    - README.md
    - dendron.yml
    - .dendronrc.yml
    - notes/

• dendron.yml
  • NOTE: ... is used to denotte ommited configuration details that are not relevant to this example

...
workspace:
    vaults:
        -
            fsPath: .
            selfContained: true
            name: seed
preview:
    enableFMTitle: true
    ...

• .dendronrc.yml

workspace:
  vaults:
        -
            fsPath: .
            selfContained: true
            name: seed
        -
            fsPath: dependencies/localhost/sprout
            selfContained: true
            name: sprout
preview:
    enableFMTitle: false

Effect

When pulling down the vault seed, contributors only see the contents of the seed vault and also a preview with enableFMTitle: true behavior.
For this particular user, because they have a local override, they will see an additional vault, sprout when they load Dendron.

Design

Note that we could have made this interface more ergonomic by assuming vaults should be extended instead of replaced. Presumabliy, this would be the common case and would also support common usecases like adding global vaults that get added to all projects by putting these vaults in the $HOME/.dendronrc.yml directory.

The reason this RFC proposes not doing this is because of the following:

• introduces additional complexity into the override process (for this proposal, we simply use the lodash merge method
• introduces additional complexity into understanding how config overrides would work (if we extend vaults, do we also extend other array like settings like siteHierarchies?)
• makes it hard to support the usecase of removing vaults via a local override
• makes assumptions about underlying use case

If, after launching this feature, we find that extending vaults is what the overwhelming majority of users want, we can revisit this design decision and iterate upon it

Tradeoffs

• Adds more complexity in exchange for functionality
• Loading optional configuration overrides is a potential vector for security vulnerabilities (eg. attacker writes a custom configuration in the users $HOME directory that executes code). while dendron configuration doesn't posess this ability today, it might in the future through registration of hooks and other functionality. This is something to be mindful of when adding configuration options in the future

[SeriousBug]

RFC Consideration

• If both project-local and user-local overrides exist, should those both merge into the config? I can see points towards both, if we skip the user local override when there's a project local override then someone could use that to disable their global vaults. If we merge both, then they could apply their preferences globally (like being able to set whether the frontmatter wraps or not).

Development Considerations

• The override configs should have all fields optional, which means a new validator file for the yaml validation.
• With global vaults, we'll need to add our own non-VSCode file watchers since the vaults are not in the workspace. This caused bugs in the past when I added the native workspace watcher because if someone had lots of files, the native workspace watcher would sometimes crash or cause slowdowns. We should make sure to apply gitignore and vscode-ignore patterns when watching the files.
• Will global vaults be active in all workspaces, or only in Dendron workspaces? Being active in all workspaces would be useful, but it may lead to bugs in our code that expect the workspace folder to be open.

[kevinslin]

If both project-local and user-local overrides exist, should those both merge into the config? I can see points towards both, if we skip the user local override when there's a project local override then someone could use that to disable their global vaults. If we merge both, then they could apply their preferences globally (like being able to set whether the frontmatter wraps or not).

If both project-local and user-local overrides exist, should those both merge into the config?

for the case of simplicity, I would advocate for not merging. if this proves to be a common usecase, then we can add it in in a phase 2.

The override configs should have all fields optional, which means a new validator file for the yaml validation.

yep

With global vaults, we'll need to add our own non-VSCode file watchers since the vaults are not in the workspace. This caused bugs in the past when I added the native workspace watcher because if someone had lots of files, the native workspace watcher would sometimes crash or cause slowdowns. We should make sure to apply gitignore and vscode-ignore patterns when watching the files.

the latest version of vscode comes with filewatchers that can watch outside of the given workspace. might be time we look into using that instead

Will global vaults be active in all workspaces, or only in Dendron workspaces? Being active in all workspaces would be useful, but it may lead to bugs in our code that expect the workspace folder to be open.

good question. undecided. i'm thinking this should be an option to toggle in global vscode workspace settings

[SeriousBug]

Something else that came to mind is that we could suggest local overrides to the user at startup.

For example Dendron could ask if they prefer the frontmatter automatically folded, or whether they want the randomly colored tags or not. This would both introduce people to these features and config options, and to the fact that you can set local overrides.

[kevinslin]

I was thinking this as well. theres also features that differ by user (eg. some people want the preview to auto open whereas others don't use it at all)