Migrate DEVGUIDE from Materialize to Tailwind CSS via calconnect-theme gem

- Replace Materialize CSS + jQuery with Tailwind CSS v4 + Vite
- Adopt calconnect-theme gem for shared layouts, includes, SCSS, and JS
- Rewrite all layouts and includes with Tailwind utility classes
- Add Vite/Node.js tooling (package.json, vite.config.ts, postcss.config.js)
- Create _frontend/ with Tailwind entrypoints, theme.js, navigation.js
- Delete vendored Materialize CSS, jQuery, Roboto fonts
- Update CI workflows with Node.js setup and calconnect-theme checkout
- Rename default branch from master to main

Author: ronaldtse

.github/workflows/build_deploy.yml

@@ -3,8 +3,7 @@ name: build_deploy
 on:
   push:
     branches:
-    - master
-    # - staging
+    - main
   pull_request:
   repository_dispatch:
   workflow_dispatch:
@@ -28,12 +27,27 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Checkout calconnect-theme
+        uses: actions/checkout@v4
+        with:
+          repository: calconnect/calconnect-theme
+          path: ../calconnect-theme
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - name: Install npm dependencies
+        run: npm ci
+
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: '3.2'
           bundler-cache: true
-          cache-version: 0 # Increment this number if you need to re-download cached gems
+          cache-version: 0
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v3
@@ -53,7 +67,7 @@ jobs:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    if: ${{ github.ref == 'refs/heads/master' }}
+    if: ${{ github.ref == 'refs/heads/main' }}
     runs-on: ubuntu-latest
     needs: build
     steps:

.github/workflows/links.yml

@@ -11,11 +11,26 @@ jobs:
   link_checker:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
+
+    - name: Checkout calconnect-theme
+      uses: actions/checkout@v4
+      with:
+        repository: calconnect/calconnect-theme
+        path: ../calconnect-theme
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v6
+      with:
+        node-version: '24'
+        cache: 'npm'
+
+    - name: Install npm dependencies
+      run: npm ci
 
     - uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.1'
+        ruby-version: '3.2'
         bundler-cache: true
 
     - name: Build site
@@ -30,10 +45,3 @@ jobs:
         fail: true
       env:
         GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
-
-      # - name: Create Issue From File
-      #   uses: peter-evans/create-issue-from-file@v2
-      #   with:
-      #     title: Link Checker Report
-      #     content-filepath: ./lychee/out.md
-      #     labels: report, automated issue

.gitignore

@@ -8,4 +8,10 @@
 js/jquery.min.2.1.js
 js/jquery.min.3.7.js
 /firebase-debug.log
-Gemfile.lock
+Gemfile.lock
+
+# Vite / Node
+node_modules/
+public/vite*
+config/
+vendor/

CLAUDE.md

@@ -0,0 +1,115 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CalConnect DEVGUIDE is a Jekyll-based static site providing a developer's guide for calendaring and scheduling standards (iCalendar, CalDAV, CardDAV, vCard, jsCalendar, iTIP, iMIP). The live site is at https://devguide.calconnect.org.
+
+Uses the shared `calconnect-theme` gem for layouts, includes, and design tokens. The theme provides Tailwind CSS v4 via Vite, dark mode support, and documentation sidebar styling.
+
+## Build & Serve Commands
+
+- **Install dependencies:** `bundle install && npm ci`
+- **Build the site:** `bundle exec jekyll build`
+- **Local dev server:** `bundle exec jekyll serve`
+- **Build for production:** `JEKYLL_ENV=production bundle exec jekyll build`
+
+Ruby 3.2, Node.js 24. Jekyll 4.3 with jekyll-vite plugin.
+
+## Deployment
+
+- **GitHub Actions** builds and deploys to GitHub Pages on push to `master`
+- **Firebase** hosting config exists in `firebase.json` (redirect rules)
+- The `_site/` directory is the build output (gitignored)
+
+## Site Architecture
+
+### Theme
+
+Uses `calconnect-theme` gem (at `../calconnect-theme/`). The theme provides:
+- **Layouts**: `base` (HTML shell), `default` (documentation sidebar), `page` (simple wrapper)
+- **Includes**: `head.html` (fonts, critical CSS, Vite), `header.html`/`footer.html` (stubs), `breadcrumbs.html`, `feedback.html`, `google-analytics.html`
+- **SCSS**: `_sass/calconnect/` partials for documentation layout, sidebar nav, typography, dark mode
+- **Frontend JS**: `theme.js` (dark/light toggle), `navigation.js` (mobile menu)
+- **Assets**: Logo SVGs (purple/white)
+
+Local `_layouts/` and `_includes/` files override the theme.
+
+### Content Collections
+
+Two Jekyll collections drive the site:
+
+- **`pages`** (`_pages/`) — Main content sections. Each top-level section has an index `.md` file and a subdirectory with child pages. Permalink: `/:path/`
+- **`appendixes`** (`_appendixes/`) — Supplementary content (Glossary, Standards, Links, Examples). Permalink: `/Appendix/:path/`
+
+### Page Front Matter (Navigation)
+
+- `parent` — Path to parent page (e.g., `"/"` for top-level, `"/iCalendar-Topics"` for children)
+- `order` — Sort order within siblings
+- `mainParent` — Groups pages under a top-level section for sidebar display
+- `parents` — Semicolon-separated breadcrumb trail in `Title:URL` format
+- `childs` — Comma-separated list of child page titles (for active-state highlighting)
+- `layout` — `default`, `page`, `home`, `toc`, `toc-type`, `post`
+
+### Layouts
+
+- `default` → theme's `base` (head, header, main, footer, Vite JS)
+- `page` → `default` (simple max-width container)
+- `home` → `default` (landing page with hero and icon grid)
+- `toc` → `default` (Table of Contents with hierarchical listing)
+- `toc-type` → `default` (section landing page with breadcrumb, content, and sidebar)
+- `post` → `default` (blog-style article)
+
+### CSS / Frontend
+
+- **Tailwind CSS v4** via Vite + jekyll-vite
+- Entry point: `_frontend/entrypoints/application.css` (Tailwind + `@theme` design tokens)
+- JS entry: `_frontend/entrypoints/application.js` (imports theme.js + navigation.js)
+- Fonts: Inter (body) + JetBrains Mono (code), loaded via Google Fonts
+- Dark mode: class-based (`html.dark`), toggled via `theme.js` with localStorage
+
+### Includes
+
+- `head.html` — Overrides theme: DEVGUIDE-specific title and favicon
+- `header.html` — Overrides theme: DEVGUIDE nav links + dark mode toggle
+- `footer.html` — Overrides theme: DEVGUIDE page/appendix links
+- `script.html` — GA4 tracking (production only)
+- `toc-sidebar.html` — Recursive sidebar navigation (front-matter-driven)
+- `toc-entry.html` — Recursive ToC entry renderer
+- `toc-mainPage-placeholder.html` — Renders child links for section landing pages
+
+### Plugin: PlantUML
+
+`_plugins/jekyll-plantuml.rb` provides a `{% plantuml %}` Liquid tag that generates SVG diagrams using `_bin/plantuml.jar`.
+
+## Content Structure
+
+Top-level sections (each is a `_pages/*.md` index + subdirectory):
+
+| Section | Topics |
+|---|---|
+| iCalendar Topics | Best Practices, Dates/Times, History, Recurrences, Validation |
+| CalDAV | Client/Server implementations, libraries, building clients, FAQs |
+| CardDAV | Client implementations |
+| Scheduling | FreeBusy, iTIP, vAvailability, vPoll |
+| Tasks | Introduction, Component |
+| Time Zones | Best Practices, Sources, TZDS |
+| Data Model | Simple Event, UID, Detailed Description |
+| vCard | vCard 4, vCard 5 |
+| jsCalendar Topics | Introduction, Implementations |
+| iMIP | Internet Scheduling |
+| iTIP | iTIP scheduling |
+| Publishing | Publishing calendars |
+| Other Topics | Calendar spam |
+
+## CI Workflows
+
+- **`build_deploy`** — Builds with Jekyll + Vite and deploys to GitHub Pages on push to `master`
+- **`links`** — Runs lychee link checker on built `_site/` HTML
+
+## Conventions
+
+- Content files are Markdown (`.md`) with YAML front matter
+- 2-space indentation, LF line endings, UTF-8 encoding (`.editorconfig`)
+- Pages with `published: false` in front matter are excluded from navigation

Gemfile

@@ -1,36 +1,21 @@
 source "https://rubygems.org"
-# Hello! This is where you manage which Jekyll version is used to run.
-# When you want to use a different version, change it below, save the
-# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
-#
-#     bundle exec jekyll serve
-#
-# This will help ensure the proper Jekyll version is running.
-# Happy Jekylling!
+
 gem "jekyll", "~> 4.3.4"
-# This is the default theme for new Jekyll sites. You may change this to anything you like.
-gem "minima", "~> 2.5"
-# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
-# uncomment the line below. To upgrade, run `bundle update github-pages`.
-# gem "github-pages", group: :jekyll_plugins
-# If you have any plugins, put them here!
+gem "calconnect-theme", path: "../calconnect-theme"
+
 group :jekyll_plugins do
   gem "jekyll-feed", "~> 0.12"
   gem "jekyll-asciidoc"
+  gem "jekyll-vite"
 end
 
-# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
-# and associated library.
+gem "jekyll-archives"
+
 platforms :mingw, :x64_mingw, :mswin, :jruby do
   gem "tzinfo", ">= 1", "< 3"
   gem "tzinfo-data"
 end
 
-# Performance-booster for watching directories on Windows
 gem "wdm", "~> 0.1", :platforms => [:mingw, :x64_mingw, :mswin]
 
-# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
-# do not have a Java counterpart.
 gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]
-gem 'jekyll-archives'
-gem "jekyll-sass-converter", "~> 2.0"

TODO.new-style/01-push-calconnect-theme-to-github.md

@@ -0,0 +1,9 @@
+# 01 - Push calconnect-theme to GitHub
+
+Create the GitHub repo and push the initial commit.
+
+```bash
+cd /Users/mulgogi/src/calconnect/calconnect-theme
+gh repo create calconnect/calconnect-theme --public --description "Shared Jekyll theme gem for CalConnect sites"
+git push -u origin main
+```

TODO.new-style/02-update-devguide-default-branch.md

@@ -0,0 +1,8 @@
+# 02 - Update DEVGUIDE default branch to main
+
+Change the default branch from `master` to `main` and update workflows to reference `main`.
+
+**Files:**
+- `.github/workflows/build_deploy.yml` — change trigger branch `master` → `main`, change deploy condition `refs/heads/master` → `refs/heads/main`
+- `.github/workflows/links.yml` — already uses `main` (verify)
+- Update remote HEAD: `git push origin main && git remote set-head origin main`

TODO.new-style/03-migrate-standards-calconnect-org.md

@@ -0,0 +1,65 @@
+# 03 - Migrate standards.calconnect.org to Tailwind/Vite
+
+Full migration from Materialize CSS to shared calconnect-theme with Tailwind/Vite.
+
+## Node.js tooling to create
+
+| File | Source |
+|---|---|
+| `package.json` | Same as DEVGUIDE (no Vue deps) |
+| `vite.config.ts` | Same as DEVGUIDE (no Vue plugin) |
+| `postcss.config.js` | Copy from DEVGUIDE |
+| `config/vite.json` | Copy from DEVGUIDE (use port 3038) |
+| `_frontend/entrypoints/application.css` | Tailwind v4 with standards-specific `@source` paths + doc-type/stage color `@theme` tokens |
+| `_frontend/entrypoints/application.js` | Copy from DEVGUIDE |
+| `_frontend/js/theme.js` | Copy from calconnect-theme |
+| `_frontend/js/navigation.js` | Copy from calconnect-theme |
+
+## Config updates
+
+- `Gemfile`: add `calconnect-theme` (path:), add `jekyll-vite`, remove `minima`, `rubocop`
+- `_config.yml`: set `theme: calconnect-theme`, add vite/node excludes
+
+## Layouts to rewrite
+
+| Layout | What to do |
+|---|---|
+| `default.html` | Replace with `layout: base` + `{{ content }}` |
+| `document.html` | Keep Liquid logic, replace Materialize classes with Tailwind |
+| `toc-type.html` | Same as DEVGUIDE: Materialize → `.documentation`/`.docs-nav`/`.nav-items` |
+| `toc.html` | `container` → `max-w-4xl mx-auto` |
+| `page.html` | `container` → `max-w-4xl mx-auto py-8 px-4` |
+
+## Includes to rewrite
+
+| Include | What to do |
+|---|---|
+| `head.html` | Replace with Inter/JetBrains Mono, critical CSS, `{% vite_stylesheet_tag %}` |
+| `header.html` | Materialize nav → Tailwind glass navbar with standards links + dark mode toggle |
+| `footer.html` | Materialize footer → Tailwind grid footer |
+| `script.html` | jQuery/Materialize/init.js → `{% vite_javascript_tag %}` + GA |
+| `document.html` | Keep Liquid logic, replace CSS classes for type badges/stage badges/download buttons |
+| `toc-sidebar.html` | `menu-sidebar` → `nav-items` etc. |
+| `find-doc.html` | Update CSS classes |
+| `copyright.html` | Update CSS classes |
+
+## Doc-type/stage colors
+
+Extract from `_sass/_main.scss` SCSS maps and express as Tailwind `@theme` tokens in `application.css`:
+- standard: #0AC442, directive: #540D6E, guide: #D183C9, specification: #65AFFF, report: #3A405A, amendment: #F26430, corrigendum: #C84630, administrative: #BFAE48, advisory: #BD9391
+- proposal: #39A0ED, working-draft: #2D7393, committee-draft: #2A6B7C, draft-standard: #1C7F7A, final-draft: #53C170, published: #069E2D, withdrawn: #004E64, cancelled: #2E382E
+
+## Files to delete
+
+- `_sass/materialize/` (entire directory)
+- `_sass/main.scss`, `_sass/_main.scss`, `_sass/_metanorma-index.scss`
+- `assets/materialize.scss`, `assets/main.scss`, `assets/metanorma-index.scss`
+- `js/jquery.min.js`, `js/materialize.min.js`, `js/init.js`
+- `fonts/roboto/` (if exists)
+
+## Preserve untouched
+
+- `Makefile`, `scripts/`, `src-documents/`, `bib/`, `bibcoll/`, `csd/`, `_input/`
+- `flake.nix`, `flake.lock`, `.envrc`
+- `_data/` (doesn't exist — navigation is hardcoded)
+- CI workflow (`.github/workflows/build_deploy.yml`) — add Node.js setup step

TODO.new-style/04-integrate-theme-into-calconnect-org.md

@@ -0,0 +1,31 @@
+# 04 - Integrate theme into calconnect.org
+
+Remove duplicated files now provided by calconnect-theme gem.
+
+## Config updates
+
+- `Gemfile`: add `gem "calconnect-theme", path: "../calconnect-theme"`, remove `minima`
+- `_config.yml`: change `theme: minima` → `theme: calconnect-theme`
+
+## Files to delete (now in theme)
+
+- `_layouts/base.html`
+- `_layouts/default.html`
+- `_layouts/page.html`
+- `_includes/head.html`
+- `_includes/breadcrumbs.html`
+- `_includes/feedback.html`
+- `_includes/google-analytics.html`
+- `_includes/custom-head.html`
+- `_frontend/js/theme.js`
+- `_frontend/js/navigation.js`
+
+## Files to keep (site-specific overrides)
+
+- `_includes/header.html`, `_includes/footer.html`
+- `_includes/news-card.html`, `_includes/script.html`
+- `_layouts/home.html`, `_layouts/category.html`, `_layouts/news-*.html`
+- `_frontend/entrypoints/application.css` (site-specific @source paths)
+- `_frontend/entrypoints/application.js` (Vue news search)
+- `_frontend/components/`, `_frontend/composables/`
+- `_data/`, `vite.config.ts`

TODO.new-style/05-verify-all-sites.md

@@ -0,0 +1,5 @@
+# 05 - Verify all three sites build
+
+1. **calconnect.org**: `cd calconnect.org && bundle install && npm ci && bundle exec jekyll build` — verify no regressions
+2. **DEVGUIDE**: `cd DEVGUIDE && bundle install && npm ci && bundle exec jekyll serve` — verify sidebar, dark mode, PlantUML, content
+3. **standards.calconnect.org**: `cd standards.calconnect.org && bundle install && npm ci && bundle exec jekyll build` — verify document rendering, doc-type badges, sidebar