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.

Table of Contents

1. Introduction
2. Quick Start
3. Site Architecture
4. 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
5. Deployment
   • Staging
6. SEO & Discoverability
7. YAML Syntax Reference
8. Configuration Reference
9. Troubleshooting

---

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:

1. Edit the relevant YAML file in _data/ (see Common Tasks below)
2. Commit and push to the main branch
3. GitHub Actions automatically builds and deploys the site
4. 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:

1. 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"
   

2. Current Status — Shows the latest 4 status updates as cards (data from _data/status_updates.yml)

3. Reference Platform — The main version specs table (data from _data/platforms/)

4. Support Guidance — Two cards describing support window and best practices

5. 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: