MarkBack

Appearance

MarkBack Format ​

MarkBack stores content and feedback together in a compact, human-writable record. The canonical, authoritative spec is rendered on-site in MarkBack v1 Specification.

Record Anatomy ​

A record contains:

  • Optional headers (@uri, @by, @prior, @source)
  • Optional inline content
  • A required feedback line starting with <<<

Content vs feedback

Everything before <<< is content (or references). Everything after <<< is feedback.

One-line feedback rule

Feedback must be a single line. The delimiter is <<< followed by exactly one space and the feedback text.

Optional URI behavior

@uri is optional. If missing, the record can still be used, but linters warn because the record has no explicit identifier.

Annotated Examples ​

Single Record (Inline Content) ​

mb
@uri local:prompt-001

Write a haiku about programming.
<<< quality=good; creativity=high
  • Blank line is required before inline content.
  • Feedback is a single line after <<< .

Multi-Record File ​

mb
@uri local:item-001

First piece of content here.
<<< positive
---
@uri local:item-002

Second piece of content.
Multiple lines are fine.
<<< negative; reason=unclear
---
Third item has no URI.
<<< neutral
  • Records are separated by --- on its own line.
  • The third record is valid without @uri.

Paired-File Mode ​

content.txt

text
The actual content goes here.

content.label.txt

mb
@uri local:content-001
<<< approved; reviewer=alice
  • Paired label files contain only headers and feedback.
  • @source is implicit (the content file).

External Content Reference ​

mb
@uri local:asset-123
@source ./assets/prompt.txt
<<< approved; topic=summary
  • When @source is present, inline content must be empty.

Generated Content with Prior ​

mb
@uri local:generated-image-001
@prior ./prompts/beach-sunset.txt
@source ./images/generated-beach.jpg
<<< accurate; matches prompt well; quality=high
  • @prior references the input that produced the content (e.g., a prompt).
  • Useful for LLM-generated images, text, or other derived content.

Attributed Feedback ​

mb
@uri local:review-001
@by alice

Write a function to calculate factorial.
<<< approved; clarity=high
  • @by attributes the feedback to a specific reviewer or annotator.
  • Useful for multi-reviewer workflows and audit trails.

Compact Label Lists ​

For many external files, use compact, single-line records:

mb
@source ./images/cat.jpg <<< positive; animal=cat
@source ./images/dog.jpg <<< positive; animal=dog
@source ./images/blurry.jpg <<< rejected; too blurry to classify
  • No --- separators are needed between compact records.