OWL Coat

Generate HTML documentation from an OWL ontology (Turtle/RDF) and a customisable Pug template.

Quick Start (CLI)

npm install -g owl-coat
mkdir my-ontology && cd my-ontology
owlcoat init
# Edit config.json with your ontology details
owlcoat generate

Installation

Global (for CLI)

npm install -g owl-coat

Then use the owlcoat command anywhere.

Local (for development)

Clone this repository:

git clone https://github.com/DOREMUS-ANR/OWL-Coat

Install dependencies:

npm install

CLI Usage

owlcoat init

Initialize a new OWL Coat project in the current directory:

owlcoat init

This creates:

• res/ — Pug templates and stylesheets
• config.json — Configuration template

owlcoat generate

Generate documentation from an ontology:

# Using config.json in current directory
owlcoat generate

# Or with command-line options (override config.json)
owlcoat generate \
  --source https://example.org/ontology.ttl \
  --named-graph http://example.org/ontology# \
  --input ./res/ \
  --output ./out/

# Using a custom config file
owlcoat generate --config ./my-config.json

Options:

• -c, --config <file> — Path to config.json (default: config.json)
• -s, --source <url-or-path> — Ontology source (TTL file URL or local path)
• -n, --named-graph <uri> — Ontology namespace URI
• -i, --input <dir> — Input directory with templates (default: ./res/)
• -o, --output <dir> — Output directory (default: ./out/)

Programmatic Usage

Use OWL Coat as a library in your Node.js code:

const generate = require('owl-coat/lib/generate');

generate({
    source: 'https://example.org/ontology.ttl',
    namedGraph: 'http://example.org/ontology#',
    input: './res/',
    output: './out/'
});

Or for the init command:

const init = require('owl-coat/lib/init');

init();

Configuration (config.json)

The config.json file contains the ontology settings:

{
  "source": "<URI or local file path>",
  "namedGraph": "<ontology namespace URI>",
  "input": "./res/",
  "output": "./out/"
}

| Field | Required | Description | |---|---|---| | source | yes | URL or local path to the ontology .ttl file | | namedGraph | yes | The ontology namespace URI (e.g. http://example.org/ontology#) | | input | no | Directory containing Pug templates and static assets (default: ./res/) | | output | no | Directory where generated files are written (default: ./out/) |

Development

Compile styles

If you edit res/styles.styl, recompile it:

npm run build:styles       # One-time compilation
npm run watch:styles       # Watch for changes

Using the Node.js API directly

node index

How to write a Pug template

OWL Coat exposes the following variables to every Pug template.

Data variables

| Variable | Type | Description | |---|---|---| | ontology | Object | The owl:Ontology node from the graph. ontology.namespace is set to the value of namedGraph. | | classes | Array | All owl:Class / rdfs:Class nodes, sorted by inner code. | | properties | Array | All owl:ObjectProperty, owl:DatatypeProperty, and rdf:Property nodes, sorted by inner code. | | context | Object | The JSON-LD @context map (prefix → namespace URI). |

Each item in classes and properties is a plain JSON-LD object. Its keys are RDF predicates in prefixed form (e.g. rdfs:label, rdfs:comment, rdfs:subClassOf) and its values are the corresponding objects.

Helper functions (utils)

The utils object is also available in every template.

utils.getHash(item)

Returns the local name (fragment or prefixed local part) of an RDF node.

h2(id=utils.getHash(c))= utils.getHash(c)

utils.print(value, single?)

Renders an RDF value (string, language-tagged literal, or resource) as an HTML string.

• If value is a plain string, it is returned as-is.
• If value is a language-tagged literal, the language tag is appended as a <small> element (unless single is true, in which case the best-match language is picked).
• If value is a resource (@id), it is rendered as an <a> link.
• If value is an array, all values are joined with newlines (or the first best-match is returned when single is true).

Use Pug's unescaped output (!=) because print may return HTML:

span!= utils.print(c['rdfs:comment']).replace(/\n/g, '<br/>')
span= utils.print(c['rdfs:label'], true)

utils.isSignificative(prop)

Returns false for internal JSON-LD bookkeeping keys (@id, @type, rdfs:isDefinedBy) that should not be displayed as features. Use it to filter the properties of a node:

each obj, prop in c
  if utils.isSignificative(prop)
    li
      span.prop= prop
      span.obj!= utils.print(obj)

Minimal template example

doctype html
html(lang="en")
  head
    title= utils.print(ontology['rdfs:label'], true)
    link(rel='stylesheet', href='styles.css')
  body
    h1 Classes
    ul
      each c in classes
        li
          a(href='#'+utils.getHash(c))= utils.print(c['rdfs:label'], true)

    each c in classes
      section(id=utils.getHash(c))
        h2= utils.print(c['rdfs:label'], true)
        p!= utils.print(c['rdfs:comment'], true)
        ul
          each obj, prop in c
            if utils.isSignificative(prop)
              li
                strong= prop
                span!= utils.print(obj)

Scripts

npm start              # Generate documentation (runs: node index)
npm run build:styles  # Compile Stylus to CSS
npm run watch:styles  # Watch Stylus files for changes and recompile
npm run lint          # Run ESLint
npm test              # Run linter

Installation via npm

Install as a dependency in your project:

npm install owl-coat

Then use it in your Node.js code:

const fs = require('fs-extra');
const path = require('path');
const pug = require('pug');
const ttl2jsonld = require('@frogcat/ttl2jsonld');

// Your custom logic using OWL Coat utilities
const utils = require('owl-coat/utils.js');

Note: The npm package includes templates and stylesheets but excludes the image assets (to reduce package size). Clone the repository if you need the sample images for the default template.

Publishing

Maintainers: to publish a new version to npm:

1. Update version in package.json
2. Commit and tag: git tag v1.0.0 && git push origin v1.0.0
3. Publish: npm publish

The files field in package.json ensures only necessary files are included in the npm package.

License

MIT