Scanning

One core philosophy of TaskFolders is avoiding a centralized data store. There is no central project file or database. All information is stored and managed locally along the files the user is working with.

A markdown note already has a data section, the frontmatter. Sometimes a feature needs to store complex data that might seem too noisy for the frontmatter. It could be like time tracking, statistics, comments… In these cases we use a _data folder where the file exists.

It might look like a very rough way to manage data, but this makes your work extremely future proof.

Databases are still convenient because they offer fast access and data integrity. We try to circumvent this with a regular scanning task that explores all paths given by the user for indexing and linting.

Indexing

When a file handled by TaskFolders is found, it will be explored for key data points like a file id, links or time markers. This will be indexed at a central location to enable enable features in other apps, like the matching an id to its file path.

We strive to make the index a convenience, not a storage location. If the app data is lost or you move just some random work folders to other computer, we wan you to have everything working together again after a scan. No need to export/import app specific data.

Linting

We want you to use any app you like with your notes. In markdown files this means you are free to touch the frontmatter, but chances are that some fields might end with an invalid format.

Whenever a file is scanned, frontmatter fields are checked for typos. Additionally some data sanitation might be done, like fixing relative time marks.

---
type: https://taskfolders.com/docs/markdown/v1
uid: f9970c33-4857-4fdf-9726-02e5aff2bd4c
before: 12w
---

Since the before field is a known field for our markdown type, the scanner will sanitize that field calculating 12 weeks since the file modification time and update the file.

Supported files

Markdown

Our first class citizen for note taking with only one minor caveat. We need to ensure the frontmatter has a reliable format, for which there is a type field

Source code

It is tempting to just reference elements from a source code project by name, but remember, naming things is one of the hardest things when building software. Chances are, that name will change, just like the path. A UUID is a quite robust way to reference code.

If you are familiar with JSDoc comments, you are already half way there.

/** Some user data
 * 
 * @uid 11e56154-96c9-49be-ad04-5207b2e186c9
 */
class UserData {
  name: string
}

Add now the Visual Studio Code extension and you will have one more way to jump from your markdown files to the source code.

Be aware that @uid is not a known tag. If you are using the eslint jsdoc plugin to check for valid tag names, you can define new ones like this:

{
  rules: {
    "jsdoc/check-tag-names": [ "error", {
        definedTags: ["uid", "sid"]
      }],
  }
}

Javascript is not the only programming language that the scanner will try to explore for tags. Other languages that it will try to explore are:

Python
Go
C++ / C
Shell scripts (Bash, Zsh)

Triggering a scan

You can trigger a scan from the cli tool

cd ~/work
tfc scan

Any markdown with frontmatter exposing a .uid or .id field that looks like an UUID will be be indexed. That is the only information taken from unknown markdown files. Markdown files with the TaskFolders type are the ones that trigger every available features.

There is a convenience option to automatically convert markdown files lacking a type field into our format, which also supports implicit frontmatter.

cd ~/work
tfc scan --convert

Now a quick note like this:

tags: demo

some simple note

Will be converted into this:

---
type: https://taskfolders.com/docs/markdown/v1
uid: f9970c33-4857-4fdf-9726-02e5aff2bd4c
tags: demo
---

some simple note