Skip to content

bitmark Text

Introduction

bitmark Text defines the bitmark markup language and its representation in bitmark JSON. bitmark Text is a simple way to describe the semantics of a text.

Important change with bitmark 3.0

With bitmark 3.0, there was a shift from mixing JSON with text markup to a strict JSON representation including text.

Semantics of text includes semantic styling. However, as you already might be aware of, bitmark does not include any layout information like font family and size, decorative or background colors, ... .

So, what exactly is "semantic styling"?

Let's start with an example. If styling infromation is part of the instruction of a quiz, such as "Mark verbs with blue, nouns with red." or "Translate all words in bold", then this is semnatic information.

Please never misuse sematic styling to apply your (corporate) design to bitmark content.

bitmark JSON String and Text

There are two "classes" in bitmark JSON.

bString JSON

The JSON representation of a bitmark String is called bString.

bString consists of an array of objects of type "text". Each of the objects represents a part of the string and its styling.

Simple example with just plain text.

The following bitmark markup...

    I ❤️ bitmark.
... translates to the following bString JSON.

    [
      {
        "text": "I ❤️ bitmark.",
        "type": "text"
      }
    ]

The following bitmark markup includdes bold text ...

    I ❤️ **bitmark.**

... and translates to the following bString JSON.

    [
      {
        "text": "I ❤️ ",
        "type": "text"
      },
      {
        "text": "bitmark.",
        "marks": [
          {
            "type": "bold"
          }
        ],
        "type": "text"
      }
    ]

bText JSON

bText introduces blocks like paragraphs, images, bullet lists, ... A paragraph block contains a bString as its content property.

Simple example with plain text.

    I ❤️ bitmark.
    [
        {
            "type": "paragraph",
            "content": [        // bString
                {
                    "text": "I ❤️ bitmark.",
                    "type": "text"
                }
            ]
        }
    ]

Three Feature Levels

bitmark Text supports for three sets of features.

These sets are defined due to the different formatting neededs of certain content/users/devices.

The most simple feature set is called text. This means, all text in a certain bit is just plain text. There is no styling information at all. This allows bitmark to be used on almost any device and makes it accessible even for very low bandwidth applications.

However, fully qualified URLs (URLs starting https://, http:// or mailto: ) will be recognized and represented in JSON.

The basic feature set is called bitmark--. It only contains a few tags for the most basic formatting needs like italic, bold, highlight and links.

The highest level of features are defined by bitmark++. bitmark++ adds more tags including image tags. bitmark++ is only available in the body of a bit. Never inside any other tags or properties.

Hint

Let me give you a simple example of why we need these layers: A title cannot contain videos or bullet lists. Therefore, titles are defined to contain at most bitmark--.

Character Set UTF-8

bitmark is based on UTF-8 character encoding.

Therefore, all UTF-8 characters are supported. This includes the non-breaking space (option-space bar) and emojis like 😀, 👻 or 👍🏾.

Line Breaks and White Spaces

Line breaks are allowed anywhere, including inside most tags, and must be preserved when displayed by a client.

The bitmark parser does trim white spaces (including line breaks) from the start and end of the value of a tag or attribute. All white spaces within a text are preserved.

Hint

This might be evident and sound trivial to you, but it is not for developers coming from the html world.

"Breakscaping" (Escaping)

See "Breakscaping" (Escaping) in the bitmark overview chapter on how to escape tags.

bitmark--

bitmark--, called "bitmark minimal" or "bitmark minus minus" is an extrem minimalist set of inline text tags.

bitmark-- is the default for all bits if no other text format is declared. bitmark-- must not be declared explicitly in the bit-type tag to be used within a bit.

Inline Tags

Inline tags are marked with two identical, surrounding (special) charaters.
Example:

This is a **bold** text

Result: This is a bold text

Example of a cloze bit with an implict declaration of bitmark-- text format:

[.cloze]
This is a [_gap][?This hint is **important** (and therefore bold)].

Example of a cloze bit with an explicit declaration of bitmark-- text format:

[.cloze:bitmark--]
This is a [_gap][?This hint is **important** (and therefore bold)].

Example of a cloze bit with an explicit declaration of plain text as format (no formating possible):

[.cloze:text]
This is a [_gap][?This hint is important].

Light, Italic and Bold

Text Semantics                      Description
``light`` light
__italic__ italic
**bold** bold

Unlike in other markup languages, spaces before the first or after the last word don't break these marks. ** This is a bold text **

The opposite is the case. The first space after the opening tag and the space before the closing tag are considered an optional part of the tag. **bold** and ** bold ** produces the same output.

Hint

More than of the mark characters in a row, are considered plain text. Please have a look at the following cheat sheet for how to solve some typical situations.

Cheat Sheet                      bitmark--  
One bold asterisk ** * **  
Two bold asterisks ** *^* ** (see breakscaping)
Two plain asterisks *^* (see breakscaping)
Three plain asterisks ***  
Four plain asterisks ****  
Five plain asterisks *****  
Three bold aterisks ** *** **  
One highlighted space !! !! (three sapces) bitmark++ tag

Hint

Combined use like **__...__** might not work as you expect. The outer tag always wins, the inner one is ignored. By design bitmark-- does not support nesting of tags. So how do you bold and italicise a text? You just don't in bitmark! It's bad practice to do it and we don't support bad practice.

bitmark-- is allowed almost everywhere. Inside most bitmark tags. Very few tags do not allow for bitmark--. It's very intuitive where formatting makes sense or not. An example, where only plain text is allowed, is the solution of gap in a cloze quiz.

bitmark Variables

bitmark supports variables. This works as follows:

Mark a specific text and link it to a variable name. If the variable is set, the marked text is replaced by the new value of the variable. If the variable is not set, the marked text is displayed (default).

[.article]

This is a text about the value added tax (VAT).
VAT is currently at ==7.6%==|var:VAT rate| in Switzerland.

bitmark++

bitmark++ is called "bitmark plus plus". bitmark++ includes everything from bitmark-- and adds support for many additional inline tags, like critic, links, source code and many more and embedding of other text formats like LaTeX to support math formulas. It also adds support for block tags like titles, lists and images.

As bitmark-- tags are so basic and can be used almost everywhere, they can also be used within bitmark++ tags like titles, highlighted text, bullet lists, ...

Titles

bitmark++ supports for titles.

Text Semantics                       Description
# Headline Headline (comparable with <h1>)
## Title Title (comparable with <h2>)
### Subtitle Subtitle (comparable with <h3>)

The space after the # is mandatory

Headlines are really bold. So artciles often don't use it and start with a title (h2) instead.

Highlighted

Text Semantics                       Description
!!highlighted!! highlighted

Critic

Critic inline tags are used to display text that is marked/corrected by one or several users (like the learner and his/her coach).

Text Semantics                       Description
~~deleted~~ Deleted text is commonly displayed as strikethrough.
††inserted†† Inserted text is commonly displayed as addition
==marked== Marked text is commonly displayed as marked
==marked==|red| Marked text supports colors
Supported colors: red, light red, pink, light pink, purple, light purple, blue, light blue, cyan, light cyan, green, light green, yellow, light yellow, orange, light orange, grey, light grey

Links to external web sites are supported. They are opened in a new window (within an app or in the standard browser).

https and mailto links are supported. Also, "plain" https urls are detected.

==This is a link==|https://www.apple.com/| and more.

https://www.apple.com/

Warning

Please be careful when using external links. Clicking a link usually leaves the (mobile) app and opens it in a new browser window. This might not be what the user expects. Good examples of links are links to Wikipedia or to the web site of the book publisher.

Lists

The type of the list is defined by its bullet character(s). There is a mandatory space right after the bullet for the list to be recogized as such.

Idents must be tabs (tabulator), one per level. Space are not recognized.

Bulleted List

List of type "bullet".

Example (bitmark)

• List Item 1
• List Item 2
•• List Item 2a
•• List Item 2b
• List Item 3

Result

  • List Item 1
  • List Item 2
    • List Item 2a
    • List Item 2b
  • List Item 3

Numbered List

List of type "numbered".

Example (bitmark)

1. List Item 1
Second Line of Item 1
1. List Item 2
11. List Item 2a
11. List Item 2b
1. List Item 3

Result

  1. List Item 1
    Second Line of Item 1
  2. List Item 2
    1. List Item 2a
    2. List Item 2b
  3. List Item 3

Hint

The first number defines the starting number.

Lettered List

List of type "lettered".

Example (bitmark)

A. List Item 1
A. List Item 2
A. List Item 3

Result

  • A. List Item 1
  • B. List Item 2
  • C. List Item 3

List

List of type "none".

Example (bitmark)

_ List Item 1
_ List Item 2
_ List Item 3

Result

  • List Item 1
  • List Item 2
  • List Item 3

Check List

List of type "check list".

Example (bitmark)

+ List Item 1
+ List Item 2
- List Item 3

Result

  • ☒ List Item 1
  • ☒ List Item 2
  • ☐ List Item 3

Mixed Lists

Example (bitmark)

• Check List 1
++ List Item 1a
-- List Item 1b
• Check List 2
++ List Item 2a
-- List Item 2b

Result

    * Check List 1
  • ☒ List Item 1a
  • ☐ List Item 1b
  • * Check List 2
  • ☒ List Item 2a
  • ☐ List Item 2b

Code

Inline Code

Some inline code |code:JavaScript:``` let a = 3; ```|

Result

Some inline code let a = 3;

Code is usually displayed in a mono-spaced font and with colored syntax.

Code Block

If your code starts at the beginning of a line, it is interpreted as a block of code and might contain several lines. Usually displayed in a mono-spaced font and with colored syntax.

|code:JavaScript:

// And a code block

let a = 3;
let b = 4;

|

Math Formulas (LaTeX)

Inline Math Formulas

Formula: |math:LaTeX: $$\f{x} = 3$$ |

Result

Formula: f(x)=3\f{x} = 3

Math Formulas Block

|math:LaTeX:

$$
\f{x} = 3
$$

|

Result

f(x)=3\f{x} = 3

Images (and other Media)

bitmark++ supports images. Images are block elements.

Please use images in bitmark++ wisely. If it makes sense to share, send or save an image alone (independent of the surrounding text), please consoider using a full bit instead.

This is exactly why the bitmark++ text format does not support other media such as audio or video. Please use full bits to add all types of media to a bitmark document.

Images support optional width and height attributes.

|image:https://cdn.bitmark.cloud/images/cat3_big.jpg|
|image:https://cdn.bitmark.cloud/images/cat3_big.jpg|width:640|
|image:https://cdn.bitmark.cloud/images/cat3_small.jpg|width:64|height:40|

bitmark Text JSON Format

bitmark uses the |ProseMirror JSON format. This is a well-designed format for representing styled text as JSON. Its extensibility, flexibility and direct support from one of the most mature editors (including its derivatives like TipTap) were the reason to adapt this format rather than develop another one. In addition, its support for collaboration and the ability to easily convert it to many other JSON formats made it an easy choice.

bitmark-- simplifications

bitmark-- has a very small feature set, but it is sufficient for most content-first quizzes we know today. Simple text is often not enough, but more sophisticated formatting is even more often not required.

Therefore, the |ProseMirror JSON format seems like too much of a good thing for such a small feature set.

However, with a few limitations, it is still very useful and not complicated to use. Please expect one, but only one "paragraph" and zero or one element in the "marks" field.

With these limitations, the format is super easy to master.

And the advantage of being compatible with bitmark++ and the |ProseMirror eco system far outweighs it.

bitmark-- Example

There are some **bold** words.
{
   "type": "doc",           // bitmark--
   "content": [             // exactly one paragraph
      {
         "type": "paragraph",
         "content": [
            {
               "text": "There are some ",
               "type": "text"
            },
            {
               "marks": [   // zero or one mark
                  {
                     "type": "bold"
                  }
               ],
               "text": "bold",
               "type": "text"
            },
            {
               "text": " words.",
               "type": "text"
            }
         ],
         "attrs": {}        // paragraph attributes can be ignored
      }
   ]
}