Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/calconnect/standards.calconnect.org

CalConnect Document Registry
https://github.com/calconnect/standards.calconnect.org

Last synced: 18 days ago
JSON representation

CalConnect Document Registry

Awesome Lists containing this project

README 

          
= CalConnect Standards Registry



image:https://github.com/CalConnect/standards.calconnect.org/actions/workflows/build_deploy.yml/badge.svg[

    Build Status, link="https://github.com/CalConnect/standards.calconnect.org/actions/workflows/build_deploy.yml"]



== 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



[cols="a,a,a",options="header"]

|===

|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



. **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`).

. **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.

. **Site build** — Jekyll builds static HTML from the aggregated `documents.json` index.

  Vite compiles the JavaScript and Tailwind CSS.

. **Deploy** — GitHub Pages serves the built site.



=== Software stack



* https://github.com/metanorma/metanorma-release[metanorma-release] — aggregation pipeline

* https://jekyllrb.com[Jekyll] — static site generator

* https://vitejs.dev[Vite] + https://tailwindcss.com[Tailwind CSS] — frontend build

* https://github.com/features/actions[GitHub Actions] — CI/CD



== Quick start



[source,sh]

----

# 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:



[cols="1m,3",options="header"]

|===

|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,yaml]

----

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:



. Use the https://github.com/CalConnect/cc-template[`cc-template`] repository template

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

. Write the document in AsciiDoc and push to `main`



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



. The document repo's `release` workflow runs (on push to `main`)

. This site's next build (push to `main` or daily cron)



No changes to this repository are needed.



=== Removing a document



. Archive or delete the document repository, or

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



. Sets up Ruby 3.3 + Node.js 24

. Restores aggregate cache (`.cache/aggregate/`)

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

. Verifies the build produced >0 documents

. Uploads Pages artifact

. Deploys to GitHub Pages (on `main` only)



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