Website of the OCM project

This repository contains the sources used to build the Open Component Model website at https://ocm.software.

• Content Structure
• Create New Content
  • Frontmatter
  • Standard Content Pages
    • Internal Links
  • Section Overview Pages
• Run Site Locally
• Cut-off New Versions
• Contributing
• Licensing

Content Structure

All content lives under the content directory and is organized by section.

Directory	Purpose
content/_index.md	Site landing page content
content/docs/concepts	Concept explanations
content/docs/getting-started	Getting Started guides
content/docs/overview	Overview and introductory information
content/docs/reference	Reference and CLI documentation (mounted via module imports)
content/docs/tutorials	Tutorials
content/community	Community information

Versioned snapshot folders live under content_versioned/:

Directory	Purpose
content_versioned/version-legacy	legacy OCM v1 docs, currently served at site root (default)
content_versioned/version-x.y.z	Content snapshot for release version x.y.z

Snapshots are generated by a script and should not be edited manually.

Create New Content

Frontmatter

Each page must contain frontmatter at the top of the file. Frontmatter defines metadata such as title, description, and optional logo. The frontmatter also defines the weight which controls the order of pages in the sidebar or the cards on the section overview pages. Lower weight means higher priority (appears first).

Example frontmatter:

title: "Page Title"
description: "A brief description of the page content"
logo: "📄"
weight: 92

There are templates for frontmatter of standard pages and _index.md of overview pages.

Standard Content Pages

Content is written in Markdown and placed under the content/ directory. Place content in the appropriate directory, keeping the structure consistent and descriptive. When creating new docs, prefer descriptive, unique filenames. This is good practice in general and helps keep relref targets short and readable.

Internal Links

We always use relref to define internal links. The default for relref is to use the base filename of the target. As long as the target file is located in the same folder as the referring document or is unique across the entire content/ folder, this is sufficient.

Example:

[Create a Component Version]({{< relref "create-component-version.md" >}})

If Hugo reports an ambiguity error during npm run dev or npm run build, such as:

ERROR [en] REF_NOT_FOUND: Ref "create-component-version.md": "/.../content/docs/concepts/components.md:9:167": page reference "create-component-version.md" is ambiguous

the filename is not unique across the content folder. In that case, you MUST use the full path of the target file relative to content/:

[Create a Component Version]({{< relref "docs/getting-started/create-component-version.md" >}})

Section Overview Pages

Sections are subfolders under content/docs. Each section requires an _index.md with frontmatter to define the section’s title and description. The _index.md should contain only metadata, no page content. The overview page will render cards for each document in the section automatically.

Run Site Locally

To test and develop the website locally, you can start a Hugo development server.

Requirements:

• Node.js ≥ 25.5.0
• npm ≥ 11.8.0
• Hugo Extended ≥ 0.155.0 (provided via npm package hugo-extended, installed with npm ci)

Install dependencies and start Hugo server (npm-first, no local Hugo install needed):

npm ci
npm run dev

The site will be available at http://localhost:1313 with live reload.

Cut-off New Versions

Versioning is performed via a script that snapshots the current content/ and updates all necessary configuration files. By default it also sets the new version as the defaultContentVersion, which is the version served at the site root. As long as the website still contains content for the legacy OCM v1 version, version "legacy" should be kept as the default version.

Examples:

# Create version 0.0.2 and keep the current defaultContentVersion
npm run cutoff -- 0.0.2 --keepDefault

# Create version 0.0.2 and set it as the defaultContentVersion
npm run cutoff -- 0.0.2

Until the first OCM v2 release ships, the recommended standard is to run the script with --keepDefault so the "legacy" version stays as default in place.

What the script does (brief):

• Copies content/ to content_versioned/version-x.y.z.
• Appends a [versions."x.y.z"] stanza (without weight) to config/_default/hugo.toml and optionally keeps defaultContentVersion unchanged when --keepDefault is supplied.
• Appends a grouped, per-version section to config/_default/module.toml.

The script keeps versioning configuration minimal and consistent. Authors only need to run the script; no manual edits of config files are required.

Contributing

Contributions to content and improvements are welcome. Please see our CONTRIBUTING guide for details on how to contribute.

Licensing

Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.