VFX Reference Platform Web Site

This repo hosts the VFX Reference Platform web site hosted at https://vfxplatform.com. Optionally, major changes can be deployed to a staging site at https://ves-tech.github.io/vfxplatform-staging/ for review before pushing to production.

Introduction

This website is built using Jekyll, a static site generator. Unlike traditional HTML websites where you edit HTML files directly, this site uses a data-driven architecture:

Content lives in simple text files (YAML format) in the _data/ folder
Templates automatically generate HTML from these data files
Most updates require no code changes — just edit the relevant data file

This approach makes content updates straightforward: find the right file, edit the text, and push to main. The site rebuilds automatically using the Github Actions workflow defined in .github/workflows.

Quick Start

Making Updates

For most content updates:

Edit the relevant YAML file in _data/ (see Common Tasks below)
Commit and push to the main branch
GitHub Actions automatically builds and deploys the site
Changes appear live within a few minutes

Local Development (Optional)

If you want to preview changes before pushing, you can run the site locally.

Prerequisites:

Node.js (v18 or later)
Ruby (v3.0 or later)

Installation:

npm install && bundle install

Running locally:

npm run dev

This starts the site at http://localhost:4000 with live reload — changes to files automatically refresh the browser.

Site Architecture

All site content is driven by YAML data files in the _data/ folder. Here's what each file controls:

_data/
├── platforms/           # Platform specifications (one file per year)
│   ├── CY2014.yml
│   ├── CY2015.yml
│   ├── ...
│   └── CY2026.yml
├── components.yml       # Component metadata and categories
├── faq.yml              # FAQ questions and answers
├── footer.yml           # Footer content (description, resources, contact)
├── navigation.yml       # Main navigation menu links
├── notes.yml            # Technical footnotes referenced from platform data
├── status_updates.yml   # Status updates shown on the homepage
└── useful_links.yml     # Useful links shown as cards on the homepage

Key point: You rarely need to touch HTML templates. Almost all routine updates involve editing these YAML files.

Interactive features: The platform table supports collapsible category sections — users can click any category header (Linux, macOS, Windows, Components) to collapse/expand its rows. Collapsed state is remembered across visits via localStorage.

Common Tasks

Adding a Status Update

Status updates appear on the homepage to announce new platform versions, drafts, and other news.

File: _data/status_updates.yml

Add new entries at the TOP of the updates: list (newest first):

updates:
  - date: "2025-11-05"
    display_date: "5th November 2025"
    content: |
      CY2026 is now Final and will be effective from January 1st. All package
      versions called out by the platform are now released.

  - date: "2025-05-07"
    display_date: "7th May 2025"
    content: |
      CY2026 Draft published. We are currently soliciting feedback...

Required fields:

date: Used for sorting (format: YYYY-MM-DD). Add a letter suffix like 2024-09-02b if multiple updates on the same day.
display_date: Human-readable date shown on the site
content: The update text. Use | for multi-line content. Markdown formatting is supported (links, bold, etc.)

Adding a New Platform Year

When a new calendar year's platform is announced, create a new data file.

Step 1: Create a new file _data/platforms/CY[YEAR].yml

Copy the structure from the previous year's file as a starting point:

year: 2027
status: draft
last_updated: "2026-05-15"

linux:
  gcc:
    version: "14.2"
    min_max: true
  glibc:
    version: "2.28"
    min_max: true

macos:
  deployment_target:
    version: "14.0"
    note: footnote-macos

windows:
  visual_studio:
    version: "Visual Studio 2022 v17.6 or later"
  sdk:
    version: "10.0.22621 or later"

components:
  python:
    version: "3.13.x"
  qt:
    version: "6.8.x"
  # ... (copy all components from previous year)

Step 2: Update the site configuration

Edit _config.yml to set the new current year:

current_year: 2027

Status values:

draft — Platform is under development, not yet finalized
final — Platform is locked and effective

Updating Component Versions

To update a version number for any component (Python, Qt, OpenEXR, etc.):

File: _data/platforms/CY[YEAR].yml

Find the component and change its version:

components:
  python:
    version: "3.13.x"      # Change this line
  qt:
    version: "6.8.x"

Optional fields for components:

components:
  onetbb:
    version: "2022.x"
    min_max: true           # Displays as "minimum/maximum" instead of exact version
    note: footnote-tbb      # References a footnote from notes.yml
    inline_note: "See migration guide"  # Short note displayed inline

Adding/Editing Notes (Footnotes)

Notes provide detailed explanations that appear as expandable footnotes, linked from platform tables.

File: _data/notes.yml

Structure:

notes:
  - id: footnote-macos
    title: "Notes - macOS"
    from_year: 2018
    content: |
      **Minimum Deployment Target in Xcode**

      Xcode's "Deployment Target" identifies the earliest OS version...

      More information is [available here](https://example.com).

  - id: footnote-gcc9
    title: "Note - gcc 9 and 11"
    from_year: 2021
    to_year: 2024
    content: |
      For users of Red Hat Enterprise Linux...

Fields:

id: Unique identifier referenced by note: in platform data
title: Heading displayed for the footnote
from_year: First platform year this note applies to (inclusive)
to_year: Last platform year this note applies to (inclusive, optional)
content: Markdown-formatted content

Referencing a note from platform data:

macos:
  deployment_target:
    version: "14.0"
    note: footnote-macos    # Must match an id in notes.yml

Year filtering: Notes only appear for platform years within their from_year/to_year range. If to_year is omitted, the note applies to all years from from_year onward.

Adding FAQ Entries

File: _data/faq.yml

Add new questions to the questions: list:

questions:
  - id: my-new-question
    question: "What is the VFX Reference Platform?"
    answer: |
      The VFX Reference Platform is a set of version guidelines...

      For more information, see the [About page](/about/).

Fields:

id: Unique identifier (used for anchor links)
question: The question text
answer: Markdown-formatted answer (use | for multi-line)

Editing Homepage Content

The homepage uses a dedicated home layout (different from other pages) that allows full-width sections like the hero. Content is structured into sections:

Hero section — Title, subtitle, and call-to-action buttons. The hero text is configured in _config.yml under the hero: key:

hero:
  subtitle: "A standardized set of tool and library versions..."
  cta_primary_text: "View Latest Platform"
  cta_primary_url: "#reference-platform"
  cta_secondary_text: "Join Discussion"
  cta_secondary_url: "https://groups.google.com/g/vfx-platform-discuss"

Current Status — Shows the latest 4 status updates as cards (data from _data/status_updates.yml)
Reference Platform — The main version specs table (data from _data/platforms/)
Support Guidance — Two cards describing support window and best practices

Useful Links — Card grid driven by _data/useful_links.yml:

- title: "Link Title"
  url: "https://example.com"
  description: "Brief description of the link."
  icon: "chart"   # Options: chart, python, container, grid, matrix

Editing Footer Content

File: _data/footer.yml

The footer displays across all pages with three columns: about, resources, and contact.

description: "Site description text..."

resources:
  - title: "Discussion Group"
    url: "https://groups.google.com/g/vfx-platform-discuss"
  - title: "Academy Software Foundation"
    url: "https://www.aswf.io/"

contact_email: "feedback@vfxplatform.com"
collaboration_text: "Updated annually in collaboration with..."

Modifying Navigation

File: _data/navigation.yml

The main navigation menu is a simple list:

main:
  - title: Home
    url: /
  - title: History
    url: /platform_history.html
  - title: Compare
    url: /compare.html
  - title: Linux
    url: /linux/
  - title: FAQ
    url: /FAQ/
  - title: About
    url: /about/

Add, remove, or reorder items as needed. URLs can be:

Relative paths (/about/)
Full URLs (https://example.com)

Deployment

Deployment is fully automated via GitHub Actions.

How It Works

Push changes to the main branch
GitHub Actions automatically:
- Builds Tailwind CSS
- Builds the Jekyll site
- Deploys to GitHub Pages
Changes appear live within a few minutes

Checking Deployment Status

Go to the GitHub repository
Click the Actions tab
Look for the latest "Deploy Jekyll with Tailwind" workflow run
Green checkmark = success, Red X = failure

Staging

For major changes, you can deploy to a staging site for review before pushing to production.

Staging URL: https://ves-tech.github.io/vfxplatform-staging/

How to use:

Create or switch to the staging branch:
```
git checkout -b staging
```
Make your changes and push:
```
git push -u origin staging
```
GitHub Actions automatically builds and deploys to the staging URL
Share the staging URL with other maintainers for review
Once approved, merge your changes into main to deploy to production

Notes:

The staging site updates on every push to the staging branch
You can also trigger a staging deploy manually from the Actions tab ("Deploy to Staging" workflow)

Syncing Branches

Deploy latest production content to staging (for review):

git checkout staging
git merge main
git push origin staging

Promote staging changes to production:

git checkout main
git merge staging
git push origin main

If the staging branch doesn't exist yet locally:

git checkout -b staging
git push -u origin staging

SEO & Discoverability

The site includes several SEO features that work automatically:

robots.txt

The robots.txt file at the site root tells search engines they can crawl all pages and provides the sitemap location. This file rarely needs changes.

Structured Data (Schema.org)

The site uses JSON-LD structured data to help search engines understand the content:

Organization Schema (_includes/head.html): Included on every page, identifies the site as an organization
FAQ Schema (FAQ/index.html): Enables rich FAQ snippets in search results by marking up Q&A content

These schemas are generated automatically from the site's data files. No manual updates needed.

Validating Structured Data

To verify structured data is working correctly:

Go to Google's Rich Results Test
Enter the page URL (e.g., https://vfxplatform.com/FAQ/)
Check that FAQ or Organization schemas are detected without errors

Sitemap

Jekyll automatically generates a sitemap at /sitemap.xml via the jekyll-sitemap plugin. This is referenced in robots.txt for search engines.

YAML Syntax Reference

YAML is a human-readable data format. Here are the key rules:

Indentation

Use spaces, not tabs. Indentation indicates structure:

parent:
  child: value        # 2 spaces indent
  another_child:
    grandchild: value # 4 spaces indent

Strings

Plain strings usually don't need quotes:

version: 3.13.x
title: Home

Use quotes when the string contains special characters (colons, quotes, etc.):

version: "Visual Studio 2022 v17.6 or later"
display_date: "5th November 2025"

Multi-line Text

Use | to preserve line breaks:

content: |
  This is the first paragraph.

  This is the second paragraph with a [link](https://example.com).

  - Bullet point one
  - Bullet point two

Lists

# Simple list
items:
  - first item
  - second item

# List of objects
updates:
  - date: "2025-01-01"
    content: First update
  - date: "2025-02-01"
    content: Second update

Common Mistakes

Mistake	Problem	Fix
Using tabs	YAML requires spaces	Convert tabs to spaces (2-space indent)
Missing quotes	Special characters break parsing	Wrap in quotes: `"value: with colon"`
Wrong indentation	Breaks structure	Align child items under parent
Trailing spaces	Can cause issues	Remove whitespace at end of lines

Configuration Reference

File: _config.yml

Key settings you might need to change:

# The current/active platform year (shown as default in tables)
current_year: 2026

# Number of years shown in main tables (older years shown on history pages)
supported_years_count: 4

Other settings:

title: Site title
description: Site description for SEO
url: Production site URL
hero: Homepage hero section text and CTA buttons (subtitle, button labels, URLs)

Important: After changing _config.yml, you must restart the local Jekyll server to see changes.

Troubleshooting

"The site doesn't update after I push"

Check GitHub Actions for build errors (see Deployment)
Hard refresh your browser (Ctrl+Shift+R / Cmd+Shift+R)
Wait a few more minutes — sometimes CDN caching causes delays

"YAML syntax error"

Use an online YAML validator like YAML Lint to check your file. Common fixes:

Ensure consistent 2-space indentation
Add quotes around strings with special characters
Check for missing colons after keys

"My note isn't appearing"

Verify the id in notes.yml matches the note: reference in the platform file
Check that the platform year falls within the note's from_year/to_year range
Ensure proper indentation in the platform file

"Local server won't start"

# Reinstall dependencies
rm -rf node_modules
npm install
bundle install

# Try running again
npm run dev

"CSS changes aren't showing"

The CSS is built from Tailwind. If running locally:

# In one terminal
npm run watch:css

# In another terminal
bundle exec jekyll serve --livereload

Or just use npm run dev which runs both.

Getting Help

For questions about content updates or site maintenance, email feedback [at] vfxplatform.com.

For technical issues with Jekyll or the build process, refer to:

Name		Name	Last commit message	Last commit date
Latest commit History 96 Commits
.github/workflows		.github/workflows
FAQ		FAQ
_data		_data
_includes		_includes
_layouts		_layouts
about		about
assets		assets
linux		linux
.claudeignore		.claudeignore
.gitignore		.gitignore
404.html		404.html
CLAUDE.md		CLAUDE.md
CNAME		CNAME
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
README.md		README.md
_config.yml		_config.yml
compare.html		compare.html
component.html		component.html
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
platform_history.html		platform_history.html
postcss.config.js		postcss.config.js
robots.txt		robots.txt
tailwind.config.js		tailwind.config.js

ves-tech/vfxplatform

Folders and files

Latest commit

History

Repository files navigation

VFX Reference Platform Web Site

Table of Contents

Introduction

Quick Start

Making Updates

Local Development (Optional)

Site Architecture

Common Tasks

Adding a Status Update

Adding a New Platform Year

Updating Component Versions

Adding/Editing Notes (Footnotes)

Adding FAQ Entries

Editing Homepage Content

Editing Footer Content

Modifying Navigation

Deployment

How It Works

Checking Deployment Status

Staging

Syncing Branches

SEO & Discoverability

robots.txt

Structured Data (Schema.org)

Validating Structured Data

Sitemap

YAML Syntax Reference

Indentation

Strings

Multi-line Text

Lists

Common Mistakes

Configuration Reference

Troubleshooting

"The site doesn't update after I push"

"YAML syntax error"

"My note isn't appearing"

"Local server won't start"

"CSS changes aren't showing"

Getting Help

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 7

Uh oh!

Languages

Packages