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.
| Site | Git branch | URL |
|---|---|---|
Production |
|
The Production site is the live site,
which is automatically deployed from changes to the main branch.
You will need to have Ruby 3.3+ installed.
Initialize all document submodules, and install all necessary dependencies:
make prepAfter dependencies have been installed, you can build the site by running:
make build-all-parallel
# Or `make build-all` for a serial runThere are two stages to building the index site, of which the order is important:
-
Building the site itself (Jekyll)
-
Building the document artifacts (Metanorma)
The above command will take care of both stages.
The site is automatically built and deployed using GitHub Actions using the workflow defined in .github/workflows/build_deploy.yml.
A successful build will upload and store (within a time limit)
the built site artifacts on GitHub,
accessible by the name github-pages,
under the "Artifacts" block on the "Summary" page tab of the build job.
The downloaded zip archive can be extracted locally for inspection as well as local testing.
To view the site locally, you have the option to run any local server,
e.g. npx serve:
npx serve _site|
Warning
|
jekyll serve (or make serve) is not recommended
as it does not build the site first,
risking the document artifacts being removed by the Jekyll process.
|
Documents are added to the site by adding a the document repository as a Git
submodule to the src-documents directory,
then updating the Metanorma YAML file list.
Conversely, removal of documents is done by removing the submodule, then also updating the Metanorma YAML file list.
pushd ~/standards.calconnect.org
git submodule add $DOCUMENT_REPOSITORY_URL src-documents/$DOCUMENT_REPO_NAME
make repopulate-metanorma-yamls-parallel
git add src-documents
git commit -m "chore: Add CC documents ($DOCUMENT_REPO_NAME)" && \
git pushpushd ~/standards.calconnect.org
make update-documents
make repopulate-metanorma-yamls-parallel # May not be necessary if no new docs
git add src-documents
git commit -m 'chore: Update to use latest CC documents' && \
git pushOn the next run of make clean build-all-parallel,
you will see your updates made to the site.
Jekyll is used to compile the HTML site, and metanorma-cli is used to compile CC documents via Metanorma YAML files.
The site sources its content from the src-documents directory,
which contains Git submodules of the various CalConnect documents.
The directory also contains the Metanorma YAML files necessary to compile the documents into various output formats.
There is also a _relaton_templates/ directory,
which contains liquid templates
for rendering HTML via
Relaton,
as well as an empty_index.adoc file,
for displaying the index page for any empty document collections.
The src-documents directory is structured as follows:
src-documents/
├── cc-doc-repo-1/
├── cc-doc-repo-2/
├── cc-doc-repo-.../
├── _relaton_templates/
│ ├── _document.liquid
│ ├── _index.liquid
│ └── ...
├── empty_index.adoc
├── metanorma-administrative.yml
├── metanorma-standard.yml
├── metanorma-....yml
└── ...The Metanorma YAML files are used to specify the source document files
(.adoc files) to be compiled by Metanorma.
Each Metanorma YAML file corresponds to one Metanorma :doctype: that is used
in CalConnect,
and contains a list of .adoc file paths to be compiled,
as well as a reference to the
liquid
template directory to be used
[1].
The template directory reference is passed to
Relaton
for the actual rendering of the HTML output.
The .adoc file lists are populated by the repopulate-metanorma-yaml
script
(see scripts/repopulate-metanorma-yaml).
There are several scripts (located in the scripts/ directory) that are
available to help manage the site.
Normally, these scripts are run via the make command,
so there is no need to run them directly.
This is to populate a target YAML’s metanorma.source.files with a list of
.adoc file paths that are of the specified :mn-document-class: and
:doctype:,
that are found in a specified directory (default: src-documents/).
The following command updates the list of CC documents to be displayed in the site:
make repopulate-metanorma-yamls-parallel
# Or `make repopulate-metanorma-yamls` for a serial runBehind the scene, something like this is run:
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 anyThis returns all .adoc file paths of a certain :doctype: and
:mn-document-class: in a specified directory,
as a list of newline-separated paths.
This adds all repositories, which satisfy the following conditions,
to the DOCS_SUBDIR directory as submodules:
-
repository organization matches given
ORG -
repository name matchs the given
PREFIX(default:CalConnect/cc-)
|
Note
|
This was used to initialize the src-documents/ directory, and is not
normally used in the day-to-day management of the site.
|
This returns, as a JSON string, all repositories in an organization that match
a prefix (default: CalConnect/cc-).
./_site/$DOCTYPE/