This guide shows how to add OCG to an existing ontology repository, point it at your current source files, customize the generated pages, and publish the companion site from that repository's main branch.
Keep your ontology repository as the source of truth and install OCG alongside it.
npm install --save-dev ontology-companion-generator. The package supplies the generator, schema fallback, branding, Sigma.js, Graphology, and RDF parser dependencies.npx ocg init --ontology vocab/my-vocabulary.ttl. OCG creates the config, schema, Pages workflow, and npm scripts, and attempts to infer the namespace and common companion files.sources are relative to the repository root, so an existing vocab/, shapes/, shex/, examples/, or spec/ layout can remain unchanged.npm run ocg:check, then npm run ocg:build. Use npm run ocg:dev to inspect the generated site locally.main. Feature branches should build and validate without deploying over the live site.{
"sources": {
"ontology": "vocab/my-vocabulary.ttl",
"ontologyFormat": "turtle",
"shapes": "shapes/my-vocabulary.shacl.ttl",
"shex": "shex/my-vocabulary.shex",
"spec": "spec/index.html",
"examples": [
{
"key": "basic",
"label": "Basic Example",
"path": "examples/basic.ttl",
"description": "A minimal valid instance graph."
}
]
}
}The primary workflow adds OCG to an existing ontology repository; forking this repository is an optional alternative.
ocg.config.json.npm run ocg:build to regenerate site/ and vendor the Sigma.js/Graphology browser bundles under site/assets/vendor/, then inspect the pages.main branch. The workflow rebuilds and deploys site/ through GitHub Actions.OCG support files can sit beside an existing ontology layout; source paths do not need to use source/.
.
├── ocg.config.json
├── ocg.config.schema.json
├── package.json # contains the OCG dependency and scripts
├── package-lock.json
├── vocab/ # existing ontology files
├── shapes/ # existing SHACL files
├── shex/ # existing ShEx files
├── examples/ # existing instance data
├── spec/ # existing ReSpec source
└── site/ # generated, do not edit by handOCG currently parses a deliberately small set of RDF serializations for the primary ontology.
{
"sources": {
"ontology": "source/ontology/my-vocabulary.jsonld",
"ontologyFormat": "jsonld"
}
}Use the component-level How To links throughout the site to return directly to these explanations. Each detailed section includes an option table and a complete example.
Install OCG as a development dependency and use the CLI to initialize, validate, build, preview, and clean the companion site.
Customize: CLI paths, output directory, local preview host, and the full ocg.config.json surface.
The home page presents your project identity, navigation, source artifacts, ontology snapshot, configurable overview cards, featured terms, examples, and the raw artifact viewer.
Customize: site.hero, site.resourcePanel, site.overviewCards, site.customSections, and curation.featuredTerms.
OWL Ontology, SHACL, ShEx, specification, examples, and additional configured source files are copied into site/assets/. Config, schema, workflow, and guide files are available as generated links but are not raw-viewer tabs.
Customize: sources, features.rawViewer, and curation.viewerTabs.
The reference page extracts declared terms from the configured ontology and groups them by class, property, concept, and declared-term type.
Enable or disable: features.referencePage.
The Ontology Network supports Predicates as Nodes or Predicates as Edges, plus filters, search, selection, layout, and external-term visibility. Its full-screen view gives the network the full viewport and provides a collapsible controls drawer. WebVOWL can be enabled alongside it and expanded the same way.
Customize: graph.custom, graph.webvowl, and graph.colors.
Every declared ontology term can receive an individual page with its IRI, labels, types, source links, and incoming/outgoing relationships.
Enable or disable: features.termPages.
Place a ReSpec HTML document at sources.spec. OCG publishes it at spec/index.html, injects the companion navigation, and links it from the site.
Enable or disable: features.specPage.
Project metadata supplies the shared title, namespace, version, and maintainer information used throughout the site.
The in-app guide can be enabled or disabled as a generated page and navigation destination.
Theme colors, fonts, footer copy, and OCG repository/documentation links are configured here.
Installs OCG into an existing ontology repository and controls initialization, validation, generation, cleanup, and local preview.
This example includes every option described in this component section. Remove optional entries you do not need.
{
"scripts": {
"ocg:check": "ocg check",
"ocg:build": "ocg build",
"ocg:dev": "ocg dev",
"ocg:clean": "ocg clean"
},
"commands": [
"npm install --save-dev ontology-companion-generator",
"npx ocg init --ontology vocab/my-vocabulary.ttl",
"npm run ocg:check",
"npm run ocg:build"
]
}Metadata used by the header, home page, generated titles, term pages, and graph data.
This example includes every option described in this component section. Remove optional entries you do not need.
{
"title": "Your Vocabulary",
"shortName": "YV",
"slug": "your-vocabulary",
"description": "What this vocabulary describes.",
"namespace": "https://example.org/vocab#",
"canonicalUri": "https://example.org/vocab",
"version": "1.0.0",
"maintainer": "Vocabulary Team"
}Controls all editorial landing-page copy and labels, including the repository-workflow heading, source controls, metadata, cards, featured terms, examples, and viewer.
This example includes every option described in this component section. Remove optional entries you do not need.
{
"features": {
"overviewCards": true
},
"site": {
"hero": {
"kicker": "Forkable Vocabulary Template",
"headline": "Explore Your Vocabulary",
"body": "A short introduction shown on the home page."
},
"resourcePanel": {
"title": "Published Artifacts",
"body": "A short explanation shown above the artifact links."
},
"home": {
"actions": {
"reference": "Reference",
"graph": "Ontology Network",
"terms": "Browse Terms",
"specification": "Specification",
"ontology": "Ontology Source",
"shapes": "Validation Shapes",
"shex": "ShEx Schema"
},
"metadata": {
"canonicalUri": "Vocabulary IRI",
"version": "Release",
"maintainer": "Maintained by",
"unspecified": "Not provided",
"copyNamespace": "Copy vocabulary namespace",
"namespaceCopied": "Vocabulary namespace copied",
"namespaceCopyUnavailable": "Vocabulary namespace could not be copied"
},
"snapshot": {
"title": "Vocabulary at a Glance",
"body": "Counts are generated from the configured ontology source."
},
"overview": {
"title": "Using This Vocabulary",
"body": "Add project-specific guidance above the configurable overview cards."
},
"featuredTerms": {
"title": "Key Terms",
"body": "Highlight the concepts and properties visitors should understand first.",
"emptyBody": "No key terms are selected yet."
},
"examples": {
"title": "Example Data",
"body": "Link to representative instance data or usage examples.",
"defaultDescription": "A configured example for this vocabulary.",
"linkText": "View Example"
},
"viewer": {
"title": "Source Viewer",
"body": "Choose source files and their order with curation.viewerTabs.",
"viewFileText": "View Source",
"loadingText": "Loading source..."
},
"artifacts": {
"ontologyLabel": "Ontology Source",
"ontologyDescription": "Primary ontology source published with the companion site.",
"shapesLabel": "Validation Shapes",
"shapesDescription": "Optional SHACL constraints package.",
"shexLabel": "ShEx Schema",
"shexDescription": "Optional ShEx schema file.",
"specificationLabel": "Specification Source",
"specificationDescription": "Source document for the optional ReSpec specification page.",
"additionalArtifactDescription": "Additional configured source artifact."
}
},
"overviewCards": [
{
"title": "Card Title",
"body": "Card text shown on the home page.",
"linkText": "Learn More",
"linkHref": "usage-guide.html#home"
}
],
"customSections": [
{
"title": "Additional Context",
"body": "A custom narrative section for domain-specific guidance.",
"items": [
"A supporting point",
"Another supporting point"
]
}
]
},
"curation": {
"featuredTerms": [
"yv:ImportantClass",
"yv:importantProperty"
]
}
}Publishes configured source files into site/assets/ and controls which files appear in the raw artifact viewer. OCG does not scan arbitrary directories. Primary ontology support is limited to Turtle, RDF/XML, JSON-LD, and N-Triples; other ontology syntaxes are rejected.
This example includes every option described in this component section. Remove optional entries you do not need.
{
"sources": {
"ontology": "source/ontology/your-vocabulary.ttl",
"shapes": "source/shapes/your-vocabulary.shacl.ttl",
"shex": "source/shex/your-vocabulary.shex",
"spec": "source/spec/index.html",
"artifacts": [
{
"key": "context",
"label": "Context JSON",
"path": "source/context.json",
"description": "Additional source documentation or metadata.",
"destinationName": "context.json"
}
],
"examples": [
{
"key": "basic",
"label": "Basic Example",
"path": "source/examples/basic.ttl",
"description": "A small valid instance graph."
}
]
},
"features": {
"rawViewer": true,
"hierarchyAsset": true
},
"curation": {
"viewerTabs": []
}
}Generates a browsable reference page from terms declared in the configured ontology, with an optional curated hierarchy overview above the Classes section.
This example includes every option described in this component section. Remove optional entries you do not need.
{
"features": {
"referencePage": true,
"hierarchyOverview": true
},
"hierarchy": {
"title": "Ontology Structure",
"description": "A curated overview of the main class and concept relationships.",
"termTypes": [
"class",
"concept"
],
"relations": [
"subClassOf",
"broader"
],
"rootTerms": [],
"maxRoots": 6,
"maxDepth": 3,
"maxChildrenPerNode": 6,
"maxNodes": 36,
"includeLeafTerms": true,
"includeExternal": false,
"includePropertyRelations": true,
"propertyRelations": [
"domain",
"range"
],
"maxPropertyRelations": 12,
"labelMode": "label-and-qname"
}
}Configures the Sigma.js Ontology Network, its ForceAtlas2 and overlap-removal layout, adaptive labels, predicate modes, interactions, WebVOWL, and graph colors.
This example includes every option described in this component section. Remove optional entries you do not need.
{
"defaultView": "custom",
"custom": {
"enabled": true,
"label": "Ontology Network",
"defaultMode": "predicate-nodes",
"modes": {
"predicateNodes": true,
"predicateEdges": true
},
"layout": {
"iterations": 320,
"seed": 42,
"scalingRatio": 1.4,
"gravity": 1,
"linLogMode": false,
"preventOverlap": true,
"labelSpacing": 1.15
},
"labels": {
"density": 1.5,
"gridCellSize": 90,
"renderedSizeThreshold": 2,
"forceAllUnder": 80
}
},
"webvowl": {
"enabled": true,
"serviceUrl": "https://service.tib.eu/webvowl/",
"ontologyUrl": "",
"height": 760
},
"colors": {
"class": "#b7dcf6",
"objectProperty": "#bee7c3",
"datatypeProperty": "#f7d7ab",
"annotationProperty": "#f2c8cf",
"concept": "#d3c5f6",
"declaredTerm": "#e1e8ef",
"external": "#dfe6ee",
"subClassOf": "#1f6f92",
"domain": "#2f8040",
"range": "#ab6b22",
"broader": "#7b5ca7"
}
}Creates one HTML page for each declared ontology term, with relationships and source links.
This example includes every option described in this component section. Remove optional entries you do not need.
{
"features": {
"termPages": true
}
}Publishes a source ReSpec document as a first-class companion page with injected navigation.
This example includes every option described in this component section. Remove optional entries you do not need.
{
"sources": {
"spec": "source/spec/index.html"
},
"features": {
"specPage": true
}
}Generates this in-app configuration and workflow guide with component-specific How To links.
This example includes every option described in this component section. Remove optional entries you do not need.
{
"features": {
"usageGuidePage": true
}
}Applies site-wide branding images, fonts, colors, page table-of-contents behavior, footer copy, and OCG attribution links.
This example includes every option described in this component section. Remove optional entries you do not need.
{
"site": {
"basePath": "/",
"branding": {
"headerImage": "source/branding/vocabulary-logo.svg",
"favicon": "source/branding/vocabulary-favicon.svg"
},
"toc": {
"enabled": true,
"title": "On this page",
"collapseLabel": "Collapse page contents",
"expandLabel": "Expand page contents"
},
"footer": {
"primary": "Your vocabulary companion site.",
"secondary": "Maintained by the Vocabulary Team."
},
"generator": {
"repositoryUrl": "https://github.com/ecrum19/ocg",
"documentationUrl": "https://github.com/ecrum19/ocg#readme"
}
},
"theme": {
"fonts": {
"heading": "Space Grotesk",
"body": "IBM Plex Sans",
"mono": "IBM Plex Mono"
},
"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"
}
}
}The config is the primary customization surface. The schema file provides editor validation.
{
"$schema": "./ocg.config.schema.json",
"project": {
"title": "Your Vocabulary",
"shortName": "YV",
"slug": "your-vocabulary",
"description": "What this vocabulary describes.",
"namespace": "https://example.org/vocab#",
"canonicalUri": "https://example.org/vocab",
"version": "1.0.0",
"maintainer": "Vocabulary Team"
},
"sources": {
"ontology": "source/ontology/your-vocabulary.ttl",
"ontologyFormat": "auto",
"shapes": "source/shapes/your-vocabulary.shacl.ttl",
"shex": "source/shex/your-vocabulary.shex",
"spec": "source/spec/index.html",
"examples": [
{
"key": "basic",
"label": "Basic Example",
"path": "source/examples/basic.ttl",
"description": "A small valid instance graph."
}
],
"artifacts": [
{
"key": "context",
"label": "Context JSON",
"path": "source/context.json",
"description": "Additional source documentation or metadata.",
"destinationName": "context.json"
}
]
},
"features": {
"referencePage": true,
"graphPage": true,
"termPages": true,
"rawViewer": true,
"overviewCards": true,
"hierarchyAsset": true,
"hierarchyOverview": true,
"specPage": true,
"usageGuidePage": true
},
"hierarchy": {
"title": "Ontology Structure",
"description": "A curated overview of the main class and concept relationships.",
"termTypes": [
"class",
"concept"
],
"relations": [
"subClassOf",
"broader"
],
"rootTerms": [],
"maxRoots": 6,
"maxDepth": 3,
"maxChildrenPerNode": 6,
"maxNodes": 36,
"includeLeafTerms": true,
"includeExternal": false,
"includePropertyRelations": true,
"propertyRelations": [
"domain",
"range"
],
"maxPropertyRelations": 12,
"labelMode": "label-and-qname"
},
"graph": {
"defaultView": "custom",
"custom": {
"enabled": true,
"label": "Ontology Network",
"defaultMode": "predicate-nodes",
"modes": {
"predicateNodes": true,
"predicateEdges": true
},
"layout": {
"iterations": 320,
"seed": 42,
"scalingRatio": 1.4,
"gravity": 1,
"linLogMode": false,
"preventOverlap": true,
"labelSpacing": 1.15
},
"labels": {
"density": 1.5,
"gridCellSize": 90,
"renderedSizeThreshold": 2,
"forceAllUnder": 80
}
},
"webvowl": {
"enabled": true,
"serviceUrl": "https://service.tib.eu/webvowl/",
"ontologyUrl": "",
"height": 760
},
"colors": {
"class": "#b7dcf6",
"objectProperty": "#bee7c3",
"datatypeProperty": "#f7d7ab",
"annotationProperty": "#f2c8cf",
"concept": "#d3c5f6",
"declaredTerm": "#e1e8ef",
"external": "#dfe6ee",
"subClassOf": "#1f6f92",
"domain": "#2f8040",
"range": "#ab6b22",
"broader": "#7b5ca7"
}
},
"theme": {
"fonts": {
"heading": "Space Grotesk",
"body": "IBM Plex Sans",
"mono": "IBM Plex Mono"
},
"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"
}
},
"site": {
"basePath": "/",
"branding": {
"headerImage": "source/branding/vocabulary-logo.svg",
"favicon": "source/branding/vocabulary-favicon.svg"
},
"hero": {
"kicker": "Forkable Vocabulary Template",
"headline": "Explore Your Vocabulary",
"body": "A short introduction shown on the home page."
},
"resourcePanel": {
"title": "Published Artifacts",
"body": "A short explanation shown above the artifact links."
},
"toc": {
"enabled": true,
"title": "On this page",
"collapseLabel": "Collapse page contents",
"expandLabel": "Expand page contents"
},
"home": {
"actions": {
"reference": "Reference",
"graph": "Ontology Network",
"terms": "Browse Terms",
"specification": "Specification",
"ontology": "Ontology Source",
"shapes": "Validation Shapes",
"shex": "ShEx Schema"
},
"metadata": {
"canonicalUri": "Vocabulary IRI",
"version": "Release",
"maintainer": "Maintained by",
"unspecified": "Not provided",
"copyNamespace": "Copy vocabulary namespace",
"namespaceCopied": "Vocabulary namespace copied",
"namespaceCopyUnavailable": "Vocabulary namespace could not be copied"
},
"snapshot": {
"title": "Vocabulary at a Glance",
"body": "Counts are generated from the configured ontology source."
},
"overview": {
"title": "Using This Vocabulary",
"body": "Add project-specific guidance above the configurable overview cards."
},
"featuredTerms": {
"title": "Key Terms",
"body": "Highlight the concepts and properties visitors should understand first.",
"emptyBody": "No key terms are selected yet."
},
"examples": {
"title": "Example Data",
"body": "Link to representative instance data or usage examples.",
"defaultDescription": "A configured example for this vocabulary.",
"linkText": "View Example"
},
"viewer": {
"title": "Source Viewer",
"body": "Choose source files and their order with curation.viewerTabs.",
"viewFileText": "View Source",
"loadingText": "Loading source..."
},
"artifacts": {
"ontologyLabel": "Ontology Source",
"ontologyDescription": "Primary ontology source published with the companion site.",
"shapesLabel": "Validation Shapes",
"shapesDescription": "Optional SHACL constraints package.",
"shexLabel": "ShEx Schema",
"shexDescription": "Optional ShEx schema file.",
"specificationLabel": "Specification Source",
"specificationDescription": "Source document for the optional ReSpec specification page.",
"additionalArtifactDescription": "Additional configured source artifact."
}
},
"overviewCards": [
{
"title": "Card Title",
"body": "Card text shown on the home page.",
"linkText": "Learn More",
"linkHref": "usage-guide.html#home"
}
],
"customSections": [
{
"title": "Additional Context",
"body": "A custom narrative section for domain-specific guidance.",
"items": [
"A supporting point",
"Another supporting point"
]
}
],
"footer": {
"primary": "Your vocabulary companion site.",
"secondary": "Maintained by the Vocabulary Team."
},
"generator": {
"repositoryUrl": "https://github.com/ecrum19/ocg",
"documentationUrl": "https://github.com/ecrum19/ocg#readme"
}
},
"curation": {
"featuredTerms": [
"yv:ImportantClass",
"yv:importantProperty"
],
"autoFeaturedTerms": true,
"featuredTermLimit": 6,
"viewerTabs": []
}
}The included workflow builds the ontology repository on pushes to main and deploys the generated site/ directory.
main so feature branches cannot overwrite the live site.GitHub Pages does not dynamically follow the branch currently selected in the GitHub file browser. Deploying every branch would send each build to the same Pages site, with the latest deployment replacing the previous one. Build and test feature branches locally or with build-only CI, then merge to main for publication.
Run these from the repository root.
npm install --save-dev ontology-companion-generator
npx ocg init --ontology vocab/my-vocabulary.ttl
npm run ocg:check # validate config and parse ontology
npm run ocg:build # generate site/
npm run ocg:dev # preview at http://127.0.0.1:4173/
npm run ocg:clean # remove generated site/