Docs Documentación

Widgets

Telar includes an interactive widget system for rich content in story panels and custom pages. Widgets let you embed image carousels, tabbed content, and collapsible sections directly in your markdown.

Available since v0.4.0.

Available Widgets

Widget Purpose
Carousel Image slideshow with captions and credits
Tabs Switchable content panels for multiple perspectives
Accordion Collapsible sections for sequential or hierarchical content
Bibliography Scholarly citations with hanging-indent formatting

Widget Syntax

Widgets use CommonMark-style container syntax with triple colons:

:::widget_type
widget content here
:::

Display multiple images with navigation controls, captions, and credits.

Syntax

:::carousel
image: story1/map.jpg
alt: Historical map of the region
caption: Map from 1650 showing colonial boundaries
credit: National Archives

---

image: story1/document.jpg
alt: Colonial document
caption: Royal decree establishing the settlement
credit: Archivo General de Indias
:::

Fields

Separate carousel items with ---.

External Images

You can use full URLs for images hosted elsewhere:

image: https://example.org/images/photo.jpg

Tabs

Organize content into switchable panels — useful for presenting different perspectives, sources, or categories.

Syntax

:::tabs
## Spanish Account
The royal authorities reported that the revolt began on...

Historical records show contradictory accounts...

## Indigenous Perspective
Community leaders organized resistance to...

Oral traditions describe a coordinated response...

## Modern Analysis
Historians now recognize this event as...
:::

Structure

Accordion

Create collapsible panels for chronological sequences, hierarchical information, or optional details that readers can expand on demand.

Syntax

:::accordion
## 1600-1650: Early Colonial Period
The Spanish crown established administrative structures across the territory.

Indigenous populations were reorganized into settlements...

## 1650-1700: Consolidation
Estate systems became entrenched as the colonial economy matured.

## 1700-1750: Reform Era
Bourbon reforms challenged existing power structures...
:::

Structure

Bibliography

Format scholarly citations with standard hanging-indent styling. Each citation is separated by a blank line.

Available since v1.1.0.

Syntax

:::bibliography
Cobo Betancourt, J. F. (2024). *The Coming of the Kingdom: The Muisca, Catholic Reform, and Spanish Colonialism in the New Kingdom of Granada*. Cambridge University Press.

Cobo, N. (2021). Creating authority and promoting normative behaviour. In T. Duve, J. L. Egío, & C. Birr (Eds.), *The School of Salamanca: A Case of Global Knowledge Production* (pp. 210–244). Brill.

Muñoz-Arbeláez, S. (2025). *The New Kingdom of Granada: The Making and Unmaking of Spain's Atlantic Empire*. Duke University Press.
:::

Structure

Where Widgets Work

Widgets can be used in:

For story panels, the recommended approach is to save widget content in a markdown file (Method 3: file reference) rather than entering it directly in a spreadsheet cell, since the triple-colon syntax is difficult to manage inline.

Widgets automatically use contrasting panel colors for visual distinction. Layer 1 widgets appear with Layer 2 styling, and vice versa.

Images in Widgets

Local Images

Place images in telar-content/objects/ and reference them by filename:

telar-content/objects/
├── map.jpg
├── document.jpg
└── artifact.jpg

image: map.jpg
image: document.jpg

If your images are in subfolders, include the path relative to telar-content/objects/:

image: story1/map.jpg

External Images

Use complete URLs for images hosted elsewhere:

image: https://digital-collections.library.edu/iiif/image123.jpg
image: https://archive.org/download/item/photo.jpg

Validation

Telar validates widgets during the build process:

Errors (build fails):

Warnings (build succeeds):

Check your build output for widget validation messages.

Examples

Historical Timeline

:::accordion
## 1520-1550: Conquest
Spanish forces established control over the territory through a series
of military campaigns...

## 1550-1600: Settlement
Colonial towns were founded as administrative centers...

## 1600-1680: Consolidation
The colonial economy based on mining and agriculture became established...
:::

Comparative Sources

:::tabs
## Primary Source
"On the 15th day of August, the viceroy decreed..."
(Colonial Archive, Doc. 234)

## Secondary Analysis
Modern historians interpret this decree as evidence of...

## Archaeological Evidence
Excavations at the site revealed...
:::

Image Comparison

:::carousel
image: before.jpg
alt: Site photograph from 1920
caption: The *Plaza Mayor* before restoration
credit: Municipal Archive

---

image: after.jpg
alt: Site photograph from 2020
caption: The *Plaza Mayor* after archaeological restoration
credit: National Institute of Anthropology
:::

Scholarly Citations

:::bibliography
Cobo Betancourt, J. F. (2024). *The Coming of the Kingdom*. Cambridge University Press.

Muñoz-Arbeláez, S. (2025). *The New Kingdom of Granada*. Duke University Press.
:::

See Also