README.adoc

CalConnect public website

This is the source code for the CalConnect public website, hosted at https://www.calconnect.org.

Purpose

This repository contains the source code for the official website of The Calendaring and Scheduling Consortium (CalConnect), a standards development organization for vendors and users of calendaring, scheduling, and collaboration systems.

The site serves multiple audiences:

• Standards developers — Technical documentation, specifications, TC work

• Product managers — Understanding CalConnect standards and implementations

• Potential members — Membership information and application

• The calendaring community — News, events, and resources

Site information architecture

Content hierarchy

The site is organized into five main sections:

Section	Description	URL
About	Organization structure, history, technical committees, policies, liaisons	/about/
Membership	Membership benefits, categories, application, fees, member list	/membership/
Events	Conferences, workshops, virtual events (past and upcoming)	/events/
News	Announcements, press releases, industry news	/news/
Resources	Standards documentation, guides, discussion lists, technical resources	/resources/

Jekyll collections

The site uses Jekyll collections to organize content:

Collection	Directory	Permalink	Purpose
posts	_posts/	/news/:year-:month-:day-:title/	News articles and press releases
events	_events/	/events/:title	Conference and event pages
about_pages	_about_pages/	/about/:title	About section pages (TCs, history, policies)
membership_pages	_membership_pages/	/membership/:title	Membership section pages
event_pages	_event_pages/	/events/:title	Event-related info (calendars, fees)
resources	_resources/	(default)	Documentation and guides
pages	_pages/	/:path/	Landing pages for each section

Navigation structure

Navigation is data-driven via YAML files in _data/:

• _data/navigation_main.yml — Header navigation with dropdowns

• _data/navigation_sidebar.yml — Section-specific sidebar navigation

Code architecture

Technology stack

The site is built with Jekyll 4.3 for static content generation, with Vite for frontend asset bundling.

Architecture overview

┌──────────────────────────────────────────────────────┐
│                     Jekyll 4.3                       │
│  (Static site generator - Ruby)                      │
│                                                      │
│  • Processes Markdown, AsciiDoc, HTML templates      │
│  • Integrates with Vite for frontend assets          │
│  • Output: _site/ directory                          │
└──────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────┐
│                      Vite 7.x                        │
│  (Frontend bundler - Node.js)                        │
│                                                      │
│  • Vue 3 components (client-side search)             │
│  • Tailwind CSS 4 styling                            │
│  • Output: public/vite/assets/                       │
└──────────────────────────────────────────────────────┘

Directory structure

.
├── _config.yml              # Jekyll configuration
├── _data/                   # YAML data files
│   ├── navigation_main.yml  # Header navigation
│   ├── navigation_sidebar.yml # Sidebar navigation
│   └── members.yml          # Member organizations
├── _frontend/               # Frontend source (Vite/Vue/Tailwind)
│   └── entrypoints/
│       ├── application.js   # Vue application entry
│       └── application.css  # Tailwind CSS entry
├── _includes/               # Jekyll partials
│   ├── head.html            # Document head
│   ├── header.html          # Site header
│   ├── footer.html          # Site footer
│   └── news-card.html       # News card component
├── _layouts/                # Page templates
│   ├── base.html            # Foundation (all pages)
│   ├── default.html         # Content pages (sidebar)
│   ├── home.html            # Homepage
│   └── page.html            # Simple content wrapper
├── _pages/                  # Landing pages
├── _posts/                  # News articles
├── _events/                 # Event pages
├── _about_pages/            # About section pages
│   └── technical-committees/ # TC subpages
├── _membership_pages/       # Membership pages
├── _event_pages/            # Event info pages
├── _resources/              # Resource pages
├── assets/                  # Static assets
│   ├── images/              # Images
│   └── css/                 # Additional stylesheets
├── public/                  # Vite output (gitignored)
├── publications/            # PDF publications
├── index.html               # Homepage
├── package.json             # Node dependencies
├── vite.config.ts           # Vite configuration
├── Gemfile                  # Ruby dependencies
└── Rakefile                 # Build tasks

Layout hierarchy

base.html (foundation)
├── default.html (sidebar + content)
│   ├── page.html (simple wrapper)
│   ├── news-year.html (news by year)
│   └── news-category.html (news by category)
└── home.html (homepage)

Prerequisites

• Ruby 3.3 (or compatible version)

• Node.js 18+ (for Vite)

• Bundler (Ruby gem manager)

• npm (Node package manager)

Installation

1. Install Ruby dependencies

bundle install

2. Install Node.js dependencies

npm install

Development

Start development server

bundle exec jekyll serve

Access the site at http://127.0.0.1:4000

The server automatically: * Rebuilds when content changes * Reloads Vite assets on modification * Enables live browser refresh

Production build

JEKYLL_ENV=production bundle exec jekyll build

Output is written to _site/.

Common maintenance tasks

Add a news post

1. Create a new file in _posts/ named YYYY-MM-DD-slug.adoc

2. Add the required front matter:

---
layout: page
title: Your Post Title
date: YYYY-MM-DD
type: news
categories: announcements press-releases
excerpt: |
  Brief summary for listings.
---

1. Write content in AsciiDoc or Markdown below the front matter

2. Rebuild the site

Available categories: announcements, press-releases, the-world-of-calendaring, general-information, current-events, member-news, member-focus, special-focus

Add or update an event

1. Create or edit a file in _events/

2. Use front matter:

---
layout: page
title: CalConnect Event Name
date: YYYY-MM-DD
host_info: Host information
image: /assets/images/event-image.jpg
---

1. Event pages appear automatically in /events/ listing

Add or update a Technical Committee page

TC pages are in _about_pages/technical-committees/:

1. Navigate to _about_pages/technical-committees/

2. Create or edit the appropriate .adoc file

3. Use front matter:

---
layout: page
title: TC Name
type: about
---

1. Update the sidebar navigation in _data/navigation_sidebar.yml if needed

Add or update a liaison

1. Edit _about_pages/liaisons-and-relationships.adoc

2. Add liaison information in the appropriate section

3. Include logo in assets/images/external-logos/ if needed

Update navigation

Header navigation

Edit _data/navigation_main.yml:

- label: Section Name
  url: /section/
  children:
    - label: Subpage
      url: /section/subpage/

Sidebar navigation

Edit _data/navigation_sidebar.yml:

- label: Section Name
  url: /section/
  items:
    - label: Page
      url: /section/page/

Update member list

Edit _data/members.yml:

- name: Organization Name
  url: https://example.org
  logo: logo-filename.png
  type: corporate

Logos are stored in assets/images/member-logos/.

Frontend development

Vue components

The site uses Vue 3 for interactive components (e.g., news search). Vue components are located in _frontend/entrypoints/.

Important

Vue components must use render functions instead of template strings. This is required for Vite compatibility.

Example Vue component structure

import { createApp, h } from 'vue'

const MyComponent = {
  render() {
    return h('div', { class: 'example' }, 'Hello')
  }
}

Tailwind CSS

Tailwind CSS 4 is used for styling. Custom styles are defined in:

• _frontend/entrypoints/application.css - Main entry point

• Layout <style> blocks - Component-specific styles

Adding new Vue components

1. Create the component in _frontend/entrypoints/

2. Import it in application.js

3. Use createApp() to mount it to a DOM element

Troubleshooting

Assets not rebuilding

Clear caches and rebuild:

rm -rf .jekyll-cache/vite public/vite
npx vite build
bundle exec jekyll build

Vue components not rendering

Ensure components use render functions, not template strings.

Missing content in navigation

Check _data/navigation_sidebar.yml — items must be declared explicitly (except collection items which auto-generate).

Ruby version issues

Use a Ruby version manager (rbenv, rvm, or asdf) to install Ruby 3.3.

rbenv install 3.3.0
rbenv local 3.3.0

Node version issues

Use nvm to manage Node.js versions:

nvm install 18
nvm use 18

Deployment

The site deploys automatically to GitHub Pages when changes are pushed to main.

CI/CD pipeline (.github/workflows/):

1. bundle exec jekyll build - Production build

2. Lychee link checker - Validates internal links

3. Deploys to GitHub Pages

Copyright and licensing

Copyright The Calendaring and Scheduling Consortium. All rights reserved.