ro-crate-html-lite

A tool to create a complete, completely static ro-crate-preview.html file with the same functionality as ro-crate-html-js but without any dependence on online resources or JavaScript (except for some small helpers).

HTML Preview Lite is available without any installation at the RO-Crate Playground.

A recipe is available here to guide a user intending to replicate the work with their own data.

Install

npm install ro-crate-html-lite

CLI Usage

npx roc-html [options] <path_to_crate_directory>

Create an HTML file preview for an RO-Crate from a specified directory.

Arguments:
  path_to_crate_directory             Path to the crate directory.

Options:
  -l, --layout <layoutPath>           Filepath or URL to a layout file in JSON format. This forces the script to use the specified layout instead of the default or the one present in the
                                      crate. Use a raw link if the URL is from GitHub. (Default:
                                      "https://github.com/Language-Research-Technology/crate-o/blob/main/src/lib/components/default_layout.json")
  -m --multipage-config <configPath>  Filepath or URL to a multipage configuration file in JSON format.
  -h, --help                          display help for command

About Page

To generate an About page for the site:

1. Include an entry for the file in the RO-Crate with @type of File and AboutPage. Use the path to the about content (in markdown format) as the entry's @id. The encodingFormat describes the markdown file media type, and isRef_about indicates that the about information is related to the collection (rather than, say one of the collection objects).

{
    "@id": "about/about.md",
    "@type": [
        "File",
        "AboutPage"
    ], 
    "encodingFormat":	"text/markdown",
    "isRef_about": "./"
},

2. Save the markdown file in the crate directory according to the path given as the file ID.

3. Associate the AboutPage type with a template in the multipage config.

Run with test data

Sample crate:

npx roc-html test_data/sample

Farms to freeways -- multipages

npx roc-html  -m test_data/f2fnew/f2fconfig.json test_data/f2fnew/data

Library Usage

To use this library in your own code, import the renderSinglePage function, e.g.:

import { renderSinglePage } from "ro-crate-html-lite";
import { ROCrate } from 'ro-crate';
import { readFile, writeFile } from 'node:fs/promises';

const json = JSON.parse(await readFile('ro-crate-metadata.json', 'utf-8'));
const crate = await ROCrate.create(json);
const previewContent = await renderSinglePage({ crate });
await writeFile('./preview.html', previewContent, 'utf-8');

Contributing

To format the template run npm run format. To test any changes to the default template.html, run the npm run build command first to generate the pre-compiled template template.js.

HTML Validation continuous integration

This repo has HTML validation set up to run on push/PR. It prints the report on the summary page of each Actions workflow run. The CI run won't fail on any validation errors, it's just for our information.

The validator is currently set up to only check test_data/**/ro-crate-preview.html files, this means that multipage previews won't be validated. Since the purpose of the validation is to check, by proxy, the validity of the template, CI for the multipage previews will be added as separate workflow in the future.