The basics

What is bitmark?

bitmark represents content as bits: typed, addressable pieces that people and machines read the same way. A paragraph, a heading, a normative provision, a definition, a figure or a quiz is each a bit of its own type, with its own ID.

bitmark is an umbrella term for two equal forms of the same content: the bitmark markup, which people write and read, and the bitmark JSON data model, which programs exchange. The parser converts one into the other without loss.

bitmark is strictly content-first: one source serves apps, the web, print, screen readers and AI alike. A bit contains no visual information. How a bit looks is decided by the app that shows it, through its theme; the bit only says what the content is.

Using bitmark

Every piece of content starts with its bit type, on a line of its own, in square brackets and beginning with a period: [.p] for a paragraph, [.h] for a heading, [.article] for a longer text, [.chapter] for a chapter.

[.h]
[#Rated values]

[.p]
The rated values are given in the table below.

The basic structure of a bit:

[.bitType]
[@id:123]

[%item][%lead]

[!instruction]

Body

Important terms and definitions explains each part.

Bit design

The design of a bit is given by its theme, never by the markup:

• The theme decides how a bit looks; the bit cannot change it.
• This keeps every bit of a kind consistent across all content.
• A theme can apply to a whole book or to a single bit.

Bit structure

Tags

All bitmark tags start with [ and end with ]:

[&image:https://example.org/images/background.png]

The first character after the opening square bracket is a reserved character that defines the role and the format of the tag (. bit type, @ property, % item/lead, ! instruction, ? hint, & resource, # title, _ gap, …).

A property tag sets a property of the bit by name; the reference lists which properties each bit type accepts:

[.p]
[@lang: de ]
Das ist ein Beispieltext.

Every bit carries a unique ID (the [@id:…] property), assigned by the platform. It identifies the bit and is crucial for referencing and rights management — never change it. A bit can also keep the ID it has in the customer's own system, beside the platform's.

Footer

Nearly all bit types can have a footer. The content of the footer is always shown at the bottom of the bit. To add a footer, insert a ==== footer ==== divider after the body of the bit:

[.article]
The protective device disconnects the supply within 0.4 seconds.
==== footer ====
Source: the product's data sheet

Chains

Chains are a fundamental concept of bitmark. All bitmark tags that are "glued" together (not separated by a space character) belong to the same object.

One gap with two accepted solutions — the two tags are chained:

[.cloze]
The students completed the [_cloze][_gap text] with the correct verb forms.

Two separate gaps — the tags are not chained, because they are separated by a space character:

[.cloze]
The students completed the [_cloze] [_with] the correct verb forms.

Property (@) tags are fully supported in chains: a chained @ tag relates to the tag it is chained to, not to the whole bit. The same holds for hints:

[_gap][?This is a hint to solve this gap and not a hint for the whole quiz][@example]

Escaping

bitmark has one special character: the caret ^. Put it right after the first character of a tag and the tag becomes plain text; two carets stand for one:

[.p]
Write [^.p] at the start of a paragraph bit, and ^^ for a single caret.