Docs Documentación

Upgrading Telar

Keep your Telar site up to date with the latest features, bug fixes, and improvements.

Using the Telar Compositor? If you manage your site through the Telar Compositor, you can upgrade with one click from its Upgrade screen — the manual steps below aren’t needed. If it asks you to approve updated GitHub permissions first, accept them and retry. The instructions below are for upgrading directly on GitHub instead.

Overview

Telar v0.3.4 introduced an automated upgrade system that makes updating your site simple and safe. The upgrade process depends on which version you’re currently running:

Automated Upgrades (v0.3.4+)

If your site is already running Telar v0.3.4 or later, upgrading is fully automated.

How It Works

The upgrade system:

  1. Detects your current Telar version from _config.yml
  2. Applies all necessary migrations incrementally (e.g., v0.3.4 → v0.3.5 → v0.3.6)
  3. Updates framework files and configurations
  4. Creates an upgrade branch and issue with detailed summary
  5. Highlights any manual steps you need to complete

Running an Automated Upgrade

Forked repositories only: If you forked your site from another repository, you’ll need to enable issues in your repository settings (Settings → General → check Issues). Sites created using the “Use this template” button already have issues enabled.

  1. Go to your repository on GitHub
  2. Click the Actions tab
  3. Select the “Upgrade Telar” workflow from the left sidebar
  4. Click Run workflow (green button on the right)
  5. Click the green Run workflow button in the dropdown
  6. Wait for the workflow to complete (usually 1-2 minutes)
  7. Review the automatically created upgrade issue
  8. Click the link in the issue to create a pull request
  9. Review changes and merge the pull request to complete the upgrade

Safe and Reversible The upgrade creates an issue and branch, giving you full control. Review the changes via the compare link, create a PR when ready, and merge only after verification.

After Upgrading

  1. Visit your site to verify it’s working correctly
  2. Check the upgrade issue for any manual steps (visible in the “After Merging” section)
  3. If you have custom themes or modifications, test them thoroughly
  4. Close the upgrade issue once everything is working - this marks the upgrade as complete
  5. If you encounter issues, check the GitHub Issues or report a bug

v1.5.0 Upgrade Notes

v1.5.0 is a robustness and security release. It is runtime and tooling only — existing stories, objects, and configuration continue to work unchanged, with no CSV edits and no config changes. The automated upgrade handles all framework file replacements; two optional manual steps are described below.

What’s included: author content is now escaped at every render point; TLS certificate verification is enforced on all Google Sheets and IIIF fetches; protected stories are hardened (the build stops rather than ship unencrypted, stronger key derivation, and no byline, description, or SEO leak); the upgrade workflow runs checksum-verified tooling in isolation; and all remote reads are capped with path-traversal guards. WaveSurfer is vendored so audio works offline, framework files install atomically, and several viewer, video, audio, and story-ordering bugs are fixed. None of this needs any action from you — see the CHANGELOG for the full list.

Recommended — update your GitHub Actions workflow files:

For security, GitHub does not allow the automated upgrade to modify workflow files, so two v1.5.0 hardening improvements are not applied for you:

To apply them, use the copy-from-Raw steps in the “Manual Setup for Earlier Versions” section below, once for each file. If you skip this, your site keeps building and deploying normally — these changes only harden your workflows.

If you update build.yml, also add package-lock.json. The new build.yml installs Node dependencies with npm ci, which requires a committed package-lock.json. Copy it from the Telar repository (open package-lock.json, click Copy raw contents) into your repository’s root, or the build will fail. New sites created from the template already include it.

Language pack — new protected-story sharing keys:

This release adds keys to the built-in language files (en.yml and es.yml) for the protected-story sharing warnings — the messages shown when a share link or embed code includes the access key. If you have a customized language file, re-apply your changes after upgrading by copying the new keys from the updated _data/languages/en.yml (or es.yml) in the Telar repository.

If you only use GitHub’s web interface:

The automated upgrade handles all framework file replacements. The workflow updates above are optional hardening; if you apply the build.yml update, remember the package-lock.json note.

v1.4.0 Upgrade Notes

v1.4.0 is a runtime-only upgrade. Existing stories, objects, and configuration continue to work unchanged — no CSV edits, no config changes, and no workflow updates are required.

Viewer change — Tify replaced by OpenSeadragon:

The IIIF image viewer has changed from Tify (loaded from a CDN) to a custom OpenSeadragon wrapper (vendored locally). For most sites this is invisible: IIIF images continue to display and zoom. If your site has a customized _sass/_viewer.scss that overrode Tify styles, those overrides are now inert and can be removed, but they will not break the build.

Language pack — six new object.viewer.* keys:

Six new keys are added to the built-in language files (en.yml and es.yml): object.viewer.prev_page, object.viewer.next_page, object.viewer.page_input_label, object.viewer.page_input_aria, object.viewer.image_unavailable_title, and object.viewer.image_unavailable_detail. These drive the multi-page pagination chrome and the error fallback UI in the new viewer.

If you have a customized language file (a copy of en.yml or es.yml with your own translations), you will need to add these six keys manually after upgrading, or the viewer pagination and error messages will fall back to the built-in English strings. Copy the values from the updated _data/languages/en.yml (or es.yml) in the Telar repository and translate as needed.

If you only use GitHub’s web interface:

No manual steps are required. The upgrade handles all file replacements automatically.

v1.3.0 Upgrade Notes

v1.3.0 fixes i18n coverage across the site and introduces a sister-file convention for localizing user pages. No CSV changes are required.

Automated content migration — hash-gated page rewrites:

The upgrade migration rewrites four user-content files (index.md, pages/glossary.md, pages/objects.md, telar-content/texts/pages/about.md) to use the new lang-key templates — but only if each file is byte-for-byte identical to the v1.2.1 default. Any customized content is preserved untouched. For Spanish-language sites whose about.md is unchanged from the v1.2.1 default, the migration also creates telar-content/texts/pages/acerca.md automatically.

New language keys — lang.index_page.welcome and lang.pages.glossary_intro:

Two new keys are added to the built-in language files. If you have a customized language file, you do not need to add them immediately — the layouts use fallback guards — but adding them gives you control over the homepage welcome text and glossary intro sentence in the site’s active language.

If you only use GitHub’s web interface:

No manual steps are required beyond reviewing the automatically created upgrade issue for any files flagged as not matching the default (meaning your customizations were detected and preserved).

v1.2.1 Upgrade Notes

v1.2.1 is a patch release. No manual steps are required.

The upgrade fixes a silent failure in the demo content fetch script that affected sites whose _config.yml carried a v-prefixed version string (e.g. version: "v1.2.0"). If your site showed no demo content after a previous upgrade, this patch resolves it. No config edits are needed; the fix is in the build script.

v1.2.0 Upgrade Notes

v1.2.0 adds a section table of contents, a Back to Start button, and in-story navigation. No manual steps are required.

All new features activate automatically. The section TOC is opt-in per story: add show_sections: yes to a story’s row in project.csv (or mostrar_secciones: si for Spanish-language sites) to display it. Sites without this column continue to work without any CSV changes.

If you only use GitHub’s web interface:

No action required.

v1.1.0 Upgrade Notes

v1.1.0 adds deep linking, title cards, collection mode, bibliography styling, and a share panel position tab. No manual steps are required.

Deep linking and the updated share panel activate automatically. Collection mode is opt-in: set collection_mode: true in _config.yml to switch the homepage layout. The default is false, so existing sites are unaffected. Title cards use existing CSV rows with an empty object field — no new columns required. Bibliography styling is a new markdown widget (:::bibliography) available in panel content.

If you only use GitHub’s web interface:

No action required.

v1.0.0-beta Upgrade Notes

v1.0.0-beta adds multimedia support (video and audio objects), an updated build pipeline, and renames the object_type CSV column to medium.

Manual step — update the build workflow:

The build.yml workflow has new steps for audio processing, Node.js setup, and JavaScript bundling. Copy the latest version from the Telar repository:

  1. Open build.yml on GitHub
  2. Click Copy raw contents
  3. In your repository, navigate to .github/workflows/build.yml and click Edit
  4. Select all and replace with the copied contents
  5. Commit the change

Manual step — install Node.js dependencies (local development only):

If you develop locally, run npm install in your repository after upgrading. This installs the JavaScript dependencies required by the new build pipeline (lenis, @vimeo/player, esbuild, vitest).

Optional — audio support:

If your site includes audio objects, install ffmpeg and audiowaveform for clip extraction and waveform peak data:

Sites without audio objects do not need these tools. GitHub Actions installs them automatically when audio files are detected.

Column rename — object_type to medium:

The object_type column in objects.csv has been renamed to medium. This change is backward compatible — the old column name is still accepted.

If you only use GitHub’s web interface:

v0.7.0 Upgrade Notes

v0.7.0 adds Node.js as a requirement for local development builds:

New requirement for local development:

If you develop locally:

  1. Install Node.js 18+ (nodejs.org)
  2. Run npm install in your repository to install JavaScript dependencies
  3. Then proceed with normal Jekyll commands

If you only use GitHub’s web interface:

Manual Setup for Earlier Versions

If your site is running v0.2.0 through v0.3.3, you’ll need to add the upgrade workflow files to your repository first. This is a one-time setup—after this, all future upgrades will be automated.

Step 1: Add the Upgrade Workflow File

You need to add two files to enable automated upgrades: the upgrade workflow and the updated build workflow. The upgrade workflow will automatically fetch all necessary scripts when it runs.

Work entirely in the browser without installing anything:

  1. Open the upgrade workflow in Telar:
  2. Create the file in your repository:
    • Go to your repository on GitHub
    • Click Add file → Create new file
    • Enter the file path: .github/workflows/upgrade.yml
    • Paste the copied contents
    • Scroll down and click Commit changes
    • Add commit message: “Add automated upgrade workflow”
    • Click Commit changes

Method B: Desktop/Local Development

If you have your repository cloned locally:

  1. Download the workflow file from Telar: 
    curl -o .github/workflows/upgrade.yml https://raw.githubusercontent.com/UCSB-AMPLab/telar/main/.github/workflows/upgrade.yml
  2. Commit and push: 
    git add .github/workflows/upgrade.yml
git commit -m "Add automated upgrade workflow"
git push

That’s it! The workflow automatically downloads the latest upgrade scripts from the Telar repository each time it runs, so you don’t need to copy any Python files manually.

Step 2: Replace the Build Workflow File

If you’re upgrading from v0.2.0 through v0.3.3, you also need to replace your .github/workflows/build.yml file with the latest version. This removes deprecated features (cron schedule and git push step) that are no longer needed in v0.3.4+.

Work entirely in the browser:

  1. Open the build workflow in Telar:
  2. Replace the file in your repository:
    • Go to your repository on GitHub
    • Navigate to .github/workflows/build.yml
    • Click the Edit button (pencil icon)
    • Select all content (Ctrl+A or Cmd+A) and delete
    • Paste the copied contents
    • Scroll down and click Commit changes
    • Add commit message: “Update build workflow to v0.3.4”
    • Click Commit changes

Method B: Desktop/Local Development

If you have your repository cloned locally:

  1. Download the workflow file from Telar: 
    curl -o .github/workflows/build.yml https://raw.githubusercontent.com/UCSB-AMPLab/telar/main/.github/workflows/build.yml
  2. Commit and push: 
    git add .github/workflows/build.yml
git commit -m "Update build workflow to v0.3.4"
git push

Optional Step: If you skip this step now, the upgrade summary will include instructions to update build.yml manually after your first upgrade. However, doing it now ensures a smoother upgrade experience.

Step 3: Run Your First Automated Upgrade

That’s all the setup needed! Now follow the Automated Upgrades instructions above to upgrade to the latest version.

The workflow will automatically:

  1. Download the latest upgrade scripts from the Telar repository
  2. Detect your current version
  3. Apply all necessary migrations
  4. Create a pull request with the upgraded files

Troubleshooting

Upgrade Workflow Not Appearing

Problem: The “Upgrade Telar” workflow doesn’t appear in the Actions tab.

Solution:

Upgrade Fails with Error

Problem: The upgrade workflow fails with an error message.

Solution:

Issue Not Created

Problem: The upgrade completes but no issue is created.

Solution:

Merge Conflicts

Problem: The upgrade PR has merge conflicts.

Solution:

Version History

For a complete list of changes in each version, see the Changelog in the Telar repository.

Need Help?