CalConnect Standards Registry

Introduction

The CalConnect Standards Registry is used to publish CalConnect deliverables, including its Standards and other public documents.

This repository provides all necessary information for the https://standards.calconnect.org site.

The site is managed by TC PUBLISH.

Sites

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

All sites are automatically deployed from their respective branches.

Building the index

# removes all generated CSD files
make distclean

# makes everything except _site
# (if we're using `make serve`, we don't need to pre-build)
make all

# generates all required files for Jekyll and runs `jekyll build`
make _site

Structure

General

Run the following command to update the list of CC documents in the site:

make repopulate-metanorma-yamls

# Behind the scene,

DOC_TYPE=standard \
DOC_CLASS=cc \
  scripts/repopulate-metanorma-yaml src-documents  src-documents/metanorma-standard.yml

DOC_TYPE=administrative \
DOC_CLASS=cc \
  scripts/repopulate-metanorma-yaml src-documents  src-documents/metanorma-administrative.yml

# ... and so on, for other doc types, if any

Sorting of entries

Sorting of the entries is by reverse sort order of the revdate attribute of documents.

Rendering of HTML

Jekyll is used to compile the HTML site, and metanorma-cli is used to compile CC documents via Metanorma YAML files.

In particular, our Makefile builds a new directory _documents from the data from bib/, as a Jekyll collection:

• The Jekyll collection, called documents, is used in the following pages:

  • _pages/public-review.adoc

• In _config.yml, it specifies that the document collection uses the layout document which allows rendering a separate page per document.

Usage

Install

You will need to have Ruby 3.3+ installed.

make update-init
make prep

How to add/remove entries?

• Bibliographic entry: add an entry in _input/external.yaml under the items: key.

• CSD document entry: add your CSD XML file to the document-register repo (push it), and update the submodule _input/csd here. It can be done here as easy as make update-modules:

pushd ~/standards.calconnect.org
make update-modules
git add src-documents
git commit -m 'chore: Update to use latest CC documents'
git push

On the next run of make clean _site you will see your entry added to the site.

Deployment

Please push all changes to the staging branch, and changes will be automatically deployed and reflected on the staging site.

If your changes are to be made public to the production site, please contact TC PUBLISH.