ResearchObject · elichad · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -4,7 +4,7 @@ on:
   push:
     branches: ["main"]
   pull_request:
-    branches: ["main"]
+    branches: ["main", "ett-6.1.0"]
 
 jobs:
   build-site:
@@ -52,3 +52,8 @@ jobs:
         working-directory: ./docs
         run: |
           ! fgrep -R 'site.pages' _site
+
+      - name: Run custom theme checks
+        working-directory: ./docs
+        run: |
+          bundle exec ruby tests/test_html_pages.rb
diff --git a/docs/README.md b/docs/README.md
@@ -4,7 +4,7 @@ A file like [pages/about/background.md](pages/about/background.md) appears rende
 
 Note that files outside `docs` are not accessible within `github.io` and must be linked to by absolute URLs, e.g. <https://github.com/ResearchObject/ro-crate/blob/master/CODE_OF_CONDUCT.md>
 
-It is more important that pages render well at <https://researchobject.github.io/ro-crate/> than in this  preview within the GitHub repository, as some MarkDown features only apply to the GitHub Pages (e.g. the `{:toc}` macro and).
+It is more important that pages render well at <https://researchobject.github.io/ro-crate/> than in this  preview within the GitHub repository, as some MarkDown features only apply to the GitHub Pages (e.g. [callouts](#callouts)).
 
 ## Running Jekyll locally
 
@@ -84,49 +84,53 @@ Also ensure the page is removed from any sidebar listings.
 
 #### Excluding pages from rendering at all
 
-To avoid a page being rendered to the site at all (i.e. it has no URL outside of the GitHub repository), add it to the `exclude` list in [`_config.yml`](_config.yml)
+To avoid a page being rendered to the site at all (i.e. it has no URL outside of the GitHub repository), add it to the `exclude` list in [`_config.yml`](_config.yml).
+
+Filenames beginning with a dot (e.g. `.template.md`) are excluded from rendering by default.
 
 #### Table of Contents
 
 Typically, a table of contents is rendered in the right-sidebar (for level 2 headings), unless you specify `toc: false` in the front matter. 
-To show a full table of contents within the main page of the page, include the following:
 
-```
-{: .no_toc }
+### Callouts
 
-## Table of contents
-{: .no_toc .text-delta }
+With the ETT theme it is possible to insert colourful [callouts](https://elixir-belgium.github.io/elixir-toolkit-theme/markdown_cheat_sheet#callouts) to bring attention to caveats and best practices. 
 
-1. TOC
-{:toc}
-```
+These are written using the `callout.html` template with the `type` set as `tip`, `note`, `warning` or `important`. They can
+include a restricted set of Markdown.
 
-### Sections and child pages
+{% include callout.html type="note" title="Optional Title" content="JSON-LD supports [many other features](https://json-ld.org/) that SHOULD NOT be used excessively." %}
 
-Note that the [concatination](../Makefile) step to make single page HTML/PDF assumes `<div id="filename">` blobs in top of each section's markdown, as the `Makefile` replaces links to say `"appendix/jsonld.md"` with `#jsonld`. See commit [bfd9b2f530](https://github.com/ResearchObject/ro-crate/commit/bfd9b2f53075f464b069b017c9648460879dda94)
+Try to keep the callout short, like a single paragraph.
 
-### Admonition cards
+For the [Makefile](Makefile) rendering to PDF, a rudimentary [Pandoc filter](scripts/admonition.py)
+attempts to translate these blocks back to paragraph rendering, although they don't show up as a box. 
+See the [release procedure](RELEASE_PROCEDURE.md).
 
-With theme it is possible to insert colourful admonition cards to bring attention to caveats and best practices. 
-These are written as a Markdown code-block with the language set as `tip`, `note` or `warning`, and can
-include a restricted set of Markdown.
+Note that a future version of ETT will simplify the callout system to a style like the code block below. If/when that style is adopted in the spec pages, the Makefile must also be updated accordingly.
 
 ```
-{: .tip }
-> JSON-LD supports [many other features](https://json-ld.org/) that SHOULD NOT be used excessively.
+{: .note }
+> This is a note.
 ```
 
-Try to keep the admonition card short, like a single paragraph.
-
-For the [Makefile](Makefile) rendering to PDF, a rudimentary [Pandoc filter](scripts/admonition.py)
-attempts to translate these blocks back to paragraph rendering, although they don't show up as a box. 
-See the [release procedure](RELEASE_PROCEDURE.md).
 
 
 ### Theme config
 
 The [`_config.yml`](_config.yml) file specifies some site-wide properties like copyright text or which folders that need to be excluded from the navigation and/or search.
 
+## Special requirements for specification pages
+
+The specification Markdown files (under `_specification/`) are special, as they are used not only to generate the web pages, but also to generate the PDF and single-page HTML versions of the specification for releases. This means they require some special customizations:
+
+* there must be a level 1 heading with the chapter title at the start of the file, e.g. `# Chapter Title`. This must match the `title` in the Jekyll front matter for consistent display in different formats: in the web version, `title` is displayed, and the Markdown heading is hidden with custom CSS; in PDF and single-page HTML, the `title` is ignored, and the Markdown heading is displayed.
+  * special case: the `title` of the top-level `index.md` page for each specification version must instead match the Markdown heading in the `_metadata.liquid` file. Do not include a Markdown heading directly in `index.md`.
+* There must be an HTML element with `id="filename"` at the top of each chapter's markdown, as the `Makefile` replaces links to say `"appendix/jsonld.md"` with `#jsonld`. (See commit [bfd9b2f530](https://github.com/ResearchObject/ro-crate/commit/bfd9b2f53075f464b069b017c9648460879dda94).) In 1.2 and later, this is handled using [Markdown Heading IDs](https://www.markdownguide.org/extended-syntax/#heading-ids) on the chapter titles (e.g. `#Chapter Title {#filename}`); in 1.1 and earlier this is handled with `<div id="filename">` at the start of each Markdown file.
+
+
+The [Makefile](../Makefile) handles some other modifications automatically (e.g. changing callouts to plain text).
+
 ## References
 
 The [_includes/references.liquid](_includes/references.liquid) file includes Markdown [hyperlink references](https://kramdown.gettalong.org/syntax.html#reference-links) that can be used on shortform, e.g. `[CreativeWork]` gets expanded to `[CreativeWork](http://schema.org/CreativeWork)`  or `[creative work][CreativeWork]` becomes  `[creative work](http://schema.org/CreativeWork)`. This only works on `*.md` pages that have the `{% include references.liquid %}` footer.
diff --git a/docs/_sass/_custom_classes.scss b/docs/_sass/_custom_classes.scss
@@ -289,3 +289,11 @@ section#search-section {
 footer .container {
     display: none;
 }
+
+// hide h1s in the content section
+// reason: spec pages need an h1 defined in the Markdown for rendering to PDF
+//         but the web pages display the `title` from the front matter already
+//         so this hides the extra h1s when viewing the web version
+#content h1 {
+    display: none;
+}
diff --git a/docs/_specification/0.1.0/index.md b/docs/_specification/0.1.0/index.md
@@ -21,6 +21,7 @@ nav_exclude: true
    limitations under the License.
 -->
 
+# ROLite 0.1.0
 {: .no_toc }
 
 This first draft of ~~ROLite~~ [RO-Crate](../../) is more of an example playground to initiate discussion.

diff --git a/docs/_specification/0.2/index.md b/docs/_specification/0.2/index.md
@@ -22,6 +22,7 @@ nav_exclude: true
    limitations under the License.
 -->
 
+# RO-Crate Metadata Specification 0.2
 {: .no_toc }
 
 * Permalink: <https://w3id.org/ro/crate/0.2>

diff --git a/docs/_specification/1.0/index.md b/docs/_specification/1.0/index.md
@@ -24,6 +24,7 @@ nav_exclude: true
    limitations under the License.
 -->
 
+# RO-Crate Metadata Specification 1.0
 {:.no_toc}
 
 

diff --git a/docs/_specification/1.1/.metadata.md b/docs/_specification/1.1/.metadata.md
@@ -1,6 +1,4 @@
----
-title: RO-Crate Metadata Specification 1.1
----
+# RO-Crate Metadata Specification 1.1
 
 * Permalink: <https://w3id.org/ro/crate/1.1>
 * Published: 2022-01-19

diff --git a/docs/_specification/1.1/.references.md b/docs/_specification/1.1/.references.md
@@ -2,6 +2,8 @@
 title: References
 ---
 
+
+# References
 <!--  Below are reference links not rendered in HTML, see
 https://kramdown.gettalong.org/syntax.html#reference-links
 

diff --git a/docs/_specification/1.1/appendix/changelog.md b/docs/_specification/1.1/appendix/changelog.md
@@ -25,6 +25,9 @@ excerpt: List of changes in releases of this specifications
    limitations under the License.
 -->
 
+
+# APPENDIX: Changelog
+
 * [RO-Crate 1.1.3](https://github.com/ResearchObject/ro-crate/releases/tag/1.1.3) 
   * JSON-LD context https://w3id.org/ro/crate/1.1/context fix typo in mapping from `RepositoryObject` to <http://pcdm.org/2016/04/18/models#Object> [#243](https://github.com/ResearchObject/ro-crate/issues/243)
 * [RO-Crate 1.1.2](https://github.com/ResearchObject/ro-crate/releases/tag/1.1.2) 

diff --git a/docs/_specification/1.1/appendix/implementation-notes.md b/docs/_specification/1.1/appendix/implementation-notes.md
@@ -25,6 +25,8 @@ excerpt:
    limitations under the License.
 -->
 
+# APPENDIX: Implementation notes
+
 ## Programming with JSON-LD
 
 When implementing tools to work with RO-Crate it is not necessary to use JSON-LD software libraries, however, programmers should keep in mind the following:

diff --git a/docs/_specification/1.1/appendix/index.md b/docs/_specification/1.1/appendix/index.md
@@ -1,5 +1,5 @@
 ---
-title: Appendix
+title: Appendixes
 redirect_from:
   - /1.1-DRAFT/appendix
   - /1.1/appendix
@@ -24,3 +24,5 @@ has_children: true
    See the License for the specific language governing permissions and
    limitations under the License.
 -->
+
+# Appendixes
diff --git a/docs/_specification/1.1/appendix/jsonld.md b/docs/_specification/1.1/appendix/jsonld.md
@@ -30,6 +30,8 @@ grand_parent: RO-Crate 1.1
 
 <div id="jsonld"></div>
 
+# APPENDIX: RO-Crate JSON-LD
+
 It is not necessary to use [JSON-LD tooling] to generate or parse the _RO-Crate Metadata File_, although JSON-LD tools may make it easier to conform to this specification, e.g. handling relative URIs. It is however RECOMMENDED to use [JSON tooling][JSON] to handle [JSON][RFC 7159] syntax and escaping rules.
 
 This appendix shows a brief JSON-LD introduction for complying with the _RO-Crate Metadata File_ requirements.

diff --git a/docs/_specification/1.1/appendix/relative-uris.md b/docs/_specification/1.1/appendix/relative-uris.md
@@ -32,6 +32,8 @@ redirect_from:
 
 <div id="relative-uris"></div>
 
+# APPENDIX: Handling relative URI references
+
 The _RO-Crate Metadata File_ use _relative URI references_ to identify files and directories
 contained within the _RO-Crate Root_ and its children.  As described in section
 [Describing entities in JSON-LD](jsonld#describing-entities-in-json-ld) above, 

diff --git a/docs/_specification/1.1/contextual-entities.md b/docs/_specification/1.1/contextual-entities.md
@@ -32,6 +32,8 @@ parent: RO-Crate 1.1
 
 <div id="contextual-entities"></div>
 
+# Representing Contextual Entities
+
 The RO-Crate SHOULD contain additional information about _Contextual Entities_ for the use of both humans (in `ro-crate-preview.html`) and machines (in `ro-crate-metadata.json`). This also helps to maximize the extent to which an _RO-Crate_ is self-contained and self-describing, in that it reduces the need for the consumer of an RO-Crate to refer to external information which may change or become unavailable over time.
 
 ## Contextual vs Data entities

diff --git a/docs/_specification/1.1/data-entities.md b/docs/_specification/1.1/data-entities.md
@@ -32,6 +32,8 @@ parent: RO-Crate 1.1
    limitations under the License.
 -->
 
+# Data Entities
+
 The primary purpose for RO-Crate is to gather and describe a set of _Data entities_ in the form of:
 
 * Files

diff --git a/docs/_specification/1.1/index.md b/docs/_specification/1.1/index.md
@@ -1,5 +1,5 @@
 ---
-title: RO-Crate 1.1
+title: RO-Crate Metadata Specification 1.1
 has_children: true
 nav_order: 1
 redirect_from:

diff --git a/docs/_specification/1.1/introduction.md b/docs/_specification/1.1/introduction.md
@@ -26,6 +26,8 @@ parent: RO-Crate 1.1
    limitations under the License.
 -->
 
+# Introduction
+
 This document specifies a method, known as _RO-Crate_ (Research Object Crate), of aggregating and describing research data with associated metadata. RO-Crates can aggregate and describe any resource including files, URI-addressable resources, or use other addressing schemes to locate digital or physical data. RO-Crates can describe data both in aggregate and at the individual resource level, with metadata to aid in discovery, and for the re-use and long term management of data. Metadata provides the ability to describe the context of data and entities involved in its production, use and reuse. For example: who created it, using which equipment, software and workflows, under which license it can be re-used, where it was collected, and/or what it is *about*.
 
 RO-Crate uses JSON-LD to express this metadata using linked data, describing data resources as well as contextual entities such as people, organizations, software and equipment as a series of linked JSON-LD objects - using common published vocabularies, chiefly schema.org. 

diff --git a/docs/_specification/1.1/metadata.md b/docs/_specification/1.1/metadata.md
@@ -32,6 +32,8 @@ parent: RO-Crate 1.1
 
 <div id="metadata"></div>
 
+# RO-Crate Metadata
+
 RO-Crate aims to capture and describe the [Research Object][ResearchObject] using structured _metadata_.
 
 The _RO-Crate Metadata File Descriptor_ contains the metadata that describes the RO-Crate and its content, in particular:

diff --git a/docs/_specification/1.1/provenance.md b/docs/_specification/1.1/provenance.md
@@ -28,6 +28,8 @@ parent: RO-Crate 1.1
 
 <div id="provenance"></div>
 
+# Detailing provenance of entities
+
 ## Equipment used to create files
 
 To specify which **equipment** was used to create or update a [Data Entity](data-entities), the _RO-Crate JSON-LD_ SHOULD have a _Context Entity_ for each item of equipment which SHOULD be of `@type` [IndividualProduct]. The entity SHOULD have a serial number, manufacturer that identifies it as completely as possible. In this case the equipment is a bespoke machine. The equipment SHOULD be described on a web page, and the address of the description SHOULD be used as its `@id`.

diff --git a/docs/_specification/1.1/root-data-entity.md b/docs/_specification/1.1/root-data-entity.md
@@ -28,6 +28,8 @@ parent: RO-Crate 1.1
    limitations under the License.
 -->
 
+# Root Data Entity
+
 The **Root Data Entity** is a [Dataset] that represent the RO-Crate as a whole;
 a _Research Object_ that includes the _Data Entities_ and the related
 _Contextual Entities_.

diff --git a/docs/_specification/1.1/structure.md b/docs/_specification/1.1/structure.md
@@ -37,6 +37,8 @@ parent: RO-Crate 1.1
 
 <div id="structure"></div>
 
+# RO-Crate Structure
+
 The structure an _RO-Crate_ MUST follow is:
 
 ```

diff --git a/docs/_specification/1.1/terminology.md b/docs/_specification/1.1/terminology.md
@@ -24,6 +24,8 @@ parent: RO-Crate 1.1
    limitations under the License.
 -->
 
+# Terminology
+
 _RO-Crate_: A directory structure that contains a dataset, which is described in an _RO-Crate Metadata File_.
 
 _RO-Crate Root_: The top-level directory of the _RO-Crate_, indicated by the presence of the _RO-Crate Metadata File_ `ro-crate-metadata.json` (or `ro-crate-metadata.jsonld` for crates that comply with versions before v1.1 of this specification)

diff --git a/docs/_specification/1.1/workflows.md b/docs/_specification/1.1/workflows.md
@@ -30,6 +30,8 @@ parent: RO-Crate 1.1
 
 <div id="workflows"></div>
 
+# Workflows and Scripts
+
 Scientific workflows and scripts that were used (or can be used) to analyze or generate files contained in an RO-Crate MAY be embedded in an RO-Crate. See also the Provenance section on [Software Used to Create Files](provenance#software-used-to-create-files).
 
 _Workflows_ and _scripts_ SHOULD be described using [data entities](data-entities) of type [SoftwareSourceCode].

diff --git a/docs/_specification/1.2/.metadata.md b/docs/_specification/1.2/.metadata.md
@@ -1,6 +1,4 @@
----
-title: RO-Crate Metadata Specification 1.2
----
+# RO-Crate Metadata Specification 1.2
 
 * Permalink: <https://w3id.org/ro/crate/1.2>
 * Published: 2025-06-04

diff --git a/docs/_specification/1.2/appendix/changelog.md b/docs/_specification/1.2/appendix/changelog.md
@@ -27,7 +27,8 @@ excerpt: List of changes in releases of this specifications
    limitations under the License.
 -->
 
-<div id="changelog"></div>
+
+# APPENDIX: Changelog {#changelog}
 
 * [RO-Crate 1.2.0](https://github.com/ResearchObject/ro-crate/releases/tag/1.2.0) <https://w3id.org/ro/crate/1.2>
   * Clarified that the [RO-Crate Metadata Descriptor MUST have `@id` of `ro-crate-metadata.json`](../root-data-entity#ro-crate-metadata-descriptor) by removing conflicting statements elsewhere in the specification [#365](https://github.com/ResearchObject/ro-crate/pull/365)

diff --git a/docs/_specification/1.2/appendix/implementation-notes.md b/docs/_specification/1.2/appendix/implementation-notes.md
@@ -27,7 +27,7 @@ nav_order: 21
    limitations under the License.
 -->
 
-<div id="implementation-notes"></div>
+# APPENDIX: Implementation notes {#implementation-notes}
 
 ## Programming with JSON-LD
 

diff --git a/docs/_specification/1.2/appendix/index.md b/docs/_specification/1.2/appendix/index.md
@@ -26,7 +26,7 @@ has_children: true
    limitations under the License.
 -->
 
-<div id="appendix"></div>
+# Appendixes {#appendix}
 
 ## Contents
 * [Changelog](changelog)

diff --git a/docs/_specification/1.2/appendix/jsonld.md b/docs/_specification/1.2/appendix/jsonld.md
@@ -30,6 +30,8 @@ nav_order: 22
    limitations under the License.
 -->
 
+# APPENDIX: RO-Crate JSON-LD {#jsonld}
+
 It is not necessary to use [JSON-LD tooling] to generate or parse the _RO-Crate Metadata Document_, although JSON-LD tools may make it easier to conform to this specification, e.g. handling relative URIs. It is however RECOMMENDED to use [JSON tooling][JSON] to handle [JSON][RFC 7159] syntax and escaping rules.
 
 This appendix shows a brief JSON-LD introduction for complying with the _RO-Crate Metadata Document_ requirements.

diff --git a/docs/_specification/1.2/appendix/relative-uris.md b/docs/_specification/1.2/appendix/relative-uris.md
@@ -33,7 +33,7 @@ nav_order: 23
    limitations under the License.
 -->
 
-<div id="relative-uris"></div>
+# APPENDIX: Handling relative URI references {#relative-uris}
 
 In an _Attached RO-Crate Package_, the _RO-Crate Metadata File_ use _relative URI references_ 
 to identify files and directories

diff --git a/docs/_specification/1.2/contextual-entities.md b/docs/_specification/1.2/contextual-entities.md
@@ -32,7 +32,7 @@ parent: RO-Crate 1.2
    limitations under the License.
 -->
 
-<div id="contextual-entities"></div>
+# Representing Contextual Entities {#contextual-entities}
 
 The RO-Crate SHOULD contain additional information about _Contextual Entities_ for the use of both humans (in `ro-crate-preview.html`) and machines (in `ro-crate-metadata.json`). This also helps to maximize the extent to which an _RO-Crate_ is self-contained and self-describing, in that it reduces the need for the consumer of an RO-Crate to refer to external information which may change or become unavailable over time.
 

diff --git a/docs/_specification/1.2/crate-focus.md b/docs/_specification/1.2/crate-focus.md
@@ -28,7 +28,7 @@ parent: RO-Crate 1.2
    limitations under the License.
 -->
 
-<div id="crate-focus"></div>
+# The focus of an RO-Crate {#crate-focus}
 
 In addition to simple data packaging, RO-Crates may have a "main" entry point or topic (referenced with a singleton `mainEntity` property), or function as a bundle of one or more Contextual Entities referenced via the `mentions` property.
 

diff --git a/docs/_specification/1.2/data-entities.md b/docs/_specification/1.2/data-entities.md
@@ -30,7 +30,7 @@ parent: RO-Crate 1.2
    limitations under the License.
 -->
 
-<div id="data-entities"></div>
+# Data Entities {#data-entities}
 
 The primary purpose for RO-Crate is to gather and describe a set of _Data Entities_ in the form of:
 

diff --git a/docs/_specification/1.2/index.md b/docs/_specification/1.2/index.md
@@ -1,5 +1,5 @@
 ---
-title: RO-Crate 1.2
+title: RO-Crate Metadata Specification 1.2
 redirect_from:
   - /1.2-DRAFT/index
   - /1.2-DRAFT/about

diff --git a/docs/_specification/1.2/introduction.md b/docs/_specification/1.2/introduction.md
@@ -27,6 +27,8 @@ parent: RO-Crate 1.2
    limitations under the License.
 -->
 
+# Introduction
+
 This document specifies a method, known as _RO-Crate_ (Research Object Crate), of aggregating and describing data for distribution, re-use, publishing, preservation and archiving. RO-Crates aggregate data into a Dataset, and may describe any resource including files, URI-addressable resources, or use other addressing schemes to locate digital or physical data. Describing resources includes technical metadata such as file sizes and types as well as contextual information including how and where datasets and files were created, how they were collated and collected, who was involved in the process, what equipment and software was used, who funded the work, how to cite it, and crucially, how it may be reused, and by whom.
 
 The core of RO-Crate is a machine-readable linked-data document in JSON-LD format known as an **RO-Crate Metadata Document**. RO-Crate metadata documents can, to a large extent, be created and processed just like any other JSON: knowledge of JSON-LD is not needed, unless extending RO-Crate with additional concepts or combining RO-Crate with other Linked Data technologies.
-Original file line number
+Diff line change
@@ Expand Up / @@ -24,6 +24,7 @@ nav_exclude: true @@
        limitations under the License.
     -->
+    # RO-Crate Metadata Specification 1.0
     {:.no_toc}
@@ Expand Down @@