Concepts
Below are some concepts that are helpful to know when using Dendron. Note that features with π§ are still under active development and might not be fully implemented.
Markdown
Frontmatter
Frontmatter is a convenient way of adding extra information to your documents like a shorthand title or longer description (think any extra information you can use to describe a note). This type of information is generally called metadata and the structure used is called YAML. You can add it to the front of your Markdown file and it won't show up in the preview. It was first introduced by Jekyll.
You can read more about the frontmatter used in Dendron here
Workspace
A Dendron workspace is a collection of one or more vaults (folders with notes).
Details
Every workspace has a dendron.yml which specifies all vaults and configurations for a particular workspace.
Most workspaces only have a single vault. See Multi Vault for scenarios of adding additional vaults.
Concepts
Workspace Root
The folder that contains files like dendron.yml
and dendron.code-workspace
is the top-level directory of a workspace, known as the workspace root.
Code Workspace
A workspace that is created using dendron.code-workspace
file.
Native Workspace
A workspace that is created with a dendron.yml
file and lacking a dendron.code-workspace
file.
Bare Workspace
A bare workspace is a workspace where all vaults inside are remote vaults (separate git repos). You can have a bare code workspace or a bare native workspace.
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.
Dendron can automatically detect merge conflicts and rebases, stash and restore your local changes when pulling if needed, and warn you about misconfigured remotes. Make sure to look at the message Dendron shows you after the sync is completed to see if there were any errors.
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
remote:
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.
Gotchas
Workspace Types
Dendron recognizes 2 types of workspaces, Code and Native. When you initialize your workspace with
the Initialize Workspace command, you get a Code
workspace. Code workspaces include a dendron.code-workspace
file which sets up vaults and
recommends installing some useful extensions. Code workspaces are great when you are setting up a
knowledge base.
Native workspaces on the other hand don't have a dendron.code-workspace
file.
They are useful when you are writing notes or documentation, and you want to
keep your notes as part of a project rather than a separate knowledge base.
See Native Workspace Setup to see how you can start using a native workspace!
Cookbook
Version control your workspace using Git
Inside your workspace, run the following
- Initialize a git repo
git init git add . git commit -m "initial commit"
- Add a remote
- go to GitHub, and create a new workspace
- follow instructions to add an existing git repo to the repository
Syncing your workspace with Git
Workspace Sync
does not sync the workspace if all your vaults are separate git repos. In order to synchronize your workspace, you need to explicitly do a git pull
from the workspace folder.
If you are inside VS Code, you should be able to run > Create Integrated Terminal...
, choose the folder containing your workspace, and launch the terminal. After launching, run a git pull
inside of it.
Vaults
Your workspace is made up of one or more 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
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βre not building a tool for computers to capture every facet of the world, weβre 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.
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.
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
Templates
Templates are notes whose content can be copied to other notes.
Templates can either be applied into an open note with the Apply Template, or automatically applied at note creation with Schemas.
Schema
Schema help you apply consistent structure to all your notes.
As you end up creating more notes, it can be hard to manage them at scale. Think of schemas as an optional type system for your notes that describe the hierarchy of your data and are represented as a hierarchy, themselves.
One of the primary capabilities for schema is to automatically insert templates into new notes.
You can create a schema by adding a YAML file with the following naming scheme {name}.schema.yml
to your workspace.
Below is an example of a three-level hierarchy describing cli commands. You don't need to concern yourself with the details of the schema syntax just yet, just know that this schema will match the following glob patterns: cli.*
, cli.*.cmd
, cli.*.cmd.*
, cli.*.env
- id: cli
desc: command line interface reference
parent: root
namespace: true
children:
- cmd
- env
- id: env
desc: variables relevant for command
- id: cmd
desc: subcommands
namespace: true
Stubs
Stubs are notes that don't exist but that you might want to create. They will show up as suggestions in lookup results. There are two reasons why these suggested notes might show up:
- they are the uncreated parent of a note deeper in the hierarchy (eg.
foo.bar
might be a stub forfoo.bar.foobar
) - they are possible notes according to the schema
The
+
sign next to the suggestion indicates that the note is a stub and does not exist
Pods
Pods are the mechanisms Dendron uses to import and export notes. Dendron has a different pod depending on where you are getting and publishing your data to.
Command Palette
The command palette is native to VS Code
. You can use it to run Dendron commands, which will all be prefixed with Dendron:
. You can use the following shortcut to open the command palette.
The command palette lets you access all command based functionality inside VS Code.
Lookup Bar
The lookup bar is how you interact with notes inside of Dendron. Use it to create, find, and delete notes. You can type > Dendron: Lookup
in the Command Palette
or use the Ctrl+L
shortcut.
Misc
Glob Pattern
Glob patterns are a way of pattern matching characters. You can test and see more example of glob patterns here.
Kebab Case
We recommend using all lower kebab case when naming your files. For example, awesome apples
would be awesome-apples
. This would be stored in your file system as awesome-apples.md
.
Dendron will auto-generate a human friendly title based on the last part of your hierarchy. By default, Dendron uses title.sh to generate titles based on your note name. Titles generated are consistent with the Chicago Manual of Style. Dendron will replace -
with a β
(space) when generating titles.
If you end up adding custom capitalization to your file name, Dendron will not attempt to generate a title but return the last part of your hierarchy as is.
Some examples below:
- awesome-apples.md -> title: Awesome Apples
- fruit.awesome-apples.md -> title: Awesome Apples
- fruit.Custom-Capitalization -> title: Custom-Capitalization
Early Seed Release
Early builds of Dendron. Only available to Environmentalist.
Slug
Human readable part of url. See Wikipedia article for more details.
Dendron uses github-slugger to generate slugs.
Pretty Ref
A pretty ref is a note ref rendered with an outline.
You can see an example below
A regular note ref is embedded inline in the text.
Children
Backlinks