cc-template

GitHub repository template for CalConnect Metanorma document repositories. Supports single-publishing (CalConnect only) and dual-publishing (CalConnect + IETF).

Quick start

1. Click Use this template on GitHub to create a new repository (e.g. cc-icalendar-series).

2. Replace XXXXX with the assigned document number:

   • sources/cc-XXXXX.adoc → sources/cc-51020.adoc

   • metanorma.yml → update the file list and collection name

3. For IETF dual-publishing, rename sources/draft-ietf-calext-example-00.adoc to match your IETF draft name.

4. Delete any files you don’t need (IETF files if single-publishing, or vice versa).

5. Write your document in AsciiDoc under sources/.

6. Add the metanorma-release GitHub topic to the repository.

7. Push to main — the generate workflow builds a preview, the release workflow publishes to standards.calconnect.org.

Repository structure

Single-publishing (CalConnect only)

├── .github/workflows/
│   ├── generate.yml
│   └── release.yml
├── .gitignore
├── Gemfile
├── metanorma.yml
├── metanorma.release.yml
└── sources/
    ├── cc-XXXXX.adoc             # CalConnect document
    └── sections/                 # Sections

Dual-publishing (CalConnect + IETF)

├── .github/workflows/
│   ├── generate.yml
│   └── release.yml
├── .gitignore
├── Gemfile
├── metanorma.yml                 # Lists both .adoc files
├── metanorma.release.yml         # Only routes cc-* to channels
└── sources/
    ├── cc-XXXXX.adoc             # CalConnect document (released)
    ├── draft-ietf-calext-example-00.adoc  # IETF internet-draft (not released)
    ├── sections/                 # Shared sections (abstract, intro, scope, terms)
    │   ├── 00-abstract.adoc
    │   ├── 01-intro.adoc
    │   ├── 01-scope.adoc
    │   ├── 02-normative-references.adoc
    │   ├── 03-terms.adoc
    │   └── 99-acknowledgements.adoc
    └── sections-ietf/            # IETF-specific sections (conventions, references)
        ├── 02-conventions.adoc
        └── 99-references.adoc

Both documents share sections from sections/ (abstract, intro, scope, terms). IETF-specific content goes in sections-ietf/ (BCP 14 conventions, IETF-style references).

Document types

Set the :doctype: attribute in your .adoc header:

Doctype	Description	Display category
standard	Normative standard	Standards, Specifications & Reports
specification	Technical specification	Standards, Specifications & Reports
report	Technical report	Standards, Specifications & Reports
guide	Implementation guide	Guides & Advisories
advisory	Advisory/recommendation	Guides & Advisories
directive	Organizational directive	Directives
administrative	Minutes, agendas, reports	Administrative
amendment	Amendment to a standard	Amendments & Technical Corrigenda
technical-corrigendum	Technical corrigendum	Amendments & Technical Corrigenda

CalConnect document attributes

= CalConnect Standard: TODO Document Title
:title: TODO Document Title
:docnumber: XXXXX
:copyright-year: 2026
:language: en
:doctype: standard
:edition: 1
:status: working-draft
:revdate: 2026-01-01
:published-date: 2026-01-01
:technical-committee: CALENDAR
:fullname: TODO Author Name
:surname: TODO
:givenname: TODO
:affiliation: TODO Organization
:mn-document-class: cc
:mn-output-extensions: xml,html,pdf,rxl
:local-cache-only:
:data-uri-image:

Additional authors use _2, _3 suffixes:

:fullname_2: Second Author
:surname_2: Author
:givenname_2: Second
:affiliation_2: Another Organization

IETF document attributes

= TODO Document Title
:doctype: internet-draft
:name: draft-ietf-calext-example-00
:status: standard
:ipr: trust200902
:area: Applications
:intended-series: full-standard
:revdate: 2026-01-01
:fullname: TODO Author Name
:lastname: TODO
:forename_initials: TODO
:affiliation: TODO Organization
:address: TODO Street + \
TODO City, TODO State TODO Code + \
TODO Country
:email: todo@example.com
:mn-document-class: ietf
:mn-output-extensions: xml,rfc,txt,html,rxl
:local-cache-only:
:data-uri-image:

Key differences from CalConnect documents:

• :mn-document-class: ietf — uses IETF formatting rules

• :name: — the IETF draft name (e.g. draft-ietf-calext-valarm-extensions-01)

• :ipr:, :area:, :intended-series: — IETF-specific metadata

• :mn-output-extensions: includes rfc and txt, not pdf

• Author format uses :lastname: / :forename_initials: instead of :surname: / :givenname:

• Author format includes :address: and :email: fields

Channel routing

metanorma.release.yml controls which documents are released. Only CalConnect documents (cc-*) are released to channels — IETF internet-drafts are published through the IETF process, not via metanorma-release.

documents:
  - pattern: "cc-*"
    channels: [public/standards]

For a multi-doctype repository with separate channels:

documents:
  - pattern: "cc-s-*"
    channels: [public/standards]
  - pattern: "cc-r-*"
    channels: [public/reports]
  - pattern: "cc-a-*"
    channels: [public/admin]

Stages

Set the :status: attribute to control the publication stage:

Status	Stage code	Description
working-draft	20	Initial working draft
committee-draft	30	Committee review draft
draft-standard	40	Draft standard
final-draft	50	Final draft for public review
published	60	Published document

The release workflow publishes all stages by default. Draft stages are released as GitHub pre-releases. The aggregator site can optionally include or exclude drafts via include_drafts in its config.

CI workflows

generate.yml — Preview

Builds the Metanorma output on every push and PR. Uses the reusable workflow from actions-mn/.github.

release.yml — Publication

Triggers on pushes to main that modify files under sources/, metanorma.yml, or metanorma.release.yml. Supports manual dispatch with options:

• include-pattern — glob to filter which documents to release

• force — re-release even if content is unchanged

Local development

bundle install
bundle exec metanorma site generate --agree-to-terms

The generated output appears in _site/.

Publishing to standards.calconnect.org

No manual steps needed. The aggregator site discovers repositories by the metanorma-release GitHub topic and subscribes to their release channels. As long as your repo:

1. Belongs to the CalConnect organization

2. Has the topic metanorma-release

3. Has a metanorma.release.yml with channel patterns

…​it will be automatically aggregated and published on https://standards.calconnect.org.