Telar: Docs Telar: Documentación

Markdown Syntax Reference

Panel content in Telar supports rich markdown formatting. This reference covers all available syntax for creating engaging narrative content.

What is Markdown?

Markdown is a lightweight markup language that lets you format text using simple, readable syntax. Instead of complex HTML tags, you write in plain text with special characters like * for emphasis or # for headings. Markdown is:

Learning Resources

New to markdown? These resources will help:

In case you’re wondering, Telar uses the Python Markdown processor with the extra and nl2br extensions.

Panel Structure

Story layer files (referenced in layer1_file and layer2_file columns) use markdown with frontmatter:

---
title: "Your Panel Title"
---

Your content goes here with full markdown support.

The title from frontmatter appears in the panel header. The body content is converted to HTML and displayed in the panel.

Basic Formatting

Headings

## Second Level Heading
### Third Level Heading
#### Fourth Level Heading

Tip: Don’t use # First Level in panels - the panel already has a title from frontmatter.

Text Styling

**Bold text** for emphasis
*Italic text* for subtle emphasis
***Bold and italic*** for maximum emphasis

Lists

Unordered lists:

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

Ordered lists:

1. First step
2. Second step
3. Third step

[Link text](https://example.com)
[Internal link](/objects/textile-001/)

Blockquotes

> This is a blockquote.
> It can span multiple lines.

Images

Telar provides special syntax for controlling image sizes in panels.

Basic Syntax

![Alt text description](path/to/image.jpg){size}

Size Options

Size Keyword Max Width Use Case
Small {sm} or {small} 250px Thumbnails, icons, small details
Medium {md} or {medium} 450px Standard illustrations (default)
Large {lg} or {large} 700px Featured images, detailed views
Full {full} 100% Panoramas, full-width visuals

Image Paths

Relative paths (no leading slash) automatically load from /components/images/:

![Weaving detail](textile-closeup.jpg){md}

→ Loads /components/images/textile-closeup.jpg

Absolute paths (starting with /) load from site root:

![Site logo](/components/images/logo.png){sm}

External URLs work as expected:

![Museum photo](https://example.com/image.jpg){lg}

Examples

![Small thumbnail](thumb.jpg){small}
![Medium illustration](diagram.jpg){md}
![Large featured image](painting.jpg){large}
![Full-width panorama](landscape.jpg){full}

Default Size: Images without a size tag default to medium (450px). Always include size tags for clarity.

Image Captions

Add a caption to any image by placing text on the line immediately after the image:

![Colonial textile fragment](textile.jpg){lg}
Detail showing the *interlocking warp* pattern typical of the period.

The caption appears centered below the image in a lighter weight font.

Optional prefix: You can use caption: to make captions more explicit:

![Map of the region](map.jpg){md}
caption: Map from *Recopilación de Leyes*, 1680.

The caption: prefix is stripped from the displayed text.

Markdown in captions: Captions support inline markdown formatting like *italics*, **bold**, and [links](url).

Rich Media

YouTube Videos

Embed responsive YouTube videos using iframe HTML:

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; margin: 1.5rem 0;">
  <iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
          src="https://www.youtube.com/embed/VIDEO_ID"
          frameborder="0"
          allowfullscreen>
  </iframe>
</div>

Replace VIDEO_ID with your YouTube video ID.

The padding-bottom: 56.25% creates a 16:9 aspect ratio container.

Other Iframes

Any iframe-embeddable content works:

<iframe src="https://example.com/embed"
        width="100%"
        height="400"
        frameborder="0">
</iframe>

Code

Inline Code

Use backticks for inline code references:

The `object_id` field must match the filename.

Code Blocks

Use triple backticks for code blocks:

```
git add .
git commit -m "Update content"
git push
```

With syntax highlighting:

```yaml
title: My Story
description: A compelling narrative
```

Footnotes

Create footnotes with [^1] syntax:

The textile shows advanced techniques.[^1]

[^1]: Based on analysis by Dr. Smith (2020).

Footnotes automatically appear at the bottom of panel content with proper styling.

Best Practices

Alt Text for Accessibility

Always provide descriptive alt text for images:

✅ ![Detailed view of interlocking warp threads](closeup.jpg){lg}
❌ ![Image](closeup.jpg){lg}

Image Organization

Keep panel images in /components/images/ for easy reference:

components/images/
├── story1-context.jpg
├── story1-detail.jpg
├── story2-map.jpg
└── ...

Content Length

Break up long text with headings, lists, and images for better readability.

File Naming

Use descriptive, lowercase filenames with hyphens:

✅ ![Colonial weaving pattern](colonial-textile-detail.jpg){md}
❌ ![Photo](IMG_1234.JPG){md}

Quick Reference

Copy-paste examples for the most common formatting tasks:

Add an image with caption

![Colonial textile showing interlocking pattern](textile-detail.jpg){lg}
Detail of the warp threads, circa 1650.

Add a YouTube video

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; margin: 1.5rem 0;">
  <iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
          src="https://www.youtube.com/embed/dQw4w9WgXcQ"
          frameborder="0" allowfullscreen></iframe>
</div>

Add a citation with footnote

Recent scholarship challenges this interpretation.[^1]

[^1]: García, M. (2023). *Rethinking Colonial Textiles*. University Press.

The [[encomienda]] system structured colonial tributary relations.

Compare with the [Lima textile](/objects/textile-lima/).

Create a blockquote

> "The patterns speak to a sophisticated understanding of geometry."
> — Author

Limitations

Next Steps