Telar: Docs Telar: Documentación

Configuration

Configure your Telar site through the _config.yml file in your repository root.

Site Settings

Basic site information and appearance:

# Site Settings
title: Your Narrative Title
description: A brief description of your narrative exhibition
baseurl: "/repository-name"  # For GitHub Pages subdirectory
url: "https://username.github.io"
author: Your Name
email: your-email@example.com
telar_theme: "paisajes"  # Options: paisajes, neogranadina, santa-barbara, austin, or custom
logo: ""  # Path to logo image (optional)
telar_language: "en"  # Options: "en" (English), "es" (Español)

baseurl vs. url

Examples:

# GitHub Pages subdirectory
url: "https://username.github.io"
baseurl: "/telar-site"
# Result: https://username.github.io/telar-site

# Custom domain at root
url: "https://mysite.org"
baseurl: ""
# Result: https://mysite.org

Add a logo to replace the site title in the navigation header:

logo: "/components/images/my-logo.png"

Theme Selection

Telar includes 4 preset themes:

telar_theme: "paisajes"  # Options: paisajes, neogranadina, santa-barbara, austin, or custom

Available Themes

See Customization: Themes for details and creating custom themes.

Multilingual Interface

Telar v0.4.0+ supports multilingual user interfaces in English and Spanish:

telar_language: "en"  # Options: "en" (English), "es" (Español)

This controls the language of all interface elements, including navigation, buttons, labels, error messages, and instructions.

What Gets Translated

The telar_language setting changes the language of:

What Stays in Your Language

The telar_language setting does not translate your content:

If you need a fully bilingual site with content in multiple languages, you’ll need to create separate Telar sites for each language.

IIIF Metadata Language Detection

When Telar auto-extracts metadata from IIIF manifests, it respects your telar_language setting:

This ensures that object metadata appears in your preferred language when available from the source institution.

Google Sheets Integration

Manage content via Google Sheets instead of editing CSV files directly:

google_sheets:
  enabled: true
  shared_url: "https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit?usp=sharing"
  published_url: "https://docs.google.com/spreadsheets/d/e/YOUR_PUBLISHED_ID/pubhtml"

Setup Steps

  1. Get the template: Duplicate the template at bit.ly/telar-template
  2. Share your sheet: Set to “Anyone with the link (Viewer access)”
  3. Publish your sheet: File → Share → Publish to web
  4. Paste both URLs into _config.yml
  5. Set enabled: true
  6. Commit changes

Automated fetching:

Both URLs are required. The shared URL is for viewing, the published URL is for automated fetching.

See Google Sheets Workflow for complete setup instructions.

Story Interface Settings

Control how stories display and behave:

story_interface:
  show_story_steps: true  # Set to false to hide "Step X" overlay
  include_demo_content: false  # Set to true to enable demo stories
  show_object_credits: true  # Set to false to hide credits badge on objects

show_story_steps

Controls whether the “Step X” indicator appears in the top-left corner of story viewers.

This is purely visual - users can still navigate through steps normally.

include_demo_content

Enable pre-built demonstration stories that showcase Telar’s features:

Demo stories appear alongside your own content with a “Demo content” badge. They’re automatically fetched during the build process and matched to your site’s language.

When to enable:

When to disable:

See Demo Content for complete details on available demos.

show_object_credits

Controls the credit attribution badge on object pages:

The credit badge displays in the top-right corner of object images, showing attribution from the credit field in your objects.csv.

Advanced Settings

The following settings are pre-configured and typically don’t need modification unless you’re doing advanced customization.

Do Not Edit The Telar _config.yml includes a line: “PLEASE DO NOT EDIT BELOW THIS LINE UNLESS YOU KNOW WHAT YOU ARE DOING”. The sections below this line are configured automatically and rarely need changes.

Collections

Jekyll collections define content types:

collections:
  stories:
    output: true
    permalink: /stories/:name/
  objects:
    output: true
    permalink: /objects/:name/
  glossary:
    output: true
    permalink: /glossary/:name/
  pages:
    output: true
    permalink: /:name/

# Collections Directory
collections_dir: _jekyll-files

You typically don’t need to modify collection settings unless doing advanced customization.

The collections_dir setting tells Jekyll where to find auto-generated working files.

Defaults

Layout defaults for each collection:

defaults:
  - scope:
      path: ""
      type: "stories"
    values:
      layout: "story"
  - scope:
      path: ""
      type: "objects"
    values:
      layout: "object"
  - scope:
      path: ""
      type: "glossary"
    values:
      layout: "glossary"
  - scope:
      path: ""
      type: "pages"
    values:
      layout: "user-page"

Build Settings

Standard Jekyll build configuration:

markdown: kramdown
permalink: pretty
exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor
  - .github
  - README.md
  - docs/
  - scripts/

# Tell Jekyll not to expect dates for collections
future: true
show_drafts: false

Plugins

Required plugin:

plugins:
  - jekyll-seo-tag

Installed automatically when you run bundle install.

Telar Version

Version information (updated automatically during releases):

telar:
  version: "0.6.2-beta"
  release_date: "2025-12-03"

Development Features

Options for development, testing, and special use cases (please do not edit these unless you know what you are doing):

development-features:
  christmas_tree_mode: false
  viewer_preloading:
    max_viewer_cards: 10
    preload_steps: 6
    loading_threshold: 5
    min_ready_viewers: 3
  hide_stories: false
  hide_collections: false

christmas_tree_mode

Displays all warning messages for testing multilingual support:

Use this only when testing translations or warning message styling.

viewer_preloading

Controls how story viewers are preloaded for smoother navigation:

Higher values = smoother scrolling but more memory usage. The defaults work well for most sites.

hide_stories

Build a site without stories, keeping only objects visible:

Use this when you want to showcase objects without narrative stories, or when building a catalog-style site.

hide_collections

Build a site with only custom user pages (no objects or stories):

Use this when building a site with only custom pages (like an “About” or landing page) without any collections.

When hide_collections is enabled, hide_stories is automatically implied.

Full Example

Here’s a complete _config.yml example:

# Site Settings
title: Colonial Textiles
description: An exhibition of colonial-era textiles from the Americas
baseurl: "/colonial-textiles"
url: "https://username.github.io"
author: Jane Smith
email: jane@example.com
telar_theme: "paisajes"
logo: ""
telar_language: "en"

# Story Interface Settings
story_interface:
  show_story_steps: true
  show_object_credits: true
  include_demo_content: false

# Google Sheets Integration (optional)
google_sheets:
  enabled: true
  shared_url: "https://docs.google.com/spreadsheets/d/ABC123/edit?usp=sharing"
  published_url: "https://docs.google.com/spreadsheets/d/e/XYZ789/pubhtml"

#
# PLEASE DO NOT EDIT BELOW THIS LINE UNLESS YOU KNOW WHAT YOU ARE DOING
#

# Collections
collections:
  stories:
    output: true
    permalink: /stories/:name/
  objects:
    output: true
    permalink: /objects/:name/
  glossary:
    output: true
    permalink: /glossary/:name/
  pages:
    output: true
    permalink: /:name/

collections_dir: _jekyll-files

# Build Settings
markdown: kramdown
permalink: pretty
exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor
  - .github
  - README.md
  - docs/
  - scripts/

# Defaults
defaults:
  - scope:
      path: ""
      type: "stories"
    values:
      layout: "story"
  - scope:
      path: ""
      type: "objects"
    values:
      layout: "object"
  - scope:
      path: ""
      type: "glossary"
    values:
      layout: "glossary"
  - scope:
      path: ""
      type: "pages"
    values:
      layout: "user-page"

future: true
show_drafts: false

# Telar Settings
telar:
  version: "0.6.2-beta"
  release_date: "2025-12-03"

# Plugins
plugins:
  - jekyll-seo-tag

# WEBrick server configuration for development (enables CORS for IIIF)
webrick:
  headers:
    Access-Control-Allow-Origin: "*"
    Access-Control-Allow-Methods: "GET, POST, OPTIONS"
    Access-Control-Allow-Headers: "Content-Type"

# Development & Testing
development-features:
  christmas_tree_mode: false
  viewer_preloading:
    max_viewer_cards: 10
    preload_steps: 6
    loading_threshold: 5
    min_ready_viewers: 3
  hide_stories: false
  hide_collections: false

Next Steps