DEV Community: Dendron Inc

Cache All the Things - A PKM workflow to incrementally retain (and find) everything

Kevin Lin — Thu, 29 Sep 2022 15:53:40 +0000

Context

An engineering manager that will remain unnamed told me his story of trying to find the solution to a technical problem on the internet.
It's the typical question -> google -> stack overflow -> answer pathway with a twist - when he finally found the answer, he realized that he himself had created the question a year prior.

I like this story because it's easy to relate to. Haven't we all searched for something that turned out to be a problem we've already encountered?

The process of searching for answers on the internet is what doing software (and much of knowledge work) is like in the 20th century.

There is an overwhelming amount of information we need to process just to do our job. It is impossible (nor useful) to keep this information in our heads so we rely on services like google to help look up what we don't know (or have forgotten).

While this can work, there is a problem when we come to depend on this workflow for getting through the day. It's like only relying on google maps to get home - while this works, you also lose the ability to navigate on your own in the process.

This is a groundhog day loop - regardless of how much you search, learnings are quickly forgotten and mastery is never built.

Now imagine the same workflow where instead of starting with a search, you look up information in your personal knowledge cache. This cache contains every problem you have ever encountered and is accessible in seconds. If you find the answer, you're done, and if not, you can be certain that it is not there. Only then do you fall back to search. When you find the answer, you add it to your cache so you can make use of it in the future.

This is a mastery loop - instead of losing your place on every question, you build and reinforce your understanding of things with each problem you encounter.

The key to building this particular mastery loop comes from combining the following PKM workflows:

a modified version of the progressive summarization method
A Hierarchy First Approach to Note Taking

Together, they let you cache all the things!

Progressive Summarization

If you're not familiar with the term, progressive summarization is the means of incrementally retaining insights from text to be used at a future date. It is built around five layers of summarization and pioneered by Tiago Forte, a big influencer in the PKM space.

The steps are described in more detail below:

If you come across useful information, save excerpts from it. This is layer 1. The benefit: next time you revisit the notes, you can just go over your excerpts instead the entire text.
If you happen to need the text again, bold specific passages that stand out as you're reviewing. This is layer 2 and serves to make future skimming easier.
If you require the text again, ==highlight from the bolded parts== insights that are especially poignant. This is layer 3 and it represents the highest quality insights that you've derived from the specific text.
If you still have need of the text, make a summary of it in your own words. This is layer 4 and represents the start of reframing the text in your own words.
If you then find the text relevant in some current project, the final step is to remix it into your own material. This is layer 5 and represents the culmination of all the prior layers.

There are some highly desirable characteristics of progressive summarization:

just in time vs ahead of time: you only do the work when you need to
incremental work: you only do minimal work at each layer which can then be leveraged in later layers
active vs passive: you actively read the text instead of skimming it

A Hierarchy First Approach to Knowledge Management

The Hierarchy First Approach to Knowledge Management excels at helping people organize lots of information in a consistent structured way for later retrieval.

It provides a foundation to create a knowledge base that can grow to any size while ensuring that information remains accessible. You can read more about the details of this workflow in the original blog post - It's Not You - It's Your Knowledge Base

Cache all the Things

Progressive Summarization helps with retaining key insights from text, the Hierarchy First Approach helps organize those summaries so that they can be found again later. The combination of the two lets us create a knowledge base of distilled insights that can be accessed at a moment's notice.

There are five levels to this hybrid technique and we'll spend some time explaining each in greater detail below.

Note
Expand
Split
Standardize
Refactor

Level 1 - Note

When you come across information that turns out to be useful, make a note of it. This is done by copying the relevant excerpts from the source material.

Greg is a new engineer at Literal, a social VR company. Their first assignment is to change a hard-coded welcome string to an internationalized string. Their mentor recommends using the CLI tool grep to find all instances of the string. Greg has never used grep before so spends some time learning about it. He captures a basic example of running the command in his notes.

## Synopsis



```
grep [OPTIONS] PATTERN [FILE...]
grep [OPTIONS] [-e PATTERN | -f FILE] [FILE...] 
```



## Example



```sh
grep 'python' *
```

Level 2 - Expand

If you find yourself continuously going back to the source material because you end up using more functionality, invest in adding more information to your note. For example, this could detail instructions for the new functionality or hard-won insights you've discovered through trial and error.

Greg finishes his first assignment and ends up doing more localization work. He uses grep quite a lot and discovers that he can use regex to speed up his workflow. He has also at this point noticed some mistakes he keeps making with the options. Greg makes a note of all of this.

## Synopsis



```
grep [OPTIONS] PATTERN [FILE...]
grep [OPTIONS] [-e PATTERN | -f FILE] [FILE...] 
```



## Gotchas

- large repetitions can cause memory exhaustion
- must escape `()|-` signs
- set option flags **before** the PATTERN

## Options

- \-P  use perl like regex (you can lookahead and lookbehind)
- \-i: Ignore casecase
- \-x: Force search to match line

## Example



```sh
grep 'python' *
```

Level 3 - Split

If you continue to expand the note, the note will eventually exceed the limit of a single page (eg. 800 words). At this point, you want to split your notes into smaller notes

NOTE: The process of splitting of large notes into smaller notes is also known as the amoeba pattern

Greg finds himself using grep all the time and he now has to spend time scrolling through his grep note to find what he needs. He has a section on snippets that makes up most of the note so he decides to split it off into its own note.

.
└── grep
    └── snippets

Level 4 - Standardize

As you continue the process of expanding and splitting notes, you tend to find certain clusters of notes will all have the same shape. When this pattern starts to emerge, you can standardize these patterns into hierarchies.

As Greg takes on bigger assignments, he also expands his arsenal of CLI commands. Greg realizes after a while that all CLI commands have a similar structure and so he consolidates it in a hierarchy.

.
└── cli/
    ├── grep
    │   └── snippets
    ├── sed
    ├── awk
    │   └── snippets
    ├── git
    ├── test
    └── ...

Level 5 - Refactor

In software engineering, refactoring is "the process of restructuring existing (information) — changing the factoring — without changing its external behavior"

Refactoring is done because the original structure can outgrow its usefulness. Sometimes the underlying information changes or your understanding of it does. Regardless, this means that you will need to update your hierarchies to account for this change.

Greg is tasked with a new assignment that involves working with windows and the PowerShell instead of the Linux terminal. He discovers that the PowerShell has its own set of commands and that the same commands in Linux will have slightly different behavior for Powershell. Greg proceeds to refactor his original hierarchy

.
└── cli/
    ├── linux
    │   ├── grep
    │   │   └── snippets
    │   ├── sed
    │   ├── awk
    │   │   └── snippets
    │   ├── git
    │   └── test
    │   └── ...
    └── powershell
        ├── CopyCmd
        ├── grep
        └── ...

Challenges

The workflow we just described can be applied outside of CLI commands to cover any information you might want to track. It allows you to systematically build up both your reference of "facts" in a domain as well as an underlying mental model of said domain.

The challenge in actually implementing this workflow generally surfaces in the latter two levels: standardization and refactoring.

Standardization into hierarchies is difficult because creating hierarchies is usually time-consuming and adds friction to both the retrieval and capture of new information.

Refactoring is hard because it usually relies on manually moving old notes into new hierarchies and also breaks links in the process.

This is why we created Dendron - a note-taking tool that helps people organize and refactor their notes.

By making it easy to standardize into hierarchies and refactor as needed, Dendron makes it possible to create, maintain, and make use of knowledge bases that span from a single README file to hundreds of thousands of notes!

Conclusion

Information can be overwhelming but it doesn't have to be.

We've long passed the point where we can keep everything in our heads. While that information is available on the internet, it takes time to find and is hard to retain.

By combining Progressive Summarization with a Hierarchy First Approach to Knowledge Management, we've created a workflow that lets us externalize an unlimited amount of information and the means to quickly find it again when needed.

This incremental caching of everything represents an escape from the endless cycle of searching for things we've already done and instead, lets us focus our efforts on the novel and bigger challenges of the day.

Imagine how much more effective we could be, as individuals, teams, and as a society, if we could build on top of what we knew instead of spending time forgetting and re-discovering hard-earned knowledge?

And now stop imagining and start caching!

Dendron 100

Kevin Lin — Tue, 21 Jun 2022 15:28:47 +0000

Dendron is launching on product hunt today. If Dendron has been of use to you, please leave feedback on our launch page - this would help us out a lot! 🙏

Context

Two years ago, we launched Dendron because we believed there was a better way of managing knowledge.

The problem - we are all drowning in information! Existing tools try to make it easy to get knowledge in but fail at getting that information back out when needed.

Dendron is a developer-focused, open-source, note-taking tool. It combines the simplicity of markdown with the power of VSCode. To manage information at scale, Dendron applies the insights we've learned from five decades of developer tooling and brings it to general knowledge.

Since 2020, we've been iterating on this thesis with weekly releases to make Dendron better, faster and stronger! With the v100 release, we'll take a moment to go over some highlights.

Better

In a well-designed system, easy things should be easy and hard things possible.

This hasn't always been the case at Dendron and it's something we've put in a lot of effort addressing through improved documentation, feature work, and better defaults.

Besides creating a catalog of talks and guides of how Dendron is used in the wild, we've also kicked off a standardization effort across all our docs so that any feature, command, or config is just a lookup away!

Feature wise, the following are some areas we've invested in to make common workflows easy:

the Dendron Sidebar provides one click access to most frequently used features like backlinks and the tree view
the Import Obsidian Vault command provides a one click method for importing your notes
the Help and Feedback panel provides a cheatsheet of useful resources and docs
the Tip of the Day panel highlights new features and enhancements

Finally, many of Dendron's core use cases now come with better defaults. For example, daily journals and meeting notes have built-in templates that get created the first time these commands are invoked.

Faster

Life is too short to wait for your notes to load.

Dendron has always been fast - much of this we get for free because your notes are just local plaintext files stored in your computer.
Over the past year, we've optimized all the parts of Dendron's lifecycle, which include initialization, lookup, publishing, and autocomplete just to name a few.

These changes resulted in orders of magnitude better performance across the board and <100ms of latency for the most common actions in Dendron 🚀 🚀 🚀

Stronger

Our goal is to make Dendron an IDE for knowledge.
Since 2020, we've released over 600 features to augment what you can do with plaintext.

Some highlights:

Handlebar Templates that allow augmentation of your templates with conditions, variables, and for loops
Hovers over links and backlinks
Note Traits that allow you to create notes with custom behavior
Publishing using NextJS with selective publishing

For the full changelog of all features, see the release notes.

Conclusion

Prior to Dendron, I worked at Amazon for over half a decade.
Something that stuck with me from my time there is that it's always day one.

This is especially relevant when dealing with knowledge management today because how humans manage information in the age of the internet is fundamentally an unsolved problem.
With Dendron, we think we have something that works.
Whether you are an individual managing a handful of notes or a team with tens of thousands of notes, Dendron helps you stay organized and on top of it all.

We've spent the past 100 releases iterating on our hierarchy first approach to note taking and we'll spend a few hundred more building on top of this foundation. On behalf of the entire Dendron team, I would like to say thanks to everyone that helped make this happen - chiefly our wonderful community and our steadfast investors. Here's to the next 100 releases!

Sincerely,

- Kevin

VSCode - Markdown Edition

Kevin Lin — Mon, 09 May 2022 15:57:50 +0000

With the 1.67 release, markdown gains programming language like tooling in VSCode

Specifically:

drag and drop files into the editor to create a markdown link
find all references to header|links|files|urls inside of markdown
rename headers|links inside markdown (and propagate the changes to all places where the link is used)
rename markdown files (and propagate changes to all links referencing said file)

If we move past drag and drop, it's notable that all other functions are related to referencing and renaming symbols. These are capabilities that are more commonly associated with programming languages than markdown.

A programming language is any set of rules that converts strings... to various kinds of machine code output

Wikipedia

Programming languages generally have a strict syntax that constrains the language. IDEs leverage this strict syntax to offer features to manipulate symbols within the language.

Markdown also has syntax (albeit more loosely defined) . This makes it possible to introduce similar transformations onto markdown.

The reason that this functionality is useful (and necessary) for programming languages is because codebases today can be massive, surpassing hundreds of millions of lines of code.

Repositories of markdown can also be massive. They are increasingly used to document and store general knowledge - both in the context of personal knowledge management (PKM) and team knowledge management (TKM).

For purposes of illustration - the primary vault (the circle titled private) for the Dendron team has over 400k lines of markdown.

The illustartion is generated using a fork of github's repo-visualization code, first described here

Running cloc returns the following output:

cloc --vcs=git .
github.com/AlDanial/cloc v 1.92  T=7.82 s (1472.4 files/s, 65739.6 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Markdown                     11494         108500             19         404711
JSON                             3              5              0            369
YAML                            14              1              0            351
-------------------------------------------------------------------------------
SUM:                         11511         108506             19         405431
-------------------------------------------------------------------------------

Given the shared syntactical properties and problems of scale between programming languages and markdown, it makes sense that the same tooling can work for both.

VSCode, and IDEs more broadly, help developers manage large code bases by making available tools to leverage and manipulate the syntax of programming languages. By shifting some of this tooling to markdown, can we do the same for large markdown repositories?

Our bet at Dendron is a resounding yes! This is why we built our knowledge management platform inside of VSCode. By leveraging the paradigms from IDEs and applying them to structured markdown, our mission is to help humans manage any amount of information.

Plaintext Task Management with Dendron and VSCode

John Knowles — Wed, 20 Apr 2022 16:11:27 +0000

Summary

Tasks come in all shapes and sizes.

Sometimes, we simply need a checkbox and a bullet to know what's complete and what's left to-do. Other times, we need to track more complex attributes of our tasks like deadlines, priorities, statuses, assignments, dependencies and more.

In this tutorial, we'll explore a simple and scalable solution to task management with Dendron. Dendron is a developer-focused note taking tool for that is open source, local-first, and integrated with Visual Studio Code.

Concepts

Task Notes

Task Notes are a special note in Dendron, like Scratch Notes or Daily Journal Notes. Task Notes use metadata in their frontmatter to help track and display task-related information.

Prerequisites

If you'd like to follow along, make sure you've read Getting Started, and are able to open a workspace.

Steps

Let's imagine a friend is having a birthday, and we want to bake some cookies to help celebrate. The party is in a few hours, so we'll need to act fast!

To show up to the party with cookies, we'll need to complete three tasks:

go to the store and buy the ingredients
mix the ingredients and bake the cookies
bring the freshly-baked cookies to the party

Create bullet tasks

We can begin with the simplest form of task management: a bullet list of checkmarks.

Open lookup (Ctrl+L / Cmd+L)
Type birthday-cookies in the text prompt and hit enter to create a note
Copy the following into the birthday-cookies note:

- [ ] buy ingredients
- [ ] bake cookies
- [ ] bring cookies to party

Check off a bullet task

After writing down our list, we make a quick trip to the store and return, ingredients in hand. We have completed our first task! Let's mark it off our list.

Type x into the brackets next to buy ingredients

- [x] buy ingredients
- [ ] bake cookies
- [ ] bring cookies to party

Your bullet list should now render Markdown checkboxes in Preview.

Create a task note

Not that we have the ingredients, it's time to bake. Looking at our bake cookies task, something feels missing...we don't know the steps involved in baking! Let's fix that...

Delete the bracket next to bake cookies. Your note should look like the following:

- [x] buy ingredients
- bake cookies
- [ ] bring cookies to party

Select the text bake cookies
Open the command palette (Ctrl+Shift+P / Cmd+Shift+P) and type task
Select the Dendron: Create Task Note command and hit Enter
You should see the text birthday-cookies.bake-cookies. If not, correct the text. Hit Enter again.

For reference, we are using the following configuration for this tutorial (the default in Dendron):

    task:
        name: task
        dateFormat: y.MM.dd
        addBehavior: asOwnDomain
        statusSymbols:
            '': ' 'p
            wip: w
            done: x
            assigned: a
            moved: m
            blocked: b
            delegated: l
            dropped: d
            pending: 'y'
        prioritySymbols:
            H: high
            M: medium
            L: low

Visit here for more information on the configuration of special notes like task notes.

Check off a task note

Congrats, you've created a task note! You may notice something strange with this new note. There's something extra in the frontmatter (the YAML text at the top of the file).

🗒 Note: Frontmatter is hidden by default in task notes. To expand, click the arrow next to the top line.

Add an 'x' next to status so it reads:

status: 'x'
due: ''
priority: ''
owner: ''

Navigate back to the birthday-cookies note.

💡 Tip: To quickly go back to the previous note, use the Alt-Tab shortcut

You should see that the bake-cookies note has a filled checkbox.

- [x] buy ingredients
- [x] [[bake cookies|birthday-cookies.bake-cookies]]
- [ ] bring cookies to party

Task notes give we get an up-to-date view of the task's status any place it is linked to. But let's not get ahead of ourselves, we haven't done any baking yet!

Return to birthday-cookies.bake-cookies and remove the x next to status so that it reads: status: ''.

🚧 Under Construction: We appreciate your patience as we develop new features like task notes. Currently, checkboxes are under construction, and are not rendering correctly in Preview.

Break into subtasks

Let's make a task for each step:

prepare the oven and ingredients
mix the ingredients
form dough balls and bake in the oven

Copy the following into birthday-cookies.bake-cookies

- prepare oven and ingredients
- mix ingredients
- form balls and bake

For the mix ingredients and form balls and bake subtasks, create a task note as you did above:

Select the text for the new task
Open the Command Palette
Run the Dendron: Create Task Note command

Your bake-cookies task should now look as follows:

- [ ] [[prepare oven and ingredients|bake-cookies.prepare-oven-and-ingredients]]
- [ ] [[mix ingredients|bake-cookies.mix-ingredients]]
- [ ] [[form balls and bake|bake-cookies.form-balls-and-bake]]

Navigate to bake-cookies.prepare-oven-and-ingredients and check out at the backlinks of the note

💡 Tip: By nesting our tasks notes (linking to a task inside another task), we can monitor which tasks are dependent on others using backlinks.

Return to your birthday-cookies note and hover your mouse above the link to the bake-cookies note. You should see the newly created tasks in Quick Preview.

💡 Tip: Try clicking on one of the tasks in the Quick Preview. Look, it's a link!

Look at you go, you've created subtasks!

Now, you can track your progress at a more granular level through the different baking steps. Soon, the smell of cookies will be in the air, and it will be time to party! 🥳

Wrap-up

Takeaways

Upon completing this tutorial, you've learned about:

creating a simple tasks using [ ]
creating a task note
adding subtasks

Task management in Dendron is flexible. Through task-specific features like bullet tasks, task notes, subtasks and configs, as well as familiar features like hierarchies and bidirectional links, Dendron gives you the tools to tackle tasks at any scale.

Next Steps

Customize your task notes with a custom configuration
Learn about the process of starting simple and reshaping with the Amoeba Pattern
Learn more about how Dendron supports other workflows, like Bullet Journaling and Todos
Read through the proposal for task notes and give your feedback on tasks in Dendron
See how other Dendrologist manage tasks from a live demonstration
Learn how Dendron manages tasks as a team in our organization handbook

2021 Dendron New User Survey Results

Derek Ardolf — Tue, 08 Feb 2022 20:51:32 +0000

The new user survey was open for several months in 2021, where we were prompting new Dendron users within VS Code itself. We had a few thousand respondents take the opportunity to give us feedback.

What backgrounds do our users have?

Users were asked about their backgrounds. Just over half of respondents had a background as Software Developers (53%), while the next largest group were Students (14%).

Approximations of remaining background options:

Researcher (7%)
Manager (7%)
DevOps (7%)
Technical Writer (4%)

The Other (8%) were spread across the following groups:

The percentages are in relation to the total number of respondents in Other

Systems/Infrastructure/IT/InfoSec Administrators/Engineers (13%)
- Solutions Architects
- InfoSec / CyberSecurity
- Systems Engineers/Administrators
- etc.
General Hobbyist/Multipotentialite/Polymath (8%)
Data Scientist (6%)
Artist (Designer/Musician/etc.) (5%)
Author/Writer/Blogger (3%)
Teacher/Professor (3%)

There were some smaller groups that stood out in the Other category, having one to three respondents:

Therapists
Legal (Lawyers/Law Graduates)
GeoChemistry
Pharmacist
Biologist
D&D Player
Dentist

What are people using Dendron for?

New users were able to select all that applied. A majority of users are coming to Dendron, first and foremost, for a Personal Knowledge Base (80%) solution.

Approximations of remaining uses:

Todos and Agenda (57%)
Research (47%)
Meeting notes (45%)
Team knowledge base (29%)
Publishing (22%)

The Other (18%) included the following groups:

The percentages are in relation to the total number of respondents in Other

Student/Learning/Class/Academia Notes (4%)
Journaling (4%)
Content Creation and Non-fiction/Fiction Writing (3%)
Project / Software Documentation (2%)
System/Product Configuration and Design (2%)
CRM (1%)
Second Brain (1%)
Gaming Notes (D&D, RPGs, General) (1%)

There were some smaller groups that stood out in the Other category, having one to three respondents:

Scripted/Automated documentation creation
Tracking, Reading, and Taking Notes on Books
Recipes / Cookbook
Drafting GitHub issues/MRs
Event planning
Presentations

Are users coming from any existing tools?

New users were able to select all that applied. More users said they were coming from No Previous Tool (26%) than users who found themselves looking at Dendron after something else, with OneNote (25%) coming in a close second.

Approximations of remaining previous (or parallel) tools:

Notion (23%)
Google Keep (19%)
Obsidian (18%)
Evernote (14%)
Roam (5%)
Logseq (5%)
Foam (5%)

15% of respondents provided additional information under Other, providing a total of over 70 different tools and workflows. Here are the top Other tools listed.

The percentages are in relation to the total number of respondents in Other

Joplin (9%)
org-mode / org-roam / emacs (6%)
Bear (6%)
Apple Notes (4%)
Plain Markdown or text files (4%)
Trello / Confluence / Jira (4%)
Typora (3%)
Physical notes (2%)

Do users have plans on publishing their notes?

New users were only able to select a single response, if they were to respond to this question at all. A majority of users were Curious (39%) about publishing, or otherwise already saying Yes (36%) to planning publishing. The remaining respondents said No (25%) and were not interested.

What's Next

We've set aside the majority of this quarter, and the last, to iterate on the feedback you've given us (specific details to come in a future blog post).
We are committed to making Dendron the absolute best tool and community for thought in 2022 and beyond!

If you like to be part of the effort, please take part in the 2022 Dendron User Survey and help us build a better tool for thought 🌱

Enjoy the blog? Subscribe to our newsletter!

Newsletters not your thing? You can also follow us elsewhere on the interwebs:

Interested in creating your own knowledge base using markdown, git, and VSCode? Get started with Dendron today.

The Five Minute Journal with Dendron and Visual Studio Code

Derek Ardolf — Thu, 06 Jan 2022 16:39:05 +0000

It's 2022 and you're looking to start off the year right by keeping a journal. Where to start? The Five Minute Journal (5MJ)¹ is a simple but effective way to get started with note taking.

The Five Minute Journal

Tim Ferriss,² world-famous entrepreneur and author of books such as Tribe of Mentors,³ uploaded a video in 2020 all about his approach to note taking with physical notebooks.⁴ 5MJ helps him express gratitude, make days better, and focus on mindfulness.

In this post, we'll be going over how to create your own 5MJ using Dendron. Dendron is a structured note taking tool for developers that is open source, local first, and integrated with Visual Studio Code (VS Code).

Prerequisites

This post expects that you've gone through the Dendron Getting Started Guide and have a workspace opened to work with. If you're new to Dendron, make sure to take a look.

Concepts

Daily journal notes

Daily journal notes are special notes meant to easily track your everyday life. Dendron also has a built-in Calendar View that helps you visually navigate and create new journal entries.

Templates

Templates are notes with pre-outlined content meant for reuse. Templates can either be inserted into an open note with the Dendron: Insert Note command, or automatically applied at note creation with Schemas. These are meant to reduce friction in the creation of new content, providing standardized outlines to your notes.

Schemas

As you end up creating more notes, it can be hard to keep track of them all. This is why Dendron has schemas to help you manage your notes at scale. Think of schemas as an optional type system for your notes. They describe the hierarchy of your data and are themselves, represented as a hierarchy.

Steps

Create 5MJ template

Open lookup (Ctrl+L / Cmd+L)
Type templates.daily-5mj in the text prompt and hit enter to create the template
Copy and paste the following markdown:

<!--
Based on the journaling method created by Intelligent Change:
- [Intelligent Change: Our Story](https://www.intelligentchange.com/pages/our-story)
- [The Five Minute Journal](https://www.intelligentchange.com/products/the-five-minute-journal)
-->

## Morning

<!-- Fill out this section after waking up -->

### Gratitude

I am grateful for:

1.
2.
3.

### What would make today great?

1.
2.
3.

### Daily affirmations

I am...

## Evening

<!-- Fill out this section before going to sleep, reflecting on your day -->

### Amazing things that happened today

1.
2.
3.

### How could I have made today even better?

I could have made today better by

Save the file.

You now have a new template with the 5MJ outline.

Create 5MJ schema

Templates can be used with or without schemas. Run Insert Note to insert a template into a currently opened note.

Open schema lookup (Ctrl+Shift+L / Cmd+Shift+L)
Type 5mj in the text prompt and hit enter to create the schema, which should look like the following:

version: 1
imports: []
schemas:
  - id: 5mj
    children: []
    title: 5mj
    parent: root

Update 5MJ schema contents

We are going to use Inline Schema, a simpler schema format that takes less lines and uses indentation for visual understanding.

Replace the content of 5mj.schema.yml with the following:

version: 1
schemas:
# Daily is the top most schema since its parent is 'root' it must have an identifier
# this identifier 'daily' will be used when using 'Lookup (schema)' command.
- id: daily
  parent: root
  title: daily
  desc: ""
  # Children of the top most schema do not need to contain identifier and just 
  # require a 'pattern' to be set to match the hierarchy of notes.
  children:
    - pattern: journal
      children:
          # This pattern matches the YYYY (year) child hierarchy
        - pattern: "[0-2][0-9][0-9][0-9]"
          children:
              # This pattern matches the MM (month) child hierarchy
            - pattern: "[0-1][0-9]"
              children:
                  # This pattern matches the DD (day) child hierarchy
                - pattern: "[0-3][0-9]"
                  # As with regular schema we can set the template to be used with
                  # the match of our notes. Below is an example usage of shorthand template
                  # definition (which defaults to type: note). 
                  desc: Five Minute Journal
                  template: templates.daily-5mj

The pattern attribute is using a Glob Pattern, which is an expression used to match ranges and combinations of characters.

To match with the daily journal structure:

Example: daily.journal.2021.12.31
Patterns:
- Year: [0-2][0-9][0-9][0-9] means match the range 0000 - 2999
- Month: [0-1][0-9] means match the range 00 - 19
- Day: [0-3][0-9] means match the range 00 - 39

This means all new daily journal notes are within pattern ranges.

Create a new daily journal

Creating a daily journal entry results in the templates.daily-5mj template automatically inserted.

Run Create Daily Journal Note (Ctrl+Shift+I / Cmd+Shift+I)

You should see a new daily journal note with the 5MJ template inserted.

Congratulations!

Key takeaways

After doing this, you've now:

Created a 5MJ template
Created a 5MJ schema
Created your first daily journal with the 5MJ template applied via schema

Next steps

Now what? You have daily journals using templates, but Dendron can do much more. It's an open source, local-first knowledge management solution that scales as you do.

Learn to swiftly create schema by targeting existing note hierarchies
Learn to level-up your daily life with the bullet journaling workflow
Learn to explore your schema visually using the schema graph
Check out an end-to-end workstyle, managing 20k notes, using schemas and daily journals from A Day in Dendron
Dendron FAQ
Dendron Concepts

Enjoy the blog? Subscribe to our newsletter!

Newsletters not your thing? You can also follow us elsewhere on the interwebs:

The Five Minute Journal, by Intelligent Change ↩
It's hard to use one sentence to describe all the things Tim Ferris does. He has one of the most popular podcasts in the world, and has authored several books from all of his notes and interview content. He seems shorter in person. Anyway, learn more at his website! ↩
For a list of books, see Books by Tim Ferriss. ↩
The video: How I Journal and Take Notes: Brainstorming + Focusing + Reducing Anxiety. For a companion guide to the video, take a look at How Tim Ferriss Uses The Five Minute Journal: 6 Tips For New Journalers. ↩

Share Your Notes Online: Publish Dendron with Netlify and GitHub

Derek Ardolf — Fri, 10 Dec 2021 19:29:06 +0000

Dendron helps people and products organize with notes, docs, and knowledge of all the things. Let's see how easy it is to publish and have a static site hosted on Netlify!

You'll learn how to publish your Dendron notes using Netlify and GitHub, which looks like this demo website. This tutorial assumes that you have basic knowledge of GitHub and Visual Studio Code (VSCode).

This uses a brand new Dendron Workspace you can later configure to work with your own vaults. Do you already have a workspace you'd prefer using? Reference the Dendron docs for in-depth details on how the template, and other workspaces, can publish to Netlify: Publishing with Netlify.

Part 1: GitHub

When logged into GitHub, click here to generate a new Dendron Workspace pre-configured for Netlify publishing. If you're wondering, we're using this template on GitHub.

Nice! That's all we need to do for this minimal Dendron setup. To understand what is going on behind the scenes, you can read the template README.

Note that this tutorial will work with both private and public repositories.

Part 2: Netlify

The rest of the steps are done in the Netlify portal.

Step 1: Import your repository

When logged into Netlify, you start on your Team Overview page.

Click New site from Git
Under Connect to Git provider, select GitHub
- You'll be asked configure Dendron for permissions. It's best practice to go with Only select repositories, and selecting the repository you made from the template

Once permissions are configured, select the repository in Netlify. There is no need to change any of default values, since the GitHub template is providing them from netlify.toml. Scroll to the bottom, and click Deploy site.

Your website should now be building!

For more information on Netlify app permissions, to GitHub, refer to Netlify Docs: Authentication with the Netlify GitHub App

Step 2: Configure your website name

By default, Netlify generates a random combination of strings. In the example so far, the website is named elastic-hugle-37bfd5.netlify.app. If you don't want to own your own domain name, you can at least change the elastic-hugle-37bfd5 section.

Site settings
Under Site information, click Change site name
Enter new name, and if it is available, click Save

For more information on custom domains, beyond the above, refer to Netlify Docs: Custom domains

Step 3: View deploy status

Under the Deploys tab, in Netlify, you can view the status of your website. This is where build information will be posted whenever new commits are posted to the main branch of your repository on GitHub.

This is a great way to check whether build have failed, or are still in progress. If you run into any errors, and aren't sure what to do next, jump into the Dendron Discord where we have a #questions channel.

Summary

You're done! From now on, all new commits you make to your repository on GitHub will trigger a new publishing update to your website.

In this tutorial, you learned how to:

Create a pre-configured, minimal Dendron Workspace from a template
Import a repository into Netlify
Create a custom name for your Netlify website
View deploy status in Netlify

Next steps

Now what? Publishing is set, but Dendron isn't just for what you want to share with the world. It's an open source, local-first knowledge management solution that scales as you do.

Enjoy the blog? Subscribe to our newsletter!

Newsletters not your thing? You can also follow us elsewhere on the interwebs:

Highlights from VSCode 1.62

Derek Ardolf — Tue, 23 Nov 2021 22:33:29 +0000

The open source VSCode project, along with VSCodium¹, completed their latest monthly release with v1.62². For those of us that haven't been using the Insider's Build,³ it's time to look at what's new.

Make sure to checkout the VSCode 1.62 Release Party on YouTube!

Live Share session sharing in Virtual Workspaces

Virtual Workspaces⁴, such as vscode.dev and github.dev, now support this superpower: sharing a session directly from the browser.

Haven't used Live Share before? Many people are attracted to Google Docs due to how easy it is to collaborate, comment, and highlight sections in order to give each other scathing reviews. Introducing Live Share: instead of waiting for the PR review, you can provide non-constructive feedback to your peers!

Take note: if you are a VSCodium user, sharing/joining sessions won't work. I learned this after spending too much time confused. Be aware of the live-share license agreement, including the information about data collection, which may be part of the incompatibility with VSCodium. There are alternatives, though, such as CodeTogether.

Release Party: Live Share (in vscode.dev)

Bracket pairs

I enjoy whenever features lessen confusion for my eyeballs. I never bought a pair of Google Glass, even as men everywhere were accidentally taking photos while using urinals in pubic restrooms. Bracket pair highlighting, though, to show where I am in the russian dolls of nested loops? Yes, please.

Settings of interest:

"editor.guides.bracketPairs": "active": Only show guides for only the active bracket pair.

"editor.guides.bracketPairs": "true": Show guides for all bracket pairs, with different colors.

Release Party: Bracket pair colorization

Verified publishers

When installing extensions, it's nice knowing you're installing the real deal. Microsoft could have gone the whimsically difficult route that Twitter has taken with their blue checkmarks, but instead they have made it an easy process. This was how I learned GitLens was acquired by GitKraken: the truth is out there.

Found a duplicate extension? Check whether one is from a verified publisher by jumping into the Marketplace.

Release Party: Verification for extensions publishers

Other notables

General tip: Wondering what shortcuts are configured in VSCode? One shortcut to rule them all: Ctrl+K Ctrl+S

Or Ctrl+Shift+P -> Preferences: Open Keyboard Shortcuts

A CVE was addressed involving characters that became invisible, leading to code that could compile differently than visually expected.
Extension note: GitHub PRs and Issues brings issue and PR interaction directly into VSCode. Have you taken a look yet?
- Latest updates can be seen in the extension changelog.
Issues resolved in point releases, referred to as "Recovery" releases, can be found on GitHub: 1.62.1, 1.62.2, and 1.62.3.

Enjoy the blog? Subscribe to our newsletter!

Newsletters not your thing? You can also follow us elsewhere on the interwebs:

Interested in creating your own knowledge base using markdown, git, and VSCode? Get started with Dendron today.

Checkout VSCodium, for the truly MIT-licensed version of the VSCode IDE (with telemetry/tracking disabled). ↩
VSCode release notes for 1.62, along with release notes for previous monthly releases. ↩
The VSCode Insiders Build allows users to get VSCode with new features as soon as they are available, rather than at the monthly cadence. ↩
Reference the VSCode Blog Post on vscode.dev for a full rundown on Virtual Workspaces and bringing VSCode to the browser. Last month, there was a livestream all about it! Watch VS Code for the Web: vscode.dev on YouTube. ↩

Highlights from VSCode 1.61

Derek Ardolf — Fri, 29 Oct 2021 14:45:36 +0000

The open source VSCode project, along with VSCodium¹, completed their latest monthly release with v1.61². For those of us that haven't been using the Insider's Build,³ it's time to look at what's new.

As a bonus for this release, Microsoft held a little VSCode 1.61 Release Party on YouTube. Watch the recording, see the devs show off features, and feel like you were actually invited to a party!

Locked editor groups

Note: this is an experimental feature.

Don't lose track of a file or terminal you are bouncing back-and-forth between in your gigantic list of editor tabs: use locked editor groups. These prevent VSCode from opening more editor tabs in a group (a collection of tabs).

I like this feature, as I'm often opening new files in the wrong area of the screen. I want those side-by-side, computer!

Release Party: Editor and workspace improvements demo

Split an editor without creating a new group

Do you find yourself looking at large files, and wish you could scroll down while staying in place elsewhere? Now you can, by doing the splits without creating a new group. Test it out with View: Split Editor in Group in the command palette (Ctrl+Shift+P) or with the keybinding shortcut: Ctrl+K Ctrl+Shift+\. This is useful when converting pieces of code into functions, trimming fat, copy/pasting comment blocks, and whatever else your heart desires.

No new group means not having yet another tab open in your editor!

Release Party: Editor and workspace improvements demo

Webview UI Toolkit for Visual Studio Code

For extension authors making use of the webview API for customizable views in the editor, life is about to become easier: say hello to the Webview UI Toolkit. This is an open-source component library, providing Visual Studio Code design language, which matches the look and feel of VSCode/VSCodium. This is compatible with your tech stack of choice, bet it React, Vue, or OMGNewJSFramework!

Other notables

General tip: Wondering what shortcuts are configured in VSCode? One shortcut to rule them all: Ctrl+K Ctrl+S

Or Ctrl+Shift+P -> Preferences: Open Keyboard Shortcuts

Confusion was caused by a new telemetry config option, telemetry.telemetryLevel, which would display that telemetry was enabled (even if it was previously disabled). The full discussion can be found on GitHub, which led to improvements being implemented in the 1.61.1 update.
Platform-specific extensions: no longer try installing a MacOS-only extension on your Windows system, or vice-versa. That is, if the extension developer specifies the supported OS targets. This was previewed at the release party.
I often came back to my laptop to find that my terminal was having a stroke in the VSCode editor. This seems to be resolved!
The latest point releases⁴ include fixes for other problems, such as high CPU consumption. Make sure to keep up-to-date!

I can't forget: want to take a look at VSCode in your web browser, without installing a thing? These are called Virtual Workspaces, such as vscode.dev and github.dev. Reference the VSCode Blog Post on vscode.dev for a full rundown on bringing VSCode to the browser.

Enjoy the blog? Subscribe to our newsletter!

Newsletters not your thing? You can also follow us elsewhere on the interwebs:

Interested in creating your own knowledge base using markdown, git, and VSCode? Get started with Dendron today.

Checkout VSCodium, for the truly MIT-licensed version of the VSCode IDE (with telemetry/tracking disabled). ↩
VSCode release notes for 1.61, along with release notes for previous monthly releases. ↩
The VSCode Insiders Build allows users to get VSCode with new features as soon as they are available, rather than at the monthly cadence. ↩
Issues resolved in point releases, referred to as "Recovery" releases, can be found on GitHub: 1.61.1 and 1.61.2. ↩

Best Mobile Note-Taking Apps for Markdown

Derek Ardolf — Mon, 25 Oct 2021 19:25:00 +0000

On the desktop, markdown-based notes can be taken in any plain-text editor of choice. If you're using Dendron, you can use VSCode/VSCodium as well as a suite of powerful commands to manage your notes. Though, what happens when you walk out the door? It turns out that your phone can work with markdown, too!

What we're looking at today:

Obsidian
GitJournal
Markor
iA Writer
Other apps of interest
- Markdown notes
- Git clients
Last thoughts

Obsidian

"Obsidian is a powerful knowledge base on top of a local folder of plain text Markdown files."

Cost: Free for personal use (or paid options for business use and other features)
OS: Android, iOS / iPad / Mac, Windows
Open Source: No
Built-in git integration: No

Obsidian is a PKM (Personal Knowledge Management) tool that provides a sleek UI to Markdown files. It had the best mobile experience, for me, out of the apps I tested. Though it doesn't have git support built-in, other mobile apps can assist in providing that backend. I recommend MGit (Android).

Obsidian uses wikilink style links (ex. [[my.other.note]]), like Dendron, which is a nice plus.

Paid options can assist note-takers with automatic syncing, publishing of notes, and other perks. Note that obsidian is free for personal use but requires at least a paid commercial license for business use.

GitJournal

"Mobile first Markdown Notes integrated with Git."

Cost: Free (or a paid Pro option)
OS: Android, iOS
Open Source: Yes (AGPL-3.0)
Built-in git integration: Yes

GitJournal has gained quite a bit of interest: it works on your mobile device of choice, free to jump into, open to contributions, and can sync notes to a repo (or multiple repos with the Pro version). The project is built with Flutter, making life easier when it comes to multiple-platforms as target exports.

GitJournal also supports wikilinks and can therefore be used with Dendron and Obsidian.

I'm really interested in seeing where GitJournal goes. I couldn't find other mobile apps that covered both notes in Markdown and git-integration, without needing to juggle multiple apps. With my Dendron vaults, I mostly take scratch notes or edit already-existing notes when using my phone. For more extensive usage, I hop on the laptop.

I will say, though, that I ran into so many problems in trying to get my first demo repository setup that I stopped using GitJournal. Other users are running into issues at the moment having to do with syncing and setup, some of which might be tied to a hardcoded expectation of branch names (such as master). I now use mgit for managing my repos, and Obsidian for managing notes.

iA Writer

"iA Writer offers a unique writing experience that lets you concentrate and clarify your message. Used by half a million people worldwide, its powerful interface is crafted to cut out noise, let you focus on what you want to say, and help you structure and trim your text."

Cost: $29.99
OS: Android, iOS / iPad / Mac, Windows
Open Source: No
Built-in git integration: No

iA Writer was initially released 10 years ago, and has since evolved to work on multiple platforms. Though it doesn't have git integration, other apps like GitJournal or MGit (Android) can be used for that.

Want to feel like a designer, in a sleek interface with minimalist and Apple-like branding? This is made for you. The editor can work across all devices: phones, tablets, and desktops.

Being a feature-full piece of software, including:

Style-checking to help improve note quality
Can export to Word
A larger list of all-the-things can be found on their main landing page.

Markor

"Markor is a TextEditor for Android. This project aims to make an editor that is versatile, flexible, and lightweight. Markor utilizes simple markup formats like Markdown and todo.txt for note-taking and list management."

Cost: Free
OS: Android
Open Source: Yes (Apache 2.0, w/ special note on commercial license)
Built-in git integration: No

Markor is without git integration, but can be combined with an app like GitJournal or MGit (Android) for syncing to a source repo.

I liked both the editor and preview rendering in Markor more than the other apps I tried. Syntax highlighting is a nice touch while editing, and the previews look cleaner than both iA Writer and GitJournal.

Though, the cons here are that Markor only works on Android and needs another app to handle git integration. Outside of that, I can quickly see why thousands of ratings have led to nearly a 5/5 on the Google Play.

Other apps of interest

There are many mobile note-taking solutions that work with Markdown. Below are some additional tools that Dendrologists have used for markdown on the go.

Markdown notes

Working Copy (iOS)
- Git client, paid (free version can't push commits). This app comes up quite a bit for iOS users and within the Dendron Discord in our #mobile channel, so I'm listing it at the top.
Noteless (Android)
- Open source, free, includes AsciiMath, KaTeX, mermaidjs
- An experimental feature option supports Dendron formatted wiki links
Neutrinote (Android)
- Open source, free, includes LaTeX / math rendering support
Editorial (iOS)
- iPad + iPhone, paid, integrated Python bonus
Taio (iOS)
- iPad + iPhone + Mac, free (or paid option has perks, such as Javascript-supported actions)
Textastic (iOS)
- iPad + iPhone + Mac, paid, code-highlighting, ssh/FTP/SFTP/Dropbox/Google Drive support

Git clients

MGit (Android)
- Git client, open source, free. There is a reason I repeatedly mention it in this article, when it comes to Android users, because it handles git repos well.
Working Copy (iOS)
- Git client, paid (free version can't push commits)

Final thoughts

Users may also be interested in future development around the GitHub mobile client, which currently does not support being able to edit or contribute new files. For now, people can use the app to post "LGTM" to PRs, add thumbs-down emojis to issues, and get notified when your PRs are rejected.

git is not the only way to sync/backup your notes, since tools like Dropbox, Google Drive, iCloud, and Keybase can also help provide that functionality. I, and other Dendrologists, have a bias toward git due to a variety of reasons:

Following the Docs as Code approach
Treating all documentation as part of a distributed wiki system that can import docs, from any source, into a single workspace
git versioning
Anyone that has used GitHub, GitLab, or other git-hosting solutions will have git installed

If I had to choose what combinations to use, on Android, I'd recommend Obsidian with MGit (Android). The two, together, have worked very well for me. I'm also a fan of setting up SSH keys to have project/repo-limited permissions as Deploy Keys on GitHub (with Allow write access enabled). This prevents users from setting up SSH keys with user-wide permissions across GitHub.

Enjoy the blog? Subscribe to our newsletter!

Newsletters not your thing? You can also follow us elsewhere on the interwebs:

Interested in creating your own knowledge base using markdown, git, and VSCode? Get started with Dendron today.

Writing a Visual Studio Code Completion Provider

Kevin Lin — Thu, 23 Sep 2021 16:43:43 +0000

Visual Studio Code (VSCode) provides many powerful features for extension developers. Autocomplete, warnings, tasks, and many more features are included out-of-the-box and are available for extension developers to take advantage of. However, figuring out how you can take advantage of these features as an extension developer can require digging through API documentation to learn the exact behavior. Using the API incorrectly can lead to issues that are hard to debug, as I learned working on the block autocomplete feature for Dendron.

This post is an overview of VSCode autocomplete —also called intellisense— feature from the viewpoint of an extension developer. I especially want to highlight a few pitfalls: VSCode provides defaults for many of the options around autocomplete, but the behavior of these defaults can be confusing if you don't know what they are.

Entry point

Your entry point into adding an autocomplete feature is languages.registerCompletionItemProvider. This allows you to attach a function that will generate the options when requested.

languages.registerCompletionItemProvider(
  "markdown",
  {
    provideCompletionItems: provideBlockCompletionItems,
  },
  "#",
  "^"
);

Above is how Dendron attaches the completion provider for blocks. This part is straightforward, although note the symbols at the end. These are the symbols that when written will trigger your completion provider automatically. While you can define multiple symbols, each symbol has to be a single character. If An overview & tutorial of writing VSCode completion providers (intellisense) as an extension developer

Next, let's take a look at the completion function. Here is the function signature for Dendron:

export async function provideBlockCompletionItems(
  document: TextDocument,
  position: Position,
  token?: CancellationToken
): Promise<CompletionItem[] | undefined> {

document and position are straightforward. token is used to cancel completions, for example if the user hits cancel while waiting for the completions. Key thing about the token is to remember that javascript is single-threaded: the token won't suddenly get cancelled in the middle of your function. The only point where it can become cancelled is if you await for something and yield the execution. This means you don't have to check if the token is cancelled everywhere in your code, just check after any awaited operation that might take a significant amount of time. Checking the token is easy, if (token?.isCancellationRequested) return; is enough.

The more important thing here is how the function gets called. One way the function will get called is if the user types one of the trigger symbols you registered. Another way is if the user hits the key for "Trigger Suggest" (Ctrl+Space by default), all registered completion providers for this language will run. Crucially, this means your completion provider may be activated at any point in the document, with or without your trigger key.
It's up to your implementation to check if the current position is somewhere that this completion is appropriate for, and return; if not. Let's look at a simplified version of how Dendron handles this for the autocomplete:

let found: RegExpMatchArray | undefined;
const line = document.lineAt(position.line);

// There may be multiple links within this line
const matches = line.text.matchAll(LINK_WITH_BLOCK_REGEX);
for (const match of matches) {
  if (_.isUndefined(match.groups) || _.isUndefined(match.index)) continue;
  const { entireLink } = match.groups;
  // If the current position is within this link, then we are trying to complete it
  if (
      match.index <= position.character &&
      position.character <= match.index + entireLink.length
  ) {
      found = match;
  }
}
if (_.isUndefined(found)) return;

The gist of it is that we get the text for the current line, and check if the current position is inside a link with a block that we can complete.

`CompletionItem`

`label`

A key part of the completion item is the label. The label is not only displayed for the completion items, but it's also used as a default for many of the options in a CompletionItem. The text that gets inserted when the user selects something, deciding the order in which these items are displayed, and how these options are narrowed when the user types are all based on the label by default.

`range`

The range is the most confusing part of the CompletionItem in my opinion. The range determines 2 things: where the selected item will be inserted, and also what counts as "stuff that the user typed to narrow the items".

For the first use of range, whatever range you provide will be replaced with the insertText (or missing that, label) of the completion item. If you have nothing to replace, the range can have start === end in which case the text is just inserted at that point.

The second use of range makes things a bit more tricky. Because the range determines what counts as "stuff the user typed", you have to be careful about what you include in the range. For example, Dendron's autocomplete allows users to type [[^ to get all blocks within a text as autocomplete options.

The problem? The user needs to type ^ to activate the completion, but ^ is not part of any completion item, and also ^ needs to be removed once an item is selected because the text is supposed to look like [[#^something]] after the completion.

While it would be convenient to just set the range to anything within the brackets, this will result in all completion items being narrowed out because ^ will also count as "stuff the user typed to narrow the items".

Something important to bring up here is the default for range. If you look
into the docs, you'll see that the default is the "range of the current word",
effectively the output of TextDocument.getWordRangeAtPosition function.
getWordRangeAtPosition allows you to set a custom regex to select what
"current word" means, so this might sound like a good way to calculate the
range. While this would work in some cases, I found that
getWordRangeAtPosition is extremely inefficient if your regex is more complex
than [...]+. Especially using lookaheads or lookbehinds causes VSCode to
completely hang. I'd recommend avoiding this function unless the default mostly
works for you.

`sortText`

This field is used to determine in what order the completion items are initially ordered. Initially is important here, as VSCode may move the items around once the user starts typing if it decides some items match the text better.

The annoying part about sortText: it simply sorts the items using basic string sorting. Issue here being that if you have a loop to generate your completion items, you can't just use the index to sort the items.

blocks.map((block, index) => {
  // These won't sort right, because "11" < "9" in string sort
  return {
    label: block.text,
    sortText: String(index),
  };
}

The fix is to pad your sortText.

sortText: String(index).padStart(5, '0'),

This is not a perfect fix of course, but it's unlikely that you'll have over 99999 completion items.

`insertText`

This is the text to be inserted when the user selects a completion. By default
it's set to the label, but you'll want to set this if you are using the label to
display something more informative to the user. For example, when completing
blocks, Dendron uses the label to display the actual line the user is selecting.
But the text we need to insert into the wikilink is not the same as the line
itself, so we set this to get it to link to the right place.

insertText: `#${AnchorUtils.anchor2string(anchor)}`,

`additionalTextEdits`

insertText replaces the part of the text that is selected by the range. This
is actually quite limiting: As I mentioned before, range not only selects the
what will be replaced but also what VSCode considers "typed by the user to
narrow options". What if you want something to be replaced along with what the
user typed, but you don't want it to be used in narrowing?

For example, when autocompleting for blocks in Dendron the user might type
[[^some-header, but the resulting link will look like
[[#some-header-text-here]]. We need to remove ^ along with whatever the user
typed, but if we set the range to include it then the narrowing would be
thrown off because it would look for options where the label includes ^.
To get around this, we use the additionalTextEdits to automatically remove the
^ part.

Another use for additionalTextEdits is to insert text somewhere completely
different in the document. Think of auto-imports for some languages, where you
type something and the language automatically adds import .... Or in Dendron,
if the user selects a block that doesn't already have a block anchor when
completing blocks, we need to insert a block anchor there. additionalTextEdits
have no limits to where they can put the text, as long as it's within the same
document. In any case, let's see what this code looks like:

const edits: TextEdit[] = [];

if (found.groups.trigger) edits.push(
  new TextEdit(
    new Range(
      position.line, found.index + 2,
      position.line, found.index + 2 + found.groups.trigger.length
    ),
    ""
  )
);

if (_.isUndefined(anchor)) {
  anchor = {
    type: "block",
    value: genUUIDInsecure(),
  };
  const blockPosition = VSCodeUtils.point2VSCodePosition(
    block.position.end
  );
  edits.push(
    new TextEdit(
      new Range(blockPosition, blockPosition),
      ` ${AnchorUtils.anchor2string(anchor)}`
    )
  );
}

The first part adds a text edit to remove the ^ part the user typed by
calculating the range from a regex match, then replacing it with "". The
second part adds the ^... part to a block by calculating the range from the
parsed document.

Conclusion

Autocomplete is a ubiquitous feature in text editing today, both for writing
natural languages and coding. It is an incredibly easy-to-use yet powerful
feature for your users, and it enables unmatched user experiences when done
right. But when done wrong, it can cause a disconnect and confusion around your
product. At Dendron, we strive for the former and hope that the learnings from
our experience will help you do the same.

Highlights from VSCode 1.59

Derek Ardolf — Thu, 02 Sep 2021 18:25:57 +0000

The open source VSCode project, along with VSCodium¹, completed their latest monthly release with v1.59². Let's take a look at some features that the insiders build³ had their impatient, bleeding-edge hands on (before we all forget what 1.59 brought before the upcoming August 2021 release).

Share view state

VSCode users are often bouncing around different files in their workspaces. By default, if you close out a file tab, VSCode doesn't track where you were in that file. This can be annoying if you didn't mean to close out the file, or because you were playing whack a mole with the new new workspace trust popups.

Say hello to shared view states across editor groups⁴. Editor groups are the windows of tab collections within the VSCode editor⁵ that grow whenever Split Editor/Open to the Side commands are used. These groups can remember your past so that your rampant mind doesn't need to.

Ah yes, that's right, I left off at the pig people.⁶

Terminal magic tricks

By default, a new terminal can be created with Ctrl+Tilde(~), where it pops up in the bottom as an entryway into the powerful, dark underbelly of shells. VSCode 1.59 highlights some wizardry alternatives.

Create terminals to the side

Are you one of those people who spins a monitor into portrait mode, because of some insatiable love for 90^o angles? Maybe you simply prefer tall terminals? Ctrl+Shift+P and Terminal: Create Terminal in Editor Area to the Side⁷, will be exactly what you're looking for.

Drag and drop terminals across windows

How many VSCode windows are sitting open on your desktop? Are you taking notes in one workspace, while continuing your commands in a separate VSCode window? Make your life easier, retain all your in-shell variables, and drag the active terminal from one window to another.

This can be helpful when improving the documentation in one window as active development is happening in another.

An excellent bonus: remember when typos were just typos? The worst thing that could happen was other people making fun of your lack of oxford comma's. Now, with terminal editors, your typo can shutdown your production database! Fun!

Live preview

The Live Preview extension⁸, originally released in June, has continued along. For users working in JavaScript land, Live Preview: Show Debug Preview ensures a built-in JavaScript debugger⁹.

Note that this extension has the warning:

WARNING: this is extension is still under development!

For the brave javascripters among you all, who want the beautiful reflections of instant-progress within the editor, take it for a test drive. Report any issues to the microsoft/vscode-livepreview repo.

Other notables

General tip: Wondering what shortcuts are configured in VSCode? One shortcut to rule them all: Ctrl+K Ctrl+S

Or Ctrl+Shift+P -> Preferences: Open Keyboard Shortcuts

If you're using an M1 Mac, you should get the latest VSCode 1.59.1¹⁰ point release, as it addresses a bug where VSCode may crash.
A preview feature¹¹ has been added for automatic language detection in unsaved/untitled files. experimentalLanguageDetection¹² (search against settings via Ctrl+Comma) can be set to true, which uses an ML model from yoeo/Guesslang¹³ with the open-source ML library Tensorflow.js¹⁴. VSCode is planning for this feature to be true by default in the future, so that code is recognized out-of-box, instead of always relying on the file extension or force Change Language Mode (Ctrl+K M).

Enjoy the blog? Subscribe to our newsletter!

Newsletters not your thing? You can also follow us elsewhere on the interwebs:

Interested in creating your own knowledge base using markdown, git, and VSCode? Get started with Dendron today.

Checkout VSCodium, for the truly MIT-licensed version of the VSCode IDE (with telemetry/tracking disabled). ↩
VSCode release notes for 1.59, along with release notes for previous monthly releases. ↩
The VSCode Insiders Build allows users to get VSCode with new features as soon as they are available, rather than at the monthly cadence. ↩
Read about Shared View State Across Editor Groups in the release notes. ↩
Read about Editor Groups in the VSCode docs. ↩
The House on the Borderland, by William Hope Hodgson, is a freely available novel via Project Gutenberg. ↩
workbench.action.createTerminalEditorSide provides this functionality, and is an alternative that can be entered after Ctrl+Shift+P. ↩
Live Preview is developed by Microsoft, and can be installed via Ctrl+P and ext install ms-vscode.live-server. ↩
For more information, see latest highlights around Live Preview. Observe the animated bunny stuck waving in an infinite loop, trapped in a simulation. More in-depth information (on the extension, not the bunny) can be found directly within the extension release notes. ↩
See all issues addressed in VSCode 1.59.1 on GitHub. For the macOS bug fix, see Perma-hang/crash on M1 MBP with universal build. ↩
Normally, release notes include this snippet about preview features and what they are: "Preview features are not ready for release but are functional enough to use. We welcome your early feedback while they are under development." ↩
Read about Automatic Language Detection of Untitled Files in the release notes. ↩
Guesslang, by GitHub user yoeo, is an MIT-licensed ML model and Python package that can help detect the programming language of source code. It's been trained on over a million source code files. ↩
Tensorflow.js makes development and useage of ML available within the browser or Node.js. For more about Tensorflow, checkout the Why TensorFlow page. ↩