CalConnect Standards Registry

Introduction

The CalConnect Standards Registry publishes CalConnect deliverables — standards, specifications, guides, directives, and other documents — at https://standards.calconnect.org.

The site is an aggregator: it discovers Metanorma document repositories via the metanorma-release GitHub topic, fetches their published releases, and builds a static site with full-text search, category pages, and document downloads.

The site is managed by TC PUBLISH.

Sites

Site	Git branch	URL
Production	main	https://standards.calconnect.org

The production site is automatically deployed from changes to the main branch. It also rebuilds daily at 06:00 UTC to pick up new releases from document repos.

Architecture

How documents get published

1. Document repo — A Metanorma repo (e.g. cc-icalendar-series) compiles .adoc sources and runs the release workflow, which publishes ZIP archives to GitHub Releases with channel labels (e.g. public/standards).

2. Aggregation — This site runs metanorma-release aggregate, which discovers repos by the metanorma-release topic, fetches their releases, filters by channel, extracts document files, and enriches metadata from Relaton bibliographic data.

3. Site build — Jekyll builds static HTML from the aggregated documents.json index. Vite compiles the JavaScript and Tailwind CSS.

4. Deploy — GitHub Pages serves the built site.

Software stack

• metanorma-release — aggregation pipeline

• Jekyll — static site generator

• Vite + Tailwind CSS — frontend build

• GitHub Actions — CI/CD

Quick start

# Install dependencies
bundle install
npm ci

# Aggregate releases + build the site
bundle exec rake build

# Serve locally
npx serve _site

Note	Aggregation requires a GITHUB_TOKEN with read access to the CalConnect organization repos. Set it as an environment variable or in .env.

Build commands

The Rakefile provides these tasks:

Command	Description
rake fetch	Aggregate releases into _data/documents.json and _site/docs/
rake build	Fetch + compile Vite + build Jekyll site
rake jekyll	Build Jekyll only (assumes fetch already done)
rake serve	Serve with Jekyll’s dev server
rake clean	Remove _site/

Configuration

metanorma.aggregate.yml

Controls how the aggregator discovers repos and builds output:

source: github
output_dir: _site/docs
file_routing: flat
cache_dir: .cache/aggregate
data_dir: _data

channels:
  - public

include_drafts: true

display_categories:
  - name: Standards, Specifications & Reports
    slug: standards
    doctypes: [standard, specification, report]
  - name: Guides & Advisories
    slug: guides
    doctypes: [guide, advisory]
  - name: Directives
    slug: directives
    doctypes: [directive]
  - name: Administrative
    slug: administrative
    doctypes: [administrative]
  - name: Amendments & Technical Corrigenda
    slug: amendments
    doctypes: [amendment, technical-corrigendum]

github:
  organizations:
    - CalConnect
  topic: metanorma-release

Key settings:

• output_dir — where extracted document files are written

• channels — which channels to subscribe to (public matches all public/*)

• display_categories — maps doctypes to site categories

• include_drafts — include working drafts, committee drafts, etc.

• data_dir — writes flattened documents.json for Jekyll’s _data/

Delta state cache

Aggregation is incremental. The .cache/aggregate/ directory tracks which repos/tags have been processed. CI caches this directory between builds to avoid re-downloading unchanged releases.

When the cache is stale (e.g. files are missing from disk), the pipeline re-processes affected repos automatically.

How to add/remove documents

Adding a document

Documents are added by creating a new Metanorma repository:

1. Use the cc-template repository template

2. Add the metanorma-release topic to the new repository

3. Write the document in AsciiDoc and push to main

The document will appear on standards.calconnect.org after:

1. The document repo’s release workflow runs (on push to main)

2. This site’s next build (push to main or daily cron)

No changes to this repository are needed.

Removing a document

1. Archive or delete the document repository, or

2. Remove the metanorma-release topic from the repository

The document will disappear from the site on the next build.

Changing a document’s category

Document categories are determined by doctype. Edit metanorma.aggregate.yml → display_categories to change which doctypes map to which category.

Project structure

├── .github/workflows/
│   └── build_deploy.yml        # CI: aggregate + build + deploy
├── _data/                      # Generated by aggregation
│   └── documents.json          # Flattened document index
├── _frontend/                  # Vite + Tailwind source
│   ├── entrypoints/
│   │   ├── application.css     # Tailwind CSS entry
│   │   └── application.js      # JavaScript entry
│   └── js/
│       └── home.js             # Global search
├── _includes/                  # Jekyll partials
│   ├── head.html
│   ├── nav.html
│   └── footer.html
├── _layouts/                   # Jekyll layouts
│   ├── base.html
│   └── doc-type.html           # Category page (standards, guides, etc.)
├── _pages/                     # Site pages
│   ├── index.html              # Home page with search
│   ├── standards.html
│   ├── guides.html
│   ├── directives.html
│   ├── administrative.html
│   ├── amendments.html
│   ├── drafts.html
│   └── public-review.html
├── _site/                      # Built site output
│   ├── docs/                   # Extracted document files (HTML, PDF, XML, RXL)
│   └── index.json              # Full document index
├── public/                     # Static assets (favicons, Vite output)
├── Gemfile                     # Ruby dependencies
├── Rakefile                    # Build tasks
├── metanorma.aggregate.yml     # Aggregator configuration
├── package.json                # Node.js dependencies
└── vite.config.js              # Vite configuration

CI/CD

The build_deploy workflow:

1. Sets up Ruby 3.3 + Node.js 24

2. Restores aggregate cache (.cache/aggregate/)

3. Runs bundle exec rake build (aggregate + Vite + Jekyll)

4. Verifies the build produced >0 documents

5. Uploads Pages artifact

6. Deploys to GitHub Pages (on main only)

Scheduled builds run daily at 06:00 UTC to pick up new releases.