# 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](https://docs.bitmark-association.org/concepts/parser.md)
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.

```bitmark
[.h]
[#Rated values]

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

The basic structure of a bit:

```bitmark
[.bitType]
[@id:123]

[%item][%lead]

[!instruction]

Body
```

[Important terms and definitions](https://docs.bitmark-association.org/concepts/terms.md) 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 `]`:

```bitmark
[&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:

```bitmark
[.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:

```bitmark
[.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:

```bitmark
[.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:

```bitmark
[.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:

```bitmark
[_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:

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