Docs 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 Content Methods

You can provide panel content in three ways. For full details, see the CSV Reference: Stories.

Method 1: Entering Text Directly

Type panel text directly in your spreadsheet’s layer1_content column:

layer1_content
This textile shows advanced weaving techniques from the colonial period. The interlocking pattern indicates sophisticated craftsmanship.

Line breaks in your spreadsheet cell create paragraph breaks. The panel title defaults to the button text.

Method 2: Pasting Markdown Text

Paste text from a plain text editor. You can include headings, widgets, and a custom panel title using YAML frontmatter:

---
title: "Weaving Techniques"
---

The interlocking warp pattern visible here indicates a complex
weaving technique that was common in the colonial period.

## Technical Details

These patterns were created using...

If you copy and paste from Microsoft Word, Google Docs, or similar applications, formatting will not be preserved. Write in markdown syntax instead.

Method 3: Referencing a Markdown File

For complex content, reference a markdown file saved in components/texts/stories/:

layer1_content
colonial-textiles/step1-layer1.md

The file uses frontmatter for the panel title and supports all markdown features including widgets.

When to use file references:

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