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.
---
type: https://taskfolders.com/docs/markdown/v1
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
todo:
- 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.
Comments and Topics
:warning: feature draft
# Some section
%% TARGET new users
has a bad taste for people
%% TODO
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
Supercharged links
The standard markdown link looks like this:
Some [extra](./extra.md) 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
[[502d618f-5967-4f86-8251-2e54a7df1708]]
[[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 :
[[:tf-extra]]
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