Ontology Companion Generator

OCG is a config-first npm package that builds a GitHub Pages companion site for an ontology or vocabulary. It generates reference, terms, graph, artifacts, optional ReSpec, and Usage Guide pages from your source files and ocg.config.json.

The recommended setup is to install OCG in the repository that owns the ontology. Forking this repository is also supported when you want the bundled example layout and source files as a starting point.

Quick Start

From the root of an existing ontology repository:

npm install --save-dev ontology-companion-generator
npx ocg init --ontology vocab/my-vocabulary.ttl
npm run ocg:check
npm run ocg:build

ocg init creates the configuration, schema, scripts, and GitHub Pages workflow. It also detects common SHACL, ShEx, examples, and ReSpec files. Review the generated ocg.config.json, then enable GitHub Pages with Settings > Pages > GitHub Actions and push main.

Useful commands:

npm run ocg:dev    # build and serve a local preview
npm run ocg:clean  # remove site/

For a ready-made template instead, fork this repository, replace the example files under source/, update ocg.config.json, and build from main.

Requirements

• Node.js 22.19.0 or newer and npm. The package supports newer Node.js releases without an upper version limit; generated workflows use Node.js 24.
• An ontology repository containing the primary source and any optional shapes, examples, or specification files.
• GitHub Pages configured to use GitHub Actions for deployment.

OCG uses rdf-parse for RDF parsing, graphology with its ForceAtlas2 and Noverlap layouts for graph generation, and sigma for the local interactive graph. Sigma.js and Graphology are bundled into the generated site; layout computation happens during the build. WebVOWL and ReSpec are optional integrations.

Repository Files

An npm-based ontology repository needs:

ocg.config.json
ocg.config.schema.json       # generated by ocg init; optional after setup
package.json
package-lock.json
.github/workflows/publish-pages.yml
your ontology, shapes, examples, and specification files

Source files can stay in their existing locations. Point to them with paths relative to the repository root. OCG detects common files during ocg init, but it does not scan arbitrary directories. Add extra files under sources.artifacts when they should be copied and shown in the viewer. The build output is written to site/ and normally contains:

• Home, Reference, Graph, Terms, and Usage Guide pages
• An optional ReSpec Specification page
• Copied ontology, SHACL, ShEx, specification, example, and configured additional artifacts

Configuration And Guides

ocg.config.json is the main customization surface. It controls metadata, source paths, page features, graph modes, featured terms, copy, branding, colors, fonts, and footer links. The schema is available at ocg.config.schema.json.

Branding Assets

Use site.branding to replace the abbreviation square in the upper-left header and the browser favicon. Paths are relative to the repository root; OCG copies them into the generated site, so they work on GitHub Pages and in local previews.

{
  "site": {
    "branding": {
      "headerImage": "source/branding/vocabulary-logo.svg",
      "favicon": "source/branding/vocabulary-favicon.svg"
    }
  }
}

headerImage accepts .png, .jpg, .jpeg, .webp, .gif, or .svg; it replaces project.shortName in the square header mark, including the ReSpec page. favicon accepts .ico, .png, or .svg. Leave either value empty to retain the default text mark or existing source/branding/favicon.png and favicon.ico fallback.

Theme Colors

Set theme.colors to restyle the generated page shell, panels, controls, tables, contextual TOCs, graph UI, and ReSpec navigation. The three accent variants control gradients, borders, and warm background details; the remaining tokens are the primary palette inputs used to derive shared surface and shadow colors.

{
  "theme": {
    "colors": {
      "pageBackground": "#f6f1ea",
      "pageBackgroundAlt": "#edf3f7",
      "panelBackground": "#ffffff",
      "cardBackground": "#ffffff",
      "text": "#1d1f22",
      "mutedText": "#5f6b7a",
      "accent": "#1f6f78",
      "accentStart": "#248992",
      "accentBorder": "#1c7d86",
      "accentStrong": "#13535a",
      "border": "#d6dee6",
      "warmAccent": "#e1ab4e"
    }
  }
}

Use CSS color values, preferably hex or rgb(...) values so translucent graph highlights can be derived reliably. Graph node and relationship semantic colors remain separately configurable under graph.colors.

Use the generated Usage Guide for complete option tables and examples. Its component-specific How To sections are also linked from the generated pages:

• Package and CLI
• Home
• Artifacts
• Reference
• Graph
• Terms
• Specification
• Branding and Footer

Set features.usageGuidePage to false if the in-app guide is not needed.

Home-Page Copy

All editorial home-page copy and labels are configured in site. Use site.hero and site.resourcePanel for the top area, and site.home for the action labels, metadata, snapshot, overview-card heading, featured terms, examples, source viewer, and built-in source artifacts. This means the Repository Workflow wording in the bundled example is not part of the generator: replace it with terminology appropriate to your ontology.

ocg init writes every site.home option into the new config. The generated Home guide documents each option; this focused example shows the common editorial changes:

{
  "site": {
    "hero": {
      "kicker": "Published Vocabulary",
      "headline": "Explore the Example Ontology",
      "body": "A concise introduction for visitors."
    },
    "home": {
      "actions": {
        "reference": "Reference",
        "graph": "Ontology Network",
        "terms": "Browse Terms",
        "ontology": "Ontology Source"
      },
      "snapshot": {
        "title": "Vocabulary at a Glance",
        "body": "Counts are generated from the configured ontology source."
      },
      "overview": {
        "title": "Using This Vocabulary",
        "body": "Add project-specific onboarding, publication, or contribution guidance here."
      },
      "featuredTerms": {
        "title": "Key Terms",
        "body": "Important concepts and properties for new users."
      },
      "examples": {
        "title": "Example Data",
        "linkText": "View Example"
      },
      "viewer": {
        "title": "Source Viewer",
        "viewFileText": "View Source"
      }
    }
  }
}

Use site.home.metadata to rename the canonical-IRI, version, and maintainer labels and the namespace-copy messages. Use site.home.artifacts to change fallback labels and descriptions for the ontology, SHACL, ShEx, and specification source assets. Labels and descriptions supplied directly in sources.examples and sources.artifacts take precedence for those individual files.

Page Navigation

OCG adds a compact table of contents to Home, Reference, Terms, and individual term pages when they contain multiple sections. It remains a sticky side rail on wide displays; its icon control contracts it to a compact square and expands the page content. On narrower screens it becomes an inline panel. The graph, Usage Guide, and ReSpec source page are intentionally excluded to avoid duplicate or distracting controls.

{
  "site": {
    "toc": {
      "enabled": true,
      "title": "On this page",
      "collapseLabel": "Collapse page contents",
      "expandLabel": "Expand page contents"
    }
  }
}

Set site.toc.enabled to false to remove these page-level tables of contents.

Optional Ontology Hierarchy

Set features.hierarchyOverview to true to add a curated ontology-structure overview above the Classes section on the Reference page. OCG derives it from subClassOf and/or broader relationships; it does not display the entire ontology. Use the hierarchy block to choose term types, roots, depth, branch limits, leaf/external-term visibility, and a capped list of important domain/range links. The default package config leaves this feature off because the useful scope varies by ontology; the bundled example enables it.

{
  "features": { "referencePage": true, "hierarchyOverview": true },
  "hierarchy": {
    "termTypes": ["class", "concept"],
    "relations": ["subClassOf", "broader"],
    "rootTerms": ["ecv:Capability"],
    "maxRoots": 4,
    "maxDepth": 3,
    "maxChildrenPerNode": 5,
    "maxNodes": 30,
    "includeLeafTerms": false,
    "includeExternal": false,
    "includePropertyRelations": true,
    "propertyRelations": ["domain", "range"],
    "maxPropertyRelations": 10,
    "labelMode": "label-and-qname"
  }
}

The overview is rendered as an accessible, collapsible tree with links to generated term pages. hierarchyAsset is a separate option: it controls the generated assets/ontology_hierarchy.ttl asset and does not enable the Reference-page overview.

Featured Terms And Artifacts

If curation.featuredTerms is omitted or empty, OCG automatically features up to six declared ontology terms. Set curation.featuredTermLimit to change the count, or set curation.autoFeaturedTerms to false to hide automatic terms.

If curation.viewerTabs is omitted or empty, the home-page Artifact Viewer includes every configured source asset: ontology, shapes, ShEx, specification source, examples, and sources.artifacts entries. Config, schema, workflow, and source-guide files are not viewer tabs. To curate the order, provide source asset keys such as ontology, example:basic, or artifact:context.

Extra files are configured explicitly:

{
  "sources": {
    "artifacts": [
      {
        "key": "context",
        "label": "Context JSON",
        "path": "source/context.json",
        "description": "Additional metadata for this vocabulary."
      }
    ]
  },
  "curation": {
    "viewerTabs": []
  }
}

Accepted Input Formats

The primary ontology input is parsed into RDF/JS quads. OCG currently supports:

• Turtle: .ttl, .turtle
• RDF/XML: .rdf, .rdfxml, .owl
• JSON-LD: .jsonld
• N-Triples: .nt, .ntriples

Use sources.ontologyFormat: "auto" to select a parser from the extension, or set it explicitly to turtle, rdfxml, jsonld, or ntriples.

OCG does not infer TriG, N-Quads, Notation3, OWL Functional or Manchester syntax, OWL/XML, OBO, arbitrary XML/JSON/YAML, CSV, UML/XMI, JSON Schema, OpenAPI, or Protobuf. SHACL and ShEx are published as artifacts but are not currently parsed into the generated graph.

Graphs

The Graph page can expose:

• A local Sigma.js graph with predicate-nodes and predicate-edges modes
• An optional WebVOWL view

The generated Ontology Network uses a deterministic ForceAtlas2 layout, label-aware Noverlap post-processing, and separate packing for disconnected components. Sigma.js provides hover details, click selection and highlighting, repeated-click deselection, forgiving edge hit areas, and draggable nodes. Manageable graphs show every label; larger graphs prioritize important labels while always revealing selected neighborhoods. Configure these behaviors under graph.custom.layout and graph.custom.labels in ocg.config.json. Both graph representations include an expand control. In the Ontology Network, full screen gives the graph the entire viewport and starts with the controls drawer collapsed; use Show controls to open it without shrinking the graph, and use the exit icon or Esc to leave full screen. WebVOWL requires a public URL for the serialized ontology document that its service can fetch. Do not set graph.webvowl.ontologyUrl to project.namespace such as https://w3id.org/vord#; a namespace identifies terms, while WebVOWL needs the actual .ttl, .rdf, or other ontology file URL. It may not work in a local file:// preview.

Automation

The Pages workflow, .github/workflows/publish-pages.yml, validates the ontology, builds site/, and deploys it when main changes or when manually dispatched. GitHub Pages cannot automatically display whichever branch a visitor is browsing, so use feature branches for validation and merge deployable changes to main.

Repositories initialized with an older OCG release should update their workflow to the current template so the GitHub Actions themselves also run on Node 24.

The npm workflow, .github/workflows/publish-npm.yml, publishes tags matching v*.*.*. It verifies the tag against package.json, runs tests, and uses npm trusted publishing with OIDC and provenance.

To enable npm publishing once:

1. Publish the initial package version manually if it is not already on npm.
2. On npm, configure a GitHub Actions trusted publisher for owner ecrum19, repository ocg, workflow publish-npm.yml.
3. Enable GitHub Actions in the repository and push the workflow.

For later releases:

npm version patch                 # or minor, major, or X.Y.Z
git push origin main --follow-tags

Example

The bundled example demonstrates ontology parsing, term pages, graph and hierarchy generation, artifacts, ReSpec, configuration-driven content, and Pages deployment. Start with:

• ocg.config.json
• source/ontology/example-capability.ttl
• source/README-source-guide.txt

Limitations

• Only the listed RDF formats are parsed as primary ontology inputs.
• SHACL and ShEx are not used to infer graph structure.
• Output is a static site; there is no backend, live synchronization, editing, or server-side reasoning.
• WebVOWL depends on an external service and a fetchable ontology URL.
• Very large ontologies may need filtering or a specialized visualization strategy for good browser performance.

Contributing

1. Fork the repository and create a focused feature branch.
2. Run npm install and use the bundled example for development.
3. Run the checks before opening a pull request:

npm test
npm run ocg:check
npm run build
git diff --check

Update the README and generated Usage Guide when changing configuration, CLI behavior, supported inputs, workflows, or user-facing features. Include regression coverage for fixes where practical, and keep generated output out of source changes unless required.

License

OCG is available under the MIT License.