Examples

Each example below is valid MarkBack V2. Note that content can include Markdown formatting -- MarkBack is designed to wrap Markdown content with feedback.

Single Record with Markdown

@id ex-001

# API Design Prompt

Create a REST endpoint that:

- Accepts **POST** requests to `/users`
- Validates `email` and `password` fields
- Returns a JWT token on success
<<< approved; clarity=high; completeness=good

Multi-Record File

%markback 2

@id qa-001

## Question
What is the time complexity of binary search?

## Expected Answer
**O(log n)** -- the search space halves with each comparison.
<<< correct; difficulty=easy

---
@id qa-002

## Question
Explain the difference between `let` and `const` in JavaScript.

## Expected Answer
- `let` allows reassignment
- `const` creates an immutable binding
<<< needs work; missing scope explanation

Code Review Example

@id review-001

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

Task: Review this code for performance issues. <<< good; identified=memoization; clarity=high

## Compact Label List

For labeling external files (documents, images, etc.):

```mb
@file ./docs/intro.md <<< approved; audience=beginner
@file ./docs/api-ref.md <<< needs work; missing examples
@file ./docs/tutorial.md <<< approved; audience=intermediate

Sidecar Files

prompt.md

# Essay Prompt

Write a 500-word essay on the **impact of remote work** on:

1. Productivity
2. Work-life balance
3. Team collaboration

> Include at least one citation.

prompt.md.mb

@id essay-prompt-001
<<< approved; tone=academic; scope=appropriate

Structured Feedback

@id doc-review-001

# Getting Started Guide

This guide walks you through:

1. **Installation** -- via pip or npm
2. **First Steps** -- creating your first record
3. **Next Steps** -- exploring advanced features

_Estimated reading time: 5 minutes_
<<< quality=excellent; accuracy=high; audience=beginner; needs=screenshots

Line Number References

For precise code review or annotation of specific lines:

@file ./src/auth.py:42 <<< bug; null check missing
@file ./src/auth.py:55-62 <<< refactor; extract to helper
@file ./src/api.py:100-120 <<< approved; clean implementation

With IDs for tracking:

@id review-PR-456-1
@file ./handlers.py:88 <<< critical; SQL injection vulnerability

@id review-PR-456-2
@file ./handlers.py:92-98 <<< suggestion; use parameterized queries

Attributed Feedback

For multi-reviewer workflows, use @by to track who provided feedback:

@id review-001
@by alice

Write a function to calculate factorial.
<<< approved; clarity=high; completeness=good

Multiple reviewers on the same content:

@id essay-review-alice
@by alice
@file ./essays/climate-change.md
<<< good; well-argued; needs stronger conclusion

---
@id essay-review-bob
@by bob
@file ./essays/climate-change.md
<<< excellent; compelling evidence; minor grammar issues

Tags

@id item-001
@tag training positive-examples batch-2024-03
@file ./data/example.txt
<<< approved

Sweep Pattern

For coverage tracking -- files matching %covers with no record are implicitly clean:

%markback 2
%scope correctness style naming
%covers ./src/batch3/*.py

@file ./src/batch3/handler.py:15-20 <<< style; function too long
@file ./src/batch3/utils.py:8 <<< naming; rename variable to something descriptive

Generated Content with Input

@id generated-image-001
@input ./prompts/beach-sunset.txt
@file ./images/generated-beach.jpg
<<< accurate; matches prompt well; quality=high

Threaded Replies

Use @reply-to to create threaded conversations within a review:

@id c1
@file ./src/auth.py:42 <<< this branch never fires

@id c2
@reply-to c1
@file ./src/auth.py:42 <<< it does -- covered by test_login_edge()

@id c3
@reply-to c2
@file ./src/auth.py:42 <<< fair enough, closing this thread

Multi-Line Feedback

When feedback needs more than one line, use the fenced form with """:

@id review-detailed
@file ./src/handler.py:88-95
<<< """
This error handling block has several issues:

1. The catch is too broad -- it swallows TypeError
2. The retry logic doesn't back off
3. No logging before the re-raise

Consider extracting a retry helper with exponential backoff.
"""

Multi-Segment Sections

Multiple comments on the same file without repeating @file:

@file ./essay.txt

the lazy fox
<<< awkward phrasing

weak ending
<<< needs punch

dragging middle paragraph
<<< trim this

All three records inherit @file ./essay.txt. A --- separator ends the section.

JSON Feedback

For machine-readable feedback with complex structure:

@id eval-001

Summarize the key points from the *quarterly report*.
<<< json:{"rating":4.5,"categories":["accuracy","conciseness"],"reviewer":"alice","timestamp":"2026-01-05"}