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.1-beta"
  release_date: "2025-11-28"

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.1-beta"
  release_date: "2025-11-28"

# Plugins
plugins:
  - jekyll-seo-tag

Next Steps