Metalsmith plugin for generating Web documentation for a linked data vocabulary. Inspired by https://schema.org
- Node v16
- Metalsmith (^2.3.0)
- Metalsmith Layouts (^2.3.1) plus a JSTransformer of your choosing (preferrably EJS)
- Metalsmith Permalinks (^2.2.0)
- Clownface
- Docker (optional but desirable)
- Create a new static Web site using metalsmith
npm install metalsmith-ldschema
- Create one or more RDF files in your site directory. Your rdf-schema vocabulary will be defined in these files. While any RDF serialization should be supported by the site generator, it has at present been tested with JSON-LD and Turtle
The following represents an example configuration:
metalsmith(__dirname)
.source('./src')
.destination('./site')
.use(ldschema({
classLayout: 'class.hbs',
propertyLayout: 'property.hbs',
indexLayout: 'index.hbs',
base: 'http://schema.howarddierking.com'
}));
classLayout
(required) - Layout file to use when renderingrdfs:Class
terms.propertyLayout
(required) - Layout file to use when renderingrdf:Property
terms.indexLayout
(required) - Layout file to use when rendering an index page of allrdfs:Class
terms.base
(required) - Hostname (including scheme) for the Web site. This value is used as a mask for determining whether or not thehref
value in the view model is an absolute or relative URI. Ifbase
matches the url.origin value of a term'sid
,href
will be a relative URI - otherwise, it will be an absolute URI.- NOTE: as of the current refactoring, the determination logic has been elided and needs to be added back
A common convention in ontology building is to use casing to differentiate classes from properties. This means that it's not uncommon to have a property and a class with the same name but different casing. Popular file systems like OSX's HFS have support for case-sensitivity, but it requires additional operating system configuration (e.g. journaling) which may be made increasingly complex by the addition of developer operating systems.
Rather than ask users to change core OS settings, the Docker image metalsmith-ldjson-server
is provided as a local server. This server is built on Alpine Linux and a file system that provides full support for case-sensitive filenames.
To use, simply mount your metalsmith-ldschema project directory into /project
, map your desired local port to 8080
in the container and execute a command as follows:
docker run -it \
-v "$(pwd):/project" \
-p 8080:8080 \
--entrypoint="" \
--workdir="/project" \
node:lts-gallium \
sh -c "npm install && npm run build"
Tests for the plugin can be run with npm run test
from within the plugin directory.