A minimal computing framework for creating visual narrative exhibitions with IIIF images and scrollytelling.
Full Documentation | Example Site | Report Issues
⚠️ Beta Release - v0.4.2-beta This is a beta release for testing and feedback. For detailed documentation, visit ampl.clair.ucsb.edu/telar-docs.
Warning: If upgrading from v0.3.4 or earlier, see the Upgrading Telar Guide for instructions.
Telar (Spanish for "loom") is a static site generator built on Jekyll that weaves together IIIF images, narrative text, and layered contextual information into interactive visual narrative exhibitions. It follows minimal computing principles: plain text authoring, static generation, and sustainable hosting.
Telar is developed by Adelaida Ávila, Juan Cobo Betancourt, Santiago Muñoz, and students and scholars at the UCSB Archives, Memory, and Preservation Lab, the UT Archives, Mapping, and Preservation Lab, and Neogranadina.
We gratefully acknowledge the support of the Caribbean Digital Scholarship Collective, the Center for Innovative Teaching, Research, and Learning (CITRAL) at the University of California, Santa Barbara, the UCSB Library, the Routes of Enslavement in the Americas University of California MRPI, and the Department of History of The University of Texas at Austin.
- IIIF integration: Support for both local images (auto-generated tiles) and external IIIF resources with automatic metadata extraction
- Scrollytelling: Discrete step-based scrolling with support for multiple IIIF objects in a single story - each object preloaded in its own viewer card
- Interactive widgets: Carousel, tabs, and accordion components for rich content presentation
- Layered panels: Progressive disclosure with three content layers plus glossary auto-linking
- Multilingual UI: Complete interface support for English and Spanish
- Objects gallery: Browsable object grid with detail pages
- Minimal computing: Plain text, static generation, GitHub Pages hosting
For comprehensive step-by-step guides, see the full documentation site. This Quick Start provides the essential steps to get your site running—detailed workflows and advanced topics are covered in the docs.
Get started with Telar in just a few steps. Telar narratives combine IIIF images with layered storytelling—each story unfolds through steps that show images alongside brief text, with optional panels for deeper exploration.
Plan your narrative structure before building. Sketch out your stories, identify key moments, choose anchor images, and decide what information belongs in brief answers versus deeper layers. Browse the example site for inspiration.
-
Create your repository
- Click the green "Use this template" button above
- Name your repository and create it
-
Choose your content management approach
- Google Sheets (recommended): Use our template to manage content via spreadsheet
- CSV files: Edit CSV files directly in your repository
-
Add your content
- Upload images to
components/images/objects/or use IIIF manifests from institutions - Create markdown files in
components/texts/stories/for your narrative text - Configure your objects and stories in Google Sheets or CSV files
- Upload images to
-
Enable GitHub Pages
- Go to repository Settings → Pages
- Set source to GitHub Actions
- Save and wait 2-5 minutes for deployment
-
Configure and customize
- Edit
_config.ymlto set your site title and theme - For Google Sheets: Add your sheet URLs to the
google_sheetssection - View your site at
https://[username].github.io/[repository]/
- Edit
- Detailed workflows: See GitHub Web Interface or Local Development guides
- Content structure: Learn about organizing your content
- IIIF integration: Understand how to work with IIIF images
- Customization: Explore themes and styling options
Telar v0.3.4+ includes an automated upgrade system for easy, safe updates to the latest version.
Upgrading is fully automated:
- Go to your repository on GitHub → Actions tab
- Select "Upgrade Telar" workflow
- Click Run workflow
- Review the automatically created upgrade issue
- Click the link in the issue to create a pull request
- Review changes and merge
The upgrade system detects your current version, applies all necessary migrations, and creates a detailed summary with any manual steps you need to complete.
First-time setup required (one-time only):
- Add the upgrade workflow file and updated build workflow from the Telar repository
- Run your first automated upgrade
- All future upgrades will be automated
For complete upgrade instructions, including detailed setup steps, troubleshooting, and version history, see the Upgrading Telar Guide in the documentation.
For developers who want to run Telar locally:
Prerequisites: Ruby 3.0+, Bundler, Python 3.9+
Quick setup:
bundle install
pip install -r requirements.txt
bundle exec jekyll serveFor detailed local development instructions, see the Local Development Guide in the documentation.
Telar uses a components-based architecture:
components/structures/- CSV files (or Google Sheets) with site and story datacomponents/images/objects/- Source images for IIIF processingcomponents/texts/stories/- Markdown files for narrative contentcomponents/texts/glossary/- Glossary term definitions
For detailed information about organizing your content, see the Content Structure Guide in the documentation.
Telar supports both local images (auto-generated IIIF tiles) and external IIIF resources from museums and libraries. Upload images to components/images/objects/ or reference external IIIF manifests in your object metadata.
For complete details on working with IIIF images, see the IIIF Integration Guide.
Configure your site in _config.yml (site title, theme, Google Sheets URLs, etc.). Telar includes 4 preset themes: Paisajes, Neogranadina, Santa Barbara, and Austin.
For all configuration options, see the Configuration Guide.
The build process is fully automated via GitHub Actions. Push changes to the main branch and GitHub Pages automatically rebuilds and deploys your site. To manually trigger a rebuild (e.g., after editing Google Sheets), go to the Actions tab and run the "Build and Deploy" workflow.
For details on the automated workflow, see the GitHub Actions Reference.
Telar v0.3.4+ includes an automated upgrade workflow that migrates your site to the latest version.
Note: The automated upgrade workflow is available for sites running v0.3.4 or later. If you're upgrading from an earlier version (v0.2.0-v0.3.3), you'll need to manually copy the upgrade workflow files to your repository first. See the Upgrade Guide for detailed instructions.
To upgrade your site (v0.3.4+):
- Go to your repository's Actions tab on GitHub
- Select the "Upgrade Telar" workflow
- Click "Run workflow"
- Review the automatically created pull request
- Merge the PR to complete the upgrade
The upgrade system automatically:
- Detects your current version
- Applies necessary migrations
- Updates framework files and configurations
- Generates an upgrade summary with any manual steps
For detailed instructions, see the Upgrade Guide.
Telar includes 4 preset themes (Paisajes, Neogranadina, Santa Barbara, Austin) that can be switched via _config.yml. You can also create custom themes with your own colors and fonts.
For theme customization and advanced styling, see the Customization Guide.
MIT License - see LICENSE file for details.
Note: This license covers the Telar framework code and documentation. It does NOT cover user-created content (stories, images, object metadata, narrative text) which remains the property of content creators and may have separate licenses.
Telar is developed by Adelaida Ávila, Juan Cobo Betancourt, Santiago Muñoz, and students and scholars at the UCSB Archives, Memory, and Preservation Lab, the UT Archives, Mapping, and Preservation Lab, and Neogranadina.
Telar is built with:
- Jekyll - Static site generator
- UniversalViewer - IIIF viewer
- Bootstrap 5 - CSS framework
- iiif-static - IIIF tile generator
It is based on Paisajes Coloniales, and inspired by:
- Wax - Minimal computing for digital exhibitions
- CollectionBuilder - Static digital collections
- Documentation: ampl.clair.ucsb.edu/telar-docs
- Report Issues: GitHub Issues
- Example Site: ampl.clair.ucsb.edu/telar