Docs Documentación

Quick Start

Telar is a minimal-computing framework for creating interactive visual narrative exhibitions. It weaves together high-resolution images, narrative text, and layered contextual information into scrollytelling experiences — hosted for free on GitHub Pages.

This tutorial walks you through building your first exhibition in four steps:

  1. Set Up Your Site — Set up your GitHub repository, Google Sheet, and configuration
  2. Plan Your Narrative — Understand how stories, steps, and panels fit together
  3. Add Your Content — Upload images, fill in your spreadsheet, and create your first story
  4. Review and Refine — Set image coordinates, review your site, and polish

A Telar exhibition is made up of stories — step-by-step visual narratives built around high-resolution images. Each story unfolds through a series of steps. Every step zooms into a region of an image and presents a question with a brief answer. Viewers who want more can open layer panels — expandable sections with longer text, embedded media, or interactive widgets. We will see this in more detail when we get to Step 2: Plan Your Narrative. But first, we need to set up the basics.

Step 1: Set up your site

In this first step, you’ll set up three things: a GitHub repository for your site, a Google Sheets spreadsheet for your content, and a configuration file to connect them. You’ll enter a few details as you go — your GitHub username, your spreadsheet link, a title for your site. At the end of this page, you’ll download a ready-to-use configuration file.

You will need:

Already familiar with GitHub Pages and YAML? You can configure everything manually with the Manual Setup guide.

The setup might feel like a lot of steps, but you only have to do it once. After that, everything happens in your Google Sheets spreadsheet.

Create Your Repository

A repository is your project’s home on GitHub — it holds your configuration and image files.

  1. Visit the Telar template
  2. Click the green Use this template button
  3. Choose Create a new repository
  4. Give your repository a name — use lowercase letters and hyphens (e.g., my-exhibition) — this will be part of your site’s web address
  5. Make sure Public is selected
  6. Click Create repository

GitHub screenshot: Use this template button

Keep your repository public. Private repositories will not work with GitHub Pages unless you have a paid GitHub plan.

Enter your GitHub details below. These are used to build your site’s web address and to generate your configuration file at the end.

Your GitHub Details
Your site will be at:
https://username.github.io/my-exhibition

Enable GitHub Pages

GitHub Pages turns your repository into a live website for free.

  1. In your repository, go to Settings → Pages
  2. Under Source, select GitHub Actions
  3. Click Save

Setting up GitHub Pages with GitHub Actions

Duplicate the Google Sheets Template

Your Google Sheets spreadsheet is where you manage all your content — objects, stories, and text.

  1. Go to https://bit.ly/telar-template
  2. Click File → Make a copy
  3. Save to your Google Drive with a name you will remember (e.g., “My Telar Exhibition”)

Share and Publish Your Sheet

Your spreadsheet needs two types of access so Telar can read your content.

Share your sheet:

  1. Click the Share button in Google Sheets
  2. Set access to “Anyone with the link” with Viewer permissions
  3. Copy the shared URL and paste it below

Publish your sheet:

  1. Go to File → Share → Publish to web
  2. Click Publish
  3. Copy the published URL and paste it below
Your Google Sheets URLs
The URL from the Share dialog (Viewer access)
From File → Share → Publish to web. This is a different URL from the one above.

Generate Your Configuration

Fill in the remaining details and this page will create your configuration file.

Site Details
Your site's display name, shown in the browser tab and header
Used for search engine metadata and social sharing previews
Controls your site's color scheme and visual style

Your _config.yml

Once generated:

  1. In your GitHub repository, navigate to _config.yml and click the pencil icon to edit
  2. Select all the existing content and replace it with what you copied or downloaded
  3. Click Commit changes to save

Verify Your Setup

After committing, GitHub Actions will automatically build and publish your site. This takes 2–5 minutes.

  1. Click the Actions tab to watch the build progress
  2. When it finishes, visit your site at the URL shown in the preview above
  3. You should see a Telar site with your title and the default demo content

Telar homepage with title and navigation menu

Build problems? The most common issues are mismatched Google Sheets URLs (you need both the shared URL and the published URL — they are different). If your site does not appear at all, check the Actions tab for error details. You can also paste your _config.yml into the Telar Config Validator to check for errors.

Next Steps

Your Telar site is up and running. Follow this tutorial to learn how Telar stories work and add your own content, or jump ahead to any section: