Important terms & definitions

A bit is normally structured like this:

[.bitType]
[@id:123]

[%item][%lead]

[!instruction]

Body

It consists of a bit type, an ID, an item, a lead, an instruction, the body (the actual content) and, optionally, resources.

Bit type

  • Defines the type of the bit, e.g. [.article] or [.image].
  • There are various bit types for various kinds of content — the content defines which bit type to use (text → .article, an image → .image, …).
  • Without any further definition, the bitmark-- text format is applied; for bitmark++ add :bitmark++ to the type (e.g. [.article:bitmark++]).

ID

The ID ([@id:…]) is a unique reference number given to each bit. It identifies the bit and is crucial for referencing, functions and rights management. Never change the ID of a bit.

Item

  • Information identifying or referring to a specific bit, like the number of a quiz or a text — it answers the question "which bit?".
  • A bit has to work without its item too; it is a kind of metadata.
  • Examples: 1., 1a, Art.2, Number 3, A), Page 27.
[.bitType]
[%item][%lead]
Body

Lead

  • Information ("label") classifying or describing the content of a bit, like "Example" or "Note".
  • The lead is not the title, and a bit must work without it; if there is only one lead in a whole book, it is probably not a lead.
  • Examples: Example, Note, Case, Side Note.

Instruction

  • The instruction ([!…]) addresses the user; it can also serve as the title of a bit (not of the content — see bitmark titles).
  • Examples: "Fill out the gaps", "Answer the question", "Read the text".

Body

The main element of the bit — normally text:

[.bitType]

[!instruction]

This is the body of the bit.

Resources

Bits often contain resources: pictures, audio, video, documents, … Every bit can have one resource attached by default. For the resource to be recognized it must be declared:

  • In the bit type, combined with & — e.g. [.article&image], [.cloze&audio].
  • In the body, as a & tag with the link to the resource.
[.article&image]

[!instruction]

[&image:https://example.org/images/background.png][@caption:Caption Text]

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Placement differs by text format:

  • With "normal" bitmark, a & resource is always displayed at the same position, defined by the reader.
  • With bitmark++, media is not a resource — it can be placed inline at a defined position in the body.