TapirMD (Tapir's Markdown) Format Specification

Terminologies, Rules and Semantics

Character and character sequences

• A character sequence consisting of
  • An ASCII Carriage Return character (Unicode: U+000D), followed by
  • An ASCII Line Feed character (Unicode: U+000A).
• A single ASCII Line Feed character that doesn't follow an ASCII Carriage Return character.
• The end of the document if it doesn't end with either of the above two cases.

• An ASCII Space character (Unicode: U+0020), or
• An ASCII Horizontal Tab character (Unicode: U+0009).

• The ASCII DEL character (Unicode: U+007F).
• Any ASCII character with a Unicode value in the inclusive range U+0000 to U+0020.

• it contains at least one whitespace character.
• it ends with a line end.
  Perceivable blank character sequences of this case are specifically called line-end blank character sequences.

Blocks, lines, and tokens

• Specifically, if the sequence of blank characters is perceivable, the corresponding blank token is called a perceivable blank token.
• More specifically, if the sequence of blank characters ends with a line-end blank character sequence, the corresponding blank token is called a line-end blank token.

• Always ends with a line-end blank token.
• May begin with an optional blank token.
• Never contains consecutive blank tokens. If consecutive blank tokens do exist within a line, they are merged into a single blank token.

Overview of block types

1. atom blocks, including
   • blank blocks
   • usual blocks
   • header blocks
   • seperator blocks
   • attribute blocks
   • code blocks
   • custom (data) blocks
   Atom blocks are the most basic block type and cannot contain other blocks. They can't nest other blocks and they can be directly nested within both base blocks and predefined container blocks (with an exception that blank blocks can't be directly nested in non-item predefined container blocks).

2. predefined container blocks
   • (list) item blocks
   • table blocks
   • quotation blocks
   • notice blocks
   • reveal blocks
   • plain blocks
   Except item blocks, predefined container blocks can only directly nest base or non-blank atom blocks and must be directly nested within a base block.
   Item blocks can directly nest base, any atom, and other item blocks. More details of item blocks will be described below.

3. base (container) blocks, including
   • explicit base blocks
   • doc blocks
   Base blocks have a dual role, functioning as both atom blocks and container blocks. They can directly nest any block type. They can be directly nested within predefined container blocks and other base blocks.
   The root block of a TapirMD document is always a doc block. TapirMD might support document nesting later so that doc blocks may be also nested.
   Explicit base blocks are bounded by explicit open and close lines, while doc blocks encompass all document lines.

• item predefined container blocks can directly nest not only atom and base blocks, but also item predefined container blocks at higher levels.
• first-level item predefined container blocks must be directly nested within their parent base block.
• non-first-level item predefined container blocks must be directly nested within another item built-in block at a lower level.

Data lines and syntaxable lines

Blank blocks

Start and end of non-item predefined container blocks

• an opitional blank token followed by
• a predefined-container-leading mark token which
  • begins with a one-character mark and
    • ends with a perceivable blank character sequence or
    • is followed by a line-end blank token.

• # for table blocks,
• > for quotation blocks,
• ! for notice blocks,
• ? for reveal blocks,
• . for plain blocks.

• before a blank block, or
• before a following predefined container block (of either item type or not), or
• before its parent base block explicitly closes, or
• at the end of the containing document.

Start and end of item predefined container blocks

• an opitional blank token followed by
• a one-character or two-character item predefined-container-leading mark token which
  • ends with a perceivable blank character sequence, or
  • is followed by a line-end blank token.

• *, +, -, ~ for unordered lists, and
• *., +., -., ~. for ordered lists, and
• :, :. for definition lists.

• if it is found that its leading mark is the same as the mark of an opening list in its parent base block, then the item block is viewed as an item in the opening list. And the item block is viewed as the sibling block of the seen last item block in the opening list.
  If the opening list is nesting inside higher-level lists, then all of those higher-level lists close.
  If the previous block of the item block is a blank block, then the blank block will be viewed as a direct child of the seen last item block in the opening list.
  The item block now is treated as the seen last item block in the opening list.

• if its leading mark is different from any marks of the opening lists within the parent base block, then a new list with a higher level opens and the item block is treated as the first and the seen last item block in the new opening list.
  If the new opening list is the only opening list tracked by the parser within the parent base block, then the list is called a first-level list. The item blocks of a first-level list are all direct children of the parent base block.

• before a blank block followed by a non-item block, or
• before a non-item predefined container block, or
• before the parent base block explicitly closes, or
• at the end of the containing document.

About child blocks of base and predefined container blocks

• If the remaining part of the start line of a predefined container block after the leading mark token has characteristics of base block open line or atom block start line, then a base block or atom block opens or starts at the same line with the predefined container block.
• Otherwise, a usual block starts at the same line with the predefined container block, even if the start line of the usual block contains nothing.

• if the last block is a blank block, then the atom block or base block, alongside with that blank block, is treated as the direct child of the parent base block.
• if the last block is a non-blank atom block, then the atom block or base block shares the same parent block (either a base block or a predefined container block) with that non-blank atom block.
• if the last block is a predefined container block and no children have been detected for the predefined container, then the atom block or base block is treated as the (first) direct child of the predefined container block.
• similarly, if the last block is an opening base block and no children have been detected for the opening base block, then the atom block or base block is treated as the (first) direct child of the opening base block.

Start and end of explciit base blocks

• opens at a syntaxable line beginning with a base-open-leading mark token, which is a character sequence containing one or more consecutive { characters.
• closes at
  • a syntaxable line beginning with one or more consecutive } characters (a base-close-leading mark token), or
  • at the end of the containing document.

//
<< >> >< <>
^^
..N:M ..N :M

• // means the explciit base block is commented out and will not be rendered in HTML output. However, the internal of the explciit base block will still be parsed.
• << >> >< <> are four text horizontal alignment tokens. At most one of them can present.
  • << means left-aligned,
  • >> means right-aligned,
  • >< means center-aligned,
  • <> means justify-aligned.
  The text alignment tokens define the text align of the explciit base block.
• ^^ is a text vertical alignment token. It is only meaningful when the explciit base block is used as a table cell. It means the table cell is top aligned in vertical. By default, table cells are middle aligned in vertical.
• ..N:M ..N :M are three table cell span count tokens. At most one of them can present. They are only meaningful when the explciit base block is used as a table cell. N and M denote positive integers.
  • ..N means N cells span along the major axis of the innermost containing table.
  • :M means M cells span along the minor axis of the innermost containing table.

Attribute blocks

• begins with three or more consecutive @ characters
• and ends with an optional blank character sequence.

#id
.class1;class2

• #id specifies a block ID (id can be any valid HTML4 ID identifier).
• .class1;class2 specifies some classes (class1 and class2 can any valid HTML4 class name identifers).

Usual blocks

• begins with three or more consecutive ; characters
• and ends with an optional blank character sequence. A new usual block will always start at such a line. If the usual block leading mark token is followed by a line-end blank token, then the line is rendered as a blank block in HTML output.

• if it has a previous line and the previous line is also a usual line or a header line (see the following sections), then the two lines belong to the same atom block (which might be a usual or header block).
• otherwise, a new usual block starts at the usual line.

Header blocks

• one or more consecutive = characters, a second-level header block starts at the header line, or
• one or more consecutive + characters, a three-level header block starts at the header line, or
• one or more consecutive - characters, a fourth-level header block starts at the header line, or
• zero or more consecutive # characters, a first-level header block starts at the header line.

• begins with such a leading character sequences containing #=+- characters,
• and ends with an optional blank character sequence.

Style and controlling marks

• text styling, including
  • bold and dimmed
  • italic and revert-italic
  • underline and dotted underline
  • strikethrough and text hiding
  • smaller and larger font size
  • subscript and superscript
  • text marking
  • code spans and mono-font spans
• hyperlinks
• media embedding
• line comments
• line breaks
• line-end spacing (whether or not generate a space character between two neighbor lines)
• (mark) character escaping

line-leading mark tokens

• begin with exact two identical characters
• and end with a perceivable blank token.

even-backtick mark tokens

• An even-backtick mark token in primary mode and with exact one pair of backticks is treated as a void character and rendered as nothing in HTML output.
• An even-backtick mark token in primary mode and with more than one pair of backticks is treated as a non-collapsable space sequence. The number of non-collapsable spaces in the sequence is the pair count minus one.
• An even-backtick mark token in secondary mode is treated as backtick character sequence, with the number of backticks in the sequence equal to the pair count.

style mark tokens

• A sequence of backticks with an even number of characters will be interpreted as an even-backtick mark token.
• A sequence of backticks with an odd number of characters will be interpreted as an even-backtick mark token followed by a code span mark token.

links, link definitions and footnotes

• If the hyperlink span contains only one content token, that token is used as the link text.
• If the hyperlink span contains multiple content tokens, all tokens except the last one are used as the link text.

• If the last content token of a hyperlink span is a valid URL (see below), it is used as the hyperlink's URL. We call the hyperlink self-defined.
• Otherwise, a matching link definition will be searched to provide the URL (the matching rules are described below).
  • If a match is found, the last content token of the matching link definition is checked.
    • If it's a valid URL (see below), that URL is used as the hyperlink's URL.
    • If not, the last token is treated as a URL generation argument, which is passed to custom user callbacks to generate a URL.
      • If the URL is successfully generated, it is used as the hyperlink's URL.
      • Otherwise, the hyperlink is marked as broken.
  • If no matching definitions are found, the last content token in the hyperlink span is treated as a URL generation argument and passed to user callbacks to generate a URL.
    • If successful, the generated URL is usedas the hyperlink's URL.
    • Otherwise, the hyperlink is marked as broken.

• for the ones following the hyperlink span, earlier ones have priority over later ones.
• for the ones before the hyperlink span, later ones have priority over earlier ones.

• All content tokens of a hyperlink span are combined into a single matching text, with all blank characters removed.
• All content tokens of a link definition, except the last one, are combined into a single matching text, with all blank characters removed.

• If the matching text of a link definition consists solely of three dots (...), the definition matches all hyperlink spans.
• If the matching text ends with three dots, prefix matching is performed.
• If the matching text begins with three dots, suffix matching is performed.
• Otherwise, exact matching is performed.

• starts with http:// (ignore case), or
• starts with https:// (ignore case), or
• ends with .htm[#fragment] (ignore case), or
• ends with .html[#fragment] (ignore case), or
• is #[fragment].

Line-end spacing rules

• The line has an opening style mark token followed by a line-end blank token.
• The line has no content tokens.
  (Note: Even-backtick mark tokens are treated as content tokens.)
• The last content token in the line ends with a blank or CJK character ^[3].
  (Note: Even-backtick mark tokens in primary mode are interpreted as CJK characters.)
• Within the block, after the line, no more content tokens are found.
• After the line and before the next content token, a media-embedding or line-break token is found.
• The next content token begins with a blank or CJK character.
  (Again, even-backtick mark tokens in primary mode are interpreted as CJK characters.)

Seperator blocks

Code blocks

• starts at a syntaxable line beginning with a code-block-leading mark token, which is a character sequence containing one or more consecutive ' (single quotation, not backtick) characters. The line is the start boundary line of the code block.
• ends at
  • a later syntaxable line (the end boundary line) beginning with a code-block-leading mark token, which contains the same number of ' characters as the corresponding code-block-leading mark token in the start boundary line, or
  • the end the document. For such case, the code block doesn't have the end boundary line.

//
language

• // means the code block is commented out and will not be rendered in HTML output.
• language means a programming language name, such as zig, c, go, etc. HTML renderers may use the language name to add class names for the code block.

<<
#id

• << just implies the streaming directtion.
• #id specifies the block to be streamed.

Custom (data) blocks

• starts at a syntaxable line beginning with a custom-block-leading mark token, which is a character sequence containing one or more consecutive " (double quotation) characters. The line is the start boundary line of the custom block.
• ends at
  • a later syntaxable line (the end boundary line) beginning with a custom-block-leading mark token, which contains the same number of " characters as the custom-block-leading mark token in the start boundary line, or
  • the end of the document. For such case, the custom block doesn't have the end boundary line.

//
app

• // means the custom block is commented out and will not be rendered in HTML output.
• app means aa application name, An application might be
  • a built-in application, or
  • a user plugin.

List semantics

• if the first non-attribute child block of the item block is a first-level header block, then the header block is treated as the definition title, and the other children are treated as the definition body.
• otherwise, the definition title is viewed as missing and all the children are treated as the definition body.

    A definition list with the `:` mark:
    : ### Term 1
      ;;; Descriptions of term 1.
    : ### Term 2
      ;;; Descriptions of term 2.
    
    A definition list with the `:.` mark:
    :. ### Term 1
      ;;; Descriptions of term 1.
    :. ### Term 2
      ;;; Descriptions of term 2.
    
    @@@
    : This is an indented block.
      It is actually a definition item block without title.

    Languages
    * Zig
      - __https://ziglang.org
        ~ Doc: __https://ziglang.org/documentation
        ~ Downloads: __https://ziglang.org/download/
      - __https://github.com/ziglang/zig
      - __https://ziggit.dev/
    * Go
      + __https://go.dev
      + __https://github.com/golang/go

    *. ☐ finish the lib implementation
      +. ☑ inline styles
      +. ☑ block hierarchy
      +. ☐ wasm
        -. Go lib (using wasm)
        -. JS lib (using wasm)
    *. ☐ write tests
    *. ☑ write specification

    * ### Zig
      - __https://ziglang.org
        ~. ### Doc
           ;;; __https://ziglang.org/documentation
        ~. ### Downloads
           ;;; __https://ziglang.org/download/
      - __https://github.com/ziglang/zig
      - __https://ziggit.dev/
    * ### Go
      + __https://go.dev
      + __https://github.com/golang/go

Table semantics

    # ### Language
      ### Simplicity
      ### Readability
      ### Powerful
      ----------
      ;;; Markdown
      ;;; Very simple
      {>< :2
      Good
      }
      ;;; No
      ----------
      ;;; TapirMD
      ;;; Reasonably simple
      {>< :2
      Yes
      }
      ----------
      ;;; AsciiDoc
      ;;; Not very simple
      ;;; Not very good

    # 
      ### Language
      ### Simplicity
      ### Readability
      ### Powerful
      ----------
      ;;; Markdown
      ;;; Very simple
      {>< :2
      Good
      }
      ;;; No
      ----------
      ;;; TapirMD
      ;;; Reasonably simple
      {>< :2
      Yes
      }
      ----------
      ;;; AsciiDoc
      ;;; Not very simple
      ;;; Not very good

Quotation block semantics

    > "Success is not final, failure is not fatal: It is the courage to continue that counts."
      {
      ;;; -- Winston Churchill
      @@@
      }
      {
      > "It is never too late to be what you might have been."
        ;;; George Eliot
        @@@
      }

    > ### The best way to predict the future is to invent it.

Notice block semantics

    ! WARNING: The specification is not yet stable.

    ! ### WARNING!
      ;;; The specification is not yet stable.

Reveal block semantics

    ? {
      * Zig
      * C/C++
      * Go
      }

    ? ### Why TapirMD?
      {
      
      The main purpose of TapirMD is to intvent a powerful markup language
      which is both readable and easily extensible.

      I believe TapirMD will boost my technical writing productivity.
      }

Plain block semantics

      const std = @import("std");

      pub fn main() void {
          std.debug.print("Zig is fast as lighting.\n", .{});
      }

    . ### main.zig
      '''zig
      const std = @import("std");

      pub fn main() void {
          std.debug.print("Zig is fast as lighting.\n", .{});
      }
      '''

    A bare plain block is placed between the two lists to
    avoid them being interpreted as a single, continuous list.

    *. foo
    
    *. bar

    . // terminate the above list

    *. 123

    *. xyz

Reserved marks

=
|
@
$
%
^
<
&
_ (underscore)
; 
,

===
+++
[[[
]]]
(((
)))

,,
^^
<<
>>
@@
((
))
[[
]]

Footnotes

1. Markdown is known for its limited capabilities and lack of strict specification.
   ↩︎
2. Without relying on interactive UI elements, a TapirMD document can easily be converted to multiple formats beyond HTML, including EPUB and others.
   ↩︎
3. CJK is a short form standing for Chinese, Japanese, and Korean.
   ↩︎