> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/annotations/html-annotation.md).

# HTML Annotation

Label visible text, entity relationships, and properties in saved HTML pages while preserving rendered context.

HTML annotation turns saved web pages into structured training and evaluation data. Work with the rendered page, select visible text, and add ontology-defined labels while keeping headings, images, tables, and nearby content available as context.

{% hint style="info" %}
**Use this guide when:** you need to label product pages, job postings, articles, or other saved HTML sources for information extraction.
{% endhint %}

## See HTML annotation in action

The demo shows the rendered HTML work surface and text annotations in their original page layout.

{% embed url="<https://homepage-files.s3.us-east-2.amazonaws.com/hero-videos/hero/html-annotation-1-20260917.mp4>" %}

[Open the demo in a new tab](https://homepage-files.s3.us-east-2.amazonaws.com/hero-videos/hero/html-annotation-1-20260917.mp4).

## Before you begin

1. Prepare saved `.html` or `.htm` files. Check that the content needed for annotation is visible in the saved source.
2. Upload the files and wait for processing to finish before attaching or publishing them as dataset members.
3. Configure entity classes, class properties, Item Properties, and allowed relations in the project ontology.
4. Write instructions for span boundaries, repeated text, navigation content, missing fields, and ambiguous values.
5. Open an assigned item from the project data view or Task Queue.

See [Annotation Workbench](https://docs.unitlab.ai/documentation/annotations/annotation-workbench) for shared navigation, saving, history, comments, and stage actions.

## Understand the HTML work surface

The viewer displays a prepared snapshot of the uploaded page. Select text in the rendered content rather than editing HTML source code. Fixed-width, fit, and responsive viewing options change the presentation of the same snapshot; they do not create a new source revision.

![The same product page in fixed-width and responsive views with Product and Brand text spans preserved.](https://content.gitbook.com/content/GjVLUz4wthGkGlRKM6rM/blobs/eHr0qc6eYqBU0sb7uqsX/6aa6304743db9787bc27ac64_unitlab%20html%20feature%20context%20preserving%20viewer%2020260913.webp)

*Inspect the same saved page at a useful width while retaining its annotation context.*

Images, charts, and controls in the page provide context. They do not become separate image or video annotation surfaces within the HTML item. Prepare another source item when the task requires labeling that media directly.

## Supported annotation model

| Annotation           | What it records                                                   | Example                                                            |
| -------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Text span**        | A contiguous range of visible text and its class.                 | Product name, price, employer, or publication date.                |
| **Class properties** | Structured values attached to an entity.                          | Currency, employment type, or a manually entered normalized value. |
| **Item Properties**  | Values describing the complete saved page.                        | Page type, language, relevance, or source category.                |
| **Relation**         | An ontology-defined connection between entities in the same page. | Product **made\_by** Brand or Job **offered\_by** Employer.        |

Text selections may cross adjacent text nodes, but must remain contiguous and non-overlapping. Use Item Properties for whole-page classification so it does not overlap entity spans. Relations and properties add meaning to entities; they are not additional drawing tools.

## Label visible text precisely

Select the exact text required by the instructions and apply its class. Check whether punctuation, currency symbols, units, or qualifiers belong in the span. A page may repeat the same value in a heading, summary, and recommendation; annotate the occurrence that belongs to the target record.

![Rendered product page with Product, Brand and Price labels on AeroDesk Stand, Northstar and $129.](https://content.gitbook.com/content/GjVLUz4wthGkGlRKM6rM/blobs/47gkaLmDw03neHOzuMRL/6aa63046e8788851830ac215_unitlab%20html%20feature%20text%20span%20annotation%2020260913.webp)

*Product, Brand, and Price spans remain grounded in the rendered product page.*

For example, a price policy might require `$129`, including the currency symbol. Apply that rule consistently rather than alternating between `$129` and `129`. Store a normalized amount in a configured property if the task requires it; normalization is an annotation decision.

## Connect entities and complete properties

Choose relations allowed by the ontology and verify their direction and endpoints. Connect the product to its own brand or price, especially when several products appear on the page. Use class properties for entity details and Item Properties for page-level context.

![A made\_by relationship connects the AeroDesk Stand product span to the Northstar brand span in a rendered HTML page.](https://content.gitbook.com/content/GjVLUz4wthGkGlRKM6rM/blobs/os4CQ2bcONsAX2qDHEhy/6aa630474872ed6bed41519d_unitlab%20html%20feature%20entity%20relationships%2020260913.webp)

*A same-page relation connects the product entity to its brand.*

## Annotate one production item

1. **Inspect the source.** Confirm the page identity and that the relevant content survived saving and processing.
2. **Locate the target content.** Distinguish the main record from navigation, advertisements, and related items using the task instructions.
3. **Create spans.** Label complete, contiguous text without overlapping another entity.
4. **Add structure.** Complete properties, classify the page, and create the required relations.
5. **Review in context.** Check repeated values, missing fields, relation direction, and span boundaries at a readable width.
6. **Save and submit.** Resolve applicable findings, save the annotation, and use the available workflow action to hand it to the next stage.

## Quality review

| Review focus    | What to check                                                                 |
| --------------- | ----------------------------------------------------------------------------- |
| Source identity | Labels refer to the intended saved page, not a later website revision.        |
| Span boundaries | Complete words and task-required symbols are included without unrelated text. |
| Coverage        | Required fields are labeled, or absence is handled according to instructions. |
| Relationships   | Endpoints belong to the same target and the relation direction is correct.    |
| Properties      | Entity and page values are complete and use the intended ontology choices.    |

![An open review comment is anchored to the AeroDesk Stand text span on a rendered product page.](https://content.gitbook.com/content/GjVLUz4wthGkGlRKM6rM/blobs/O5B7M7pKD6ewRKshkavG/6aa6304858da10b1692a3a9b_unitlab%20html%20feature%20anchored%20review%20comments%2020260913.webp)

*Anchor feedback to the text that needs correction so another annotator can resolve it in context.*

Use [Review Stages](https://docs.unitlab.ai/documentation/qa/review-stages) for expert decisions, [Consensus](https://docs.unitlab.ai/documentation/qa/consensus) to compare independent annotations, and [Quality Gate](https://docs.unitlab.ai/documentation/qa/quality-gate) for comparisons with approved answer keys. Agreement is evidence of consistency, not a guarantee that the extraction policy is correct.

## Prepare a traceable release

Use folders, tags, filenames, and available metadata to curate the source pages. A dataset version fixes the selected source membership. After annotation and review, create a project annotation release to freeze the labels for delivery.

HTML JSONL and native UUEF exports preserve text, entity properties, relationships, page properties, and snapshot or anchor identity. Verify representative exported spans against the saved page and check that the downstream consumer handles the source identity correctly. An export source URL can identify Unitlab's release source rather than the original website.

## Troubleshooting and boundaries

| Situation                            | Recommended action                                                                                 |
| ------------------------------------ | -------------------------------------------------------------------------------------------------- |
| Required text is missing             | Inspect the saved file and processing state. Prepare a complete source before annotation.          |
| A selection overlaps another entity  | Adjust the boundary or express the additional meaning as a property or relation.                   |
| The original website changed         | Treat the revised page as a new source; changing the viewer width does not re-anchor labels to it. |
| A field has several plausible values | Leave contextual feedback and route it to the assigned reviewer.                                   |

This workflow annotates saved pages. It does not provide website crawling, raw DOM or HTML-attribute labeling, or browser interaction recording.

## Next steps

* Define acceptance rules in [Project Instructions](https://docs.unitlab.ai/documentation/projects/project-instructions).
* Connect annotation and review with [QA Workflows](https://docs.unitlab.ai/documentation/qa/qa-workflows).
* Prepare delivery using [Create a release](https://docs.unitlab.ai/documentation/releases/create-a-release).

Explore the [Unitlab HTML Annotation overview](https://unitlab.ai/en/html-annotation).