The TaskFolders Syntax


Resisting the creation of a new Markdown standard can be surprisingly daunting. There are so many tools that rely on existing Markdown formatting, and I wouldn’t want to risk breaking them.

What could possibly be missing that would justify messing things up a little bit? Are there quality-of-life syntax extensions that could improve my experience as a markdown user?

Implicit frontmatter

Any good programmer worth his grain of salt will try to master the art of laziness. So typing those 3 dashes for the frontmatter… and 2 times on top! is quite painful. Is it so evil if we were to introduce implicit frontmatter?

tags: deadline
before: 2w

something must be done soon

This should not be a biggie because the scanner will take care of sanitizing the file to the good boys markdown.

uid: c62ee550-32d4-42e0-9c6f-426dc630c518
tags: deadline
before: 2022-02-18

something must be done soon

Heading frontmatter

Here I start my note

# first section
sid: first-sec
uid: 52aa14c0-741f-41b0-bdb1-0a10bcd3015c
  - add more content

On my first section

# more stuff

I am not sure why, but I have never seen any extension considering frontmatter in markdown headings as an incredible value proposition. A normal or implicit frontmatter block after a heading without an empty line will be treated as meta data.

The sids and uids can be used to reference exactly one section of your markdown. HTML has anchor tags and some parsers will auto generate them for each heading. However now I can relocate that section to another file and no link to it will break.

Ad hoc outlines

When taking notes I have two modes: the Writer who types long paragraphs and the Telegrapher who outlines key sentences.

A writer focus on prose in paragraph form

Why do we believe markdown syntactic sugar 
is important or useful? 

One could get everything done using HTML tags, 
but if enjoying experience typing notes, then 
syntax sugar is a must have.

The telegrapher breaks down a chain of thoughts into key ideas while trying to be less verbose

WHY md syntactic sugar important
  one thing is getting the job done
    for that you can use html tags
    avoid stack complexity
  other is enjoying typing notes
    for that syntax-sugar is a must

This is closer to a mind dump. One worries less about how the reading experience flows and starts shooting out bullet precise thoughts. They are way easier to edit and move around to shape the message.

  • Sudden ideas can be captured quickly
  • Tasks can highlight priorities and structure
  • Boost your learning process breaking down concepts

Did the all uppercase WHY catch your attention? That is the outline topic label, a keyword to describe the intention of the block.

Sadly most markdown parsers ignore indented lines like these and merge them into a nasty single paragraph blob. You will need a special conversion step to render them nicely in HTML.

Image layout hints

It is well known that there is a already a syntax to add images. Getting the alignment right is a whole other story. Nowadays in most of my posts I just center the image since it is the safest way to not break my layout. Centering every image by default is taking things too far, so one easier method is still needed. Thats where this great StackOverflow answer came to the rescue, it is our default in our styling.

![to the right >](./image.png)
![to the left <](./image.png)
![center ><](./image.png)

Comments and Topics

:warning: feature draft

# Some section

%% TARGET new users

has a bad taste for people

  use some less offensive term
  add extra content

Basically a comment is any line starting with a %% and it will extend until the first non indented line. Whenever a comment (or heading) starts with all uppercase letters, we call that label the topic. Some well known topics have special meaning and consequences

  • TODO will show up in the pending tasks list
  • LOG Is considered an event, the parser will add a timestamp and show up as part of the folder logs.

There are hacks around comments, but I still find reasons for a new syntax.

  • It makes clear that they are never to be part of your published content by accident.
  • These are nicer to type
  • Reserved topic labels can re-purpose what can be done with the comment

The standard markdown link looks like this:

Some [extra](./ content

It is not much extra typing, but if the link and target are the same word, it is a little bit verbose. Usually wiki links are a good solution.

Some [[extra]] content

Popular markdown apps supercharge these to reach other paths that are not so easy to find. We could not be an exception and support links using uids

[[768b98ef-7640-44db-9058-7fdd65449579 Some description]]

Or a [long and windy](30f118cf-6584-4435-adbb-3fd87eb55341) link

There are also user defined ids we call sids and mark with a single :


Or a [short and nice ](:tf-extra) link

And finally we have our experimental tagged links marked with a double ::

Are you ready? Then [get started](::get-started)!

These are a bit more technical. While uids and sids are translated into full local paths thanks to the scanner, tagged links need a developer to give a table of link tags to translate them into final urls.

When writing this documentation I do have have a getting started page, but I want to make sure the link is not broken. The previous example will be converted to:

Are you ready? Then [get started](/docs/introduction/getting-started)!

Headings level dilemma

Technically speaking, a single <h1> is the most semantically correct approach. Whenever the headings in my site seem off I am constantly reminded that one extra sharp symbol is missing.

# My Title
## section one
## section two

I find this a bit annoying, specially when I write the title in the frontmatter to avoid magic parsing tricks when dealing with a list of markdown files.

Simple notes, specially those you tend to read more often in markdown than HTML, can look like this:

title: My Optional Title

# section one
# section two

The preprocessor default is to detect if multiple level 1 headings are used. In this case all headings will be increased one level more.

From my perspective this is more semantically explicit and prevents some formatting conflicts.

Standard Markdown Preprocessor

Given all the existing Markdown variants, parsing libraries and different programming languages implementing them, we do not want to hijack the user into a single HTML rendering engine.

Instead the SDK can transform this syntax into standard markdown. Headings frontmatter and comments will be dropped, links translated into their final version, and HTML blocks added where there is not an official solution in standard markdown.

Currently we are even considering translating common syntax extensions like emojis or highlight marks to avoid adding extensions to the final parser you decide to use.

Dive Deeper

  • The official Markdown guide has a page about hacks to work around missing features