Some of what TheBrain stores has no equivalent anywhere in Markdown — line alignment, a generated table of contents, and the styling of a table (shown under Tables below). These ride in HTML comments, which every Markdown application preserves and none displays. Editing a note elsewhere leaves them intact, and TheBrain reads them back.
They all take one shape — <!--tb:KIND key:value;key:value--> — a kind, then a list of properties. That list is not merely shaped like a CSS style attribute; it is one, so you can hand it to whatever CSS declaration parser your language already has. A value is a bare token run, or a quoted string when it needs to hold a ;, a " or a space, and a backslash escapes the character after it. Kinds and property names you do not recognize can be ignored. The table-of-contents markers below are the one exception, because they are the ones the markdown-toc tool already uses.
Two details are worth knowing if you write a parser. A hyphen that follows another hyphen is written \-, because an HTML comment ends at the first --> and that happens before anything reads the CSS — the escape is itself valid CSS, so nothing is lost. And property names avoid any CSS property that means something else: table column widths are col-widths, never column-width, which in CSS is the width of a column of text in a multi-column layout. Where a name does match CSS, so does its meaning — background-color is a color, and colors are written the way CSS writes them.
Why comments and not HTML? Everywhere else on this page, what Markdown cannot express is written as HTML — <u>, <sup>, a styled <span> — because those tags render in other applications, so using them costs nothing and gains you the formatting wherever the note goes. These three cannot be written that way without giving something up. Wrapping a paragraph in a <div style="text-align:center"> would stop the Markdown inside it from being read as Markdown at all — bold, links and lists within the wrapper would go back to being literal text — and it would not even center anything on GitHub, which strips style attributes. Writing every styled table as an HTML <table> would show its colors, but at the cost of the pipe table, which is the form you can actually read and edit by hand in another editor.
A comment gives up neither. It is invisible in every Markdown application, so nothing appears that should not, and it is preserved by every one of them, so nothing is lost when the note travels and comes back. What it costs is that other applications do not act on it: a centered line shows up left-aligned elsewhere, and a table’s colors and column widths are TheBrain’s alone. That is the trade — the formatting is dormant rather than destroyed.
<!--tb:block align:center-->
Centered
Centered
The comment goes on its own line before the line it aligns, and applies to that line alone. center, right and justify are written; left alignment is the default and writes nothing. Other applications show the text unaligned.
<!-- toc -->
- [Installation](#installation)
- [Options](#options)
<!-- tocstop -->
A table of contents is written out as a real list of links between these two markers, regenerated from the note’s headings each time it is saved. The markers are the ones the widely used markdown-toc tool uses, so other tooling recognizes the block.
