ro-crate-static-site

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).

Note: this repository is now ro-crate-static-site

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-static-site

CLI Usage

npx rocss [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")
    -c, --config <configPath>            Filepath or URL to a configuration file in JSON format.
    -m, --multipage-config <configPath>  Deprecated alias for --config.
    -s, --style <stylePath>              Filepath or URL to a CSS file. Overrides config style and default.css.
    --generate-config <configPath>       Generate a starter config file with empty structure and termMapping for crate class/property URIs.
    --rm                                 Remove ro-crate-preview.html and ro-crate-preview_html directory from the crate.
  -h, --help                          display help for command

CSS loading

CSS is loaded by the generator and injected into the HTML template (not linked with a stylesheet URL).

Style resolution order:

1. CLI --style
2. Config style (or root.style)
3. default.css in project root

Examples:

# Use default.css
npx rocss test_data/COOEE/crate

# Use style from config
npx rocss -c test_data/oral-history/oral-history-single-page-config.json test_data/oral-history/crate

# Override style from CLI
npx rocss --style test_data/oral-history/oral-history-blue.css test_data/COOEE/crate

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 rocss test_data/sample

Sample crate with tabular summary and no multipage output:

npx rocss -c test_data/sample/sample-config.json test_data/sample/crate

## Library Usage

To use this library in your own code, import the `renderSinglePage` function, e.g.:
```js
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');

Farms to freeways -- multiple pages

npx rocss -c test_data/f2fnew/f2fconfig.json test_data/f2fnew/data

Optional tabular summary settings for multipage configs

You can add a tabular block to a multipage config to generate tablular summary on the root page.

{
    "types": {
        "RepositoryCollection": {
            "template": "test_data/oral-history/templates/oral-history-collection-template.html"
        }
    },
    "root": {
        "template": "test_data/oral-history/templates/oral-history-root-template.html"
    },
    "tabular": {
        "mainNavType": "http://pcdm.org/models#Collection",
        "columnLimit": 6,
        "searchEnabled": true,
        "hideColumns": ["http://purl.org/dc/terms/conformsTo"],
        "includeFallbackColumns": true
    }
}

You can also provide explicit per-type navigation and columns with navigationByType:

{
    "multipage": false,
    "style": "oral-history-blue.css",
    "root": {"template": "template.html"},
    "navigationByType": {
        "http://pcdm.org/models#Collection": [
            {"uri": "http://schema.org/name", "label": "Collection name"},
            {"uri": "http://schema.org/description", "label": "Collection description"},
            {"uri": "http://schema.org/about", "label": "Collection subjects"},
            {"uri": "https://schema.org/holdingArchive", "label": "Collection holder"},
            {"uri": "http://schema.org/author", "label": "Contributor"}
        ]
    },
    "tabular": {
        "mainNavType": "http://pcdm.org/models#Collection",
        "columnLimit": 5,
        "searchEnabled": true,
        "columnSearchEnabled": false,
        "includeFallbackColumns": true
    }
}

Per-column visibility and facets:

• Add "hideInTable": true on a navigationByType column entry to hide that property from visible table columns for that type.
• Keep "addFacet": true on the same entry if you still want the property available as a filter facet.

Example:

{
    "uri": "http://purl.org/dc/terms#format",
    "label": "Format",
    "addFacet": true,
    "facetLabel": "format",
    "hideInTable": true
}

How columns are chosen:

• Column order follows propertyGroups from the resolved layout (or legacy inputGroups when present).
• If navigationByType is present, dropdown order follows config order.
• Columns with no values for that type are skipped.
• If includeFallbackColumns is true, extra populated properties not listed in propertyGroups can be appended.
• columnLimit caps the number of columns shown in the summary table.
• columnSearchEnabled enables per-column search inputs in the table header.
• mainNavType accepts either a bare type name or a full type URI.
• hideColumns hides columns by URI (with local-name matching fallback) when navigationByType is not configured.
• Internal default tabular config hides conformsTo columns unless explicitly re-added via navigationByType.

navigationByType accepts full type URIs. Matching includes a local-name fallback so equivalent URI variants (for example http/https) still resolve.

If you want tabular summaries without generating per-entity pages, set:

"multipage": false

in the config file.

Config reference

Top-level config keys currently supported:

• multipage: boolean. Generate per-entity pages when true.
• style: CSS path or URL.
• root.template: template path for the root page.
• propertyGroups: ordered property groups used in the property panel.
• inputGroups: legacy alias for propertyGroups (still accepted for backward compatibility).
• navigationByType: optional explicit tabular columns and labels by type URI.
• tabular: tabular summary behavior (mainNavType, columnLimit, searchEnabled, columnSearchEnabled, includeFallbackColumns, hideColumns).
• termMapping: label and visibility overrides for classes/properties.
• settings: UI behavior settings.

settings keys:

• maxListItemsWithoutSearch (number): list size threshold before inline find boxes are shown.
• showInfoLinks (boolean): show/hide definition info icons (ⓘ) across the UI.
• tabular (boolean): enable/disable generation of tabular summary data (default: false).

Example:

{
    "settings": {
        "maxListItemsWithoutSearch": 10,
        "showInfoLinks": false,
        "tabular": true
    }
}

Demo styles

• Default style: default.css
• Oral-history blue demo: test_data/oral-history/oral-history-blue.css

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.