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.
[
{
"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 |
††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 |
External Web Links
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
- List Item 1
Second Line of Item 1 - List Item 2
- List Item 2a
- List Item 2b
- 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:
Math Formulas Block
|math:LaTeX:
$$
\f{x} = 3
$$
|
Result
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
}
]
}