Merge pull request ResearchObject#499 from elichad/page-descriptions

elichad · web-flow · commit ad848cd484b7 · 2025-11-14T18:39:52.000+01:00
Add page descriptions/excerpts to improve page previews and SEO
diff --git a/docs/_includes/head.html b/docs/_includes/head.html
@@ -19,7 +19,7 @@
   {%- assign subtitle = page.type | replace: "_", " " %}
   {%- endif %}
   {%- capture title %}{% if page.url == "/" %}{{site.title}}{% elsif page.title %}{% if subtitle %}{{subtitle}}: {% endif %}{{ page.title }} | {{ site.title }}{%- else %}{{ site.title }}{% endif %}{% endcapture %}
-  {%- capture description %}{% if page.url == "/" %}{{site.description}}{% elsif page.description %}{{ page.description | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% elsif page.summary %}{{ page.summary | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% else %}{{ page.content | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% endif %}{% endcapture %}  
+  {%- capture description %}{% if page.url == "/" or page.url == "/index" %}{{site.description}}{% elsif page.description %}{{ page.description | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% elsif page.summary %}{{ page.summary | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% elsif page.excerpt %}{{ page.excerpt | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% else %}{{ page.content | strip_html | replace: '\n', ' ' | truncatewords: 30, '...' }}{% endif %}{% endcapture %}  
   <meta charset="utf-8">
   <meta http-equiv="X-UA-Compatible" content="IE=edge">
   <title>{{title}}</title>
diff --git a/docs/_specification/1.0/index.md b/docs/_specification/1.0/index.md
@@ -1,5 +1,7 @@
 ---
 title: RO-Crate 1.0
+excerpt: |
+  This document specifies a method, known as _RO-Crate_ (Research Object Crate), of organizing file-based data with associated metadata, using [linked data] principles, in both human and machine readable formats, with the ability to include additional domain-specific metadata.
 redirect_from: 
   - /1.0/
 nav_exclude: true
diff --git a/docs/_specification/1.1/appendix/jsonld.md b/docs/_specification/1.1/appendix/jsonld.md
@@ -3,6 +3,10 @@ title: RO-Crate JSON-LD
 redirect_from:
   - /1.1-DRAFT/appendix/jsonld
   - /1.1/appendix/jsonld
+excerpt: |
+  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.
 parent: Appendix
 grand_parent: RO-Crate 1.1
 ---
diff --git a/docs/_specification/1.1/appendix/relative-uris.md b/docs/_specification/1.1/appendix/relative-uris.md
@@ -1,5 +1,11 @@
 ---
 title: Handling relative URI references
+excerpt: |
+  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, 
+  relative URI references are also frequently used for 
+  identifying _Contextual entities_.
 parent: Appendix
 grand_parent: RO-Crate 1.1
 redirect_from:
diff --git a/docs/_specification/1.1/data-entities.md b/docs/_specification/1.1/data-entities.md
@@ -3,6 +3,14 @@ title: Data Entities
 redirect_from:
   - /1.1-DRAFT/data-entities
   - /1.1/data-entities
+excerpt: |
+  The primary purpose for RO-Crate is to gather and describe a set of _Data entities_ in the form of:
+
+  * Files
+  * Directories
+  * Web resources
+
+  The data entities can be further described by referencing [contextual entities](contextual-entities) such as persons, organizations and publications.
 nav_order: 6
 parent: RO-Crate 1.1
 ---
diff --git a/docs/_specification/1.1/introduction.md b/docs/_specification/1.1/introduction.md
@@ -3,6 +3,8 @@ title: Introduction
 redirect_from:
   - /1.1-DRAFT/introduction
   - /1.1/introduction
+excerpt: |
+  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*.
 nav_order: 1
 parent: RO-Crate 1.1
 ---
diff --git a/docs/_specification/1.1/provenance.md b/docs/_specification/1.1/provenance.md
@@ -3,6 +3,8 @@ title: Provenance of entities
 redirect_from:
   - /1.1-DRAFT/provenance
   - /1.1/provenance
+excerpt: |
+  To specify which **equipment** was used to create or update a [Data Entity](data-entities), the _RO-Crate JSON-LD_ SHOULD have a _Contextual Entity_ for each item of equipment which SHOULD be of `@type` [IndividualProduct]. The entity SHOULD have a serial number and manufacturer that identify the equipment as completely as possible. In the following 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`.
 nav_order: 8
 parent: RO-Crate 1.1
 ---
diff --git a/docs/_specification/1.1/root-data-entity.md b/docs/_specification/1.1/root-data-entity.md
@@ -3,6 +3,10 @@ title: Root Data Entity
 redirect_from:
   - /1.1-DRAFT/root-data-entity
   - /1.1/root-data-entity
+excerpt: |
+  The **Root Data Entity** is a [Dataset] that represents the RO-Crate as a whole;
+   a _Research Object_ that includes the _Data Entities_ and the related
+   _Contextual Entities_.
 nav_order: 5
 parent: RO-Crate 1.1
 ---
diff --git a/docs/_specification/1.1/structure.md b/docs/_specification/1.1/structure.md
@@ -3,6 +3,17 @@ title: RO-Crate Structure
 redirect_from:
   - /1.1-DRAFT/structure
   - /1.1/structure
+excerpt: |
+  The structure an _RO-Crate_ MUST follow is:
+
+  ```
+  <RO-Crate root directory>/
+  |   ro-crate-metadata.json    # RO-Crate Metadata File MUST be present 
+  |   ro-crate-preview.html     # RO-Crate Website homepage MAY be present
+  |   ro-crate-preview_files/   # MAY be present
+  |    | [other RO-Crate Website files]
+  |   [payload files and directories]  # 0 or more
+  ```
 nav_order: 3
 parent: RO-Crate 1.1
 ---
diff --git a/docs/_specification/1.2/appendix/implementation-notes.md b/docs/_specification/1.2/appendix/implementation-notes.md
@@ -1,5 +1,6 @@
 ---
 title: Implementation notes
+description: Guidance on programming with JSON-LD, combining RO-Crate with other packaging schemes, and repository-specific identifiers
 redirect_from:
   - /1.2-DRAFT/appendix/implementation-notes
   - /specification/1.2-DRAFT/appendix/implementation-notes
diff --git a/docs/_specification/1.2/appendix/jsonld.md b/docs/_specification/1.2/appendix/jsonld.md
@@ -4,6 +4,10 @@ redirect_from:
   - /1.2-DRAFT/appendix/jsonld
   - /specification/1.2-DRAFT/appendix/jsonld
   - /specification/1.2-RC1/appendix/jsonld
+excerpt: |
+  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.
 parent: Appendix
 grand_parent: RO-Crate 1.2
 nav_order: 22
diff --git a/docs/_specification/1.2/appendix/relative-uris.md b/docs/_specification/1.2/appendix/relative-uris.md
@@ -4,6 +4,13 @@ redirect_from:
   - /1.2-DRAFT/appendix/relative-uris
   - /specification/1.2-DRAFT/appendix/relative-uris
   - /specification/1.2-RC1/appendix/relative-uris
+excerpt: |
+  In an _Attached RO-Crate Package_, 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), 
+  relative URI references are also frequently used for 
+  identifying _Contextual entities_.
 parent: Appendix
 grand_parent: RO-Crate 1.2
 nav_order: 23
diff --git a/docs/_specification/1.2/data-entities.md b/docs/_specification/1.2/data-entities.md
@@ -4,6 +4,11 @@ redirect_from:
   - /1.2-DRAFT/data-entities
   - /specification/1.2-DRAFT/data-entities
   - /specification/1.2-RC1/data-entities
+excerpt: |
+  The primary purpose for RO-Crate is to gather and describe a set of _Data Entities_ in the form of: 
+  
+  * Actual files which are datastreams available on the local file system or over the web -- when represented in the RO-Crate Metadata Document, these have the type `File`.
+  * Folders (or directories) of files -- represented using the type `Dataset`.
 nav_order: 6
 parent: RO-Crate 1.2
 ---
diff --git a/docs/_specification/1.2/introduction.md b/docs/_specification/1.2/introduction.md
@@ -4,6 +4,8 @@ redirect_from:
   - /1.2-DRAFT/introduction
   - /specification/1.2-DRAFT/introduction
   - /specification/1.2-RC1/introduction
+excerpt: |
+  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.
 nav_order: 1
 parent: RO-Crate 1.2
 ---
diff --git a/docs/_specification/1.2/provenance.md b/docs/_specification/1.2/provenance.md
@@ -4,6 +4,8 @@ redirect_from:
   - /1.2-DRAFT/provenance
   - /specification/1.2-DRAFT/provenance
   - /specification/1.2-RC1/provenance
+excerpt: |
+  To specify which **equipment** was used to create or update a [Data Entity](data-entities), the _RO-Crate JSON-LD_ SHOULD have a _Contextual Entity_ for each item of equipment which SHOULD be of `@type` [IndividualProduct]. The entity SHOULD have a serial number and manufacturer that identify the equipment as completely as possible. In the following 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`.
 nav_order: 9
 parent: RO-Crate 1.2 
 ---
diff --git a/docs/_specification/1.2/root-data-entity.md b/docs/_specification/1.2/root-data-entity.md
@@ -4,6 +4,10 @@ redirect_from:
   - /1.2-DRAFT/root-data-entity
   - /specification/1.2-DRAFT/root-data-entity
   - /specification/1.2-RC1/root-data-entity
+excerpt: |
+  The **Root Data Entity** is a [Dataset] that represents the RO-Crate as a whole;
+   a _Research Object_ that includes the _Data Entities_ and the related
+   _Contextual Entities_.
 nav_order: 5
 parent: RO-Crate 1.2 
 ---
diff --git a/docs/_specification/1.2/structure.md b/docs/_specification/1.2/structure.md
@@ -4,6 +4,18 @@ redirect_from:
   - /1.2-DRAFT/structure
   - /specification/1.2-DRAFT/structure
   - /specification/1.2-RC1/structure
+excerpt: |
+  An [_RO-Crate Metadata Document_](#ro-crate-metadata-document-ro-crate-metadatajson) is used to package data in one of two ways:
+  
+  1.  An _Attached  RO-Crate Package_ that defines an on-disk collection of data:
+  - It is defined within a file-system-like service as a directory (known as the _RO-Crate Root_) with the _RO-Crate Metadata Document_ saved in a file-like entity with a file name of `ro-crate-metadata.json`.
+  - References to files and directories in the _RO-Crate Metadata Document_ are present in the RO-Crate or available online as [Web-based Data Entities](data-entities.html#web-based-data-entities).
+  - Typically, software processing an _Attached RO-Crate Package_ would be passed a path to a directory or a zip file.
+  2.  A _Detached RO-Crate Package_:
+    - Is defined by a stand-alone _RO-Crate Metadata Document_ which may be stored in a file or distributed via an API.
+    - References to files and directories in the _RO-Crate Metadata Document_ are all Web-based Data Entities.
+    - If stored in a file, known as a _Detached RO-Crate Metadata File_, the filename SHOULD be `${prefix}-ro-crate-metadata.json` rather than `ro-crate-metadata.json` where the variable `${prefix}` is a human readable version of the dataset's ID or name, to signal that on disk, the presence of the file does not indicate an _Attached RO-Crate Data Package_.
+    - Typically, software processing a _Detached RO-Crate Package_ would be passed a path to a file, an absolute URI, or a JSON string or object, without a directory context.
 nav_order: 3
 parent: RO-Crate 1.2
 ---
diff --git a/docs/_specification/1.3-DRAFT/appendix/jsonld.md b/docs/_specification/1.3-DRAFT/appendix/jsonld.md
@@ -2,6 +2,11 @@
 title: RO-Crate JSON-LD
 redirect_from:
   - /1.3-DRAFT/appendix/jsonld
+excerpt: |
+  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.
+
 parent: Appendix
 grand_parent: RO-Crate 1.3-DRAFT
 nav_order: 22
diff --git a/docs/_specification/1.3-DRAFT/appendix/relative-uris.md b/docs/_specification/1.3-DRAFT/appendix/relative-uris.md
@@ -2,6 +2,13 @@
 title: Handling relative URI references
 redirect_from:
   - /1.3-DRAFT/appendix/relative-uris
+excerpt: |
+  In an _Attached RO-Crate Package_, 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), 
+  relative URI references are also frequently used for 
+  identifying _Contextual entities_.
 parent: Appendix
 grand_parent: RO-Crate 1.3-DRAFT
 nav_order: 23
diff --git a/docs/_specification/1.3-DRAFT/data-entities.md b/docs/_specification/1.3-DRAFT/data-entities.md
@@ -2,6 +2,11 @@
 title: Data Entities
 redirect_from:
   - /1.3-DRAFT/data-entities
+excerpt: |
+  The primary purpose for RO-Crate is to gather and describe a set of _Data Entities_ in the form of: 
+  
+  * Actual files which are datastreams available on the local file system or over the web -- when represented in the RO-Crate Metadata Document, these have the type `File`.
+  * Folders (or directories) of files -- represented using the type `Dataset`.
 nav_order: 6
 parent: RO-Crate 1.3-DRAFT
 ---
diff --git a/docs/_specification/1.3-DRAFT/introduction.md b/docs/_specification/1.3-DRAFT/introduction.md
@@ -2,6 +2,8 @@
 title: Introduction
 redirect_from:
   - /1.3-DRAFT/introduction
+excerpt: |
+  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.
 nav_order: 1
 parent: RO-Crate 1.3-DRAFT
 ---
diff --git a/docs/_specification/1.3-DRAFT/provenance.md b/docs/_specification/1.3-DRAFT/provenance.md
@@ -2,6 +2,8 @@
 title: Provenance of entities
 redirect_from:
   - /1.3-DRAFT/provenance
+excerpt: |
+  To specify which **equipment** was used to create or update a [Data Entity](data-entities), the _RO-Crate JSON-LD_ SHOULD have a _Contextual Entity_ for each item of equipment which SHOULD be of `@type` [IndividualProduct]. The entity SHOULD have a serial number and manufacturer that identify the equipment as completely as possible. In the following 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`.
 nav_order: 9
 parent: RO-Crate 1.3-DRAFT 
 ---
diff --git a/docs/_specification/1.3-DRAFT/root-data-entity.md b/docs/_specification/1.3-DRAFT/root-data-entity.md
@@ -2,6 +2,10 @@
 title: Root Data Entity
 redirect_from:
   - /1.3-DRAFT/root-data-entity
+excerpt: |
+  The **Root Data Entity** is a [Dataset] that represents the RO-Crate as a whole;
+   a _Research Object_ that includes the _Data Entities_ and the related
+   _Contextual Entities_.
 nav_order: 5
 parent: RO-Crate 1.3-DRAFT 
 ---
diff --git a/docs/_specification/1.3-DRAFT/structure.md b/docs/_specification/1.3-DRAFT/structure.md
@@ -2,6 +2,18 @@
 title: RO-Crate Structure
 redirect_from:
   - /1.3-DRAFT/structure
+excerpt: |
+  An [_RO-Crate Metadata Document_](#ro-crate-metadata-document-ro-crate-metadatajson) is used to package data in one of two ways:
+  
+  1.  An _Attached  RO-Crate Package_ that defines an on-disk collection of data:
+  - It is defined within a file-system-like service as a directory (known as the _RO-Crate Root_) with the _RO-Crate Metadata Document_ saved in a file-like entity with a file name of `ro-crate-metadata.json`.
+  - References to files and directories in the _RO-Crate Metadata Document_ are present in the RO-Crate or available online as [Web-based Data Entities](data-entities.html#web-based-data-entities).
+  - Typically, software processing an _Attached RO-Crate Package_ would be passed a path to a directory or a zip file.
+  2.  A _Detached RO-Crate Package_:
+    - Is defined by a stand-alone _RO-Crate Metadata Document_ which may be stored in a file or distributed via an API.
+    - References to files and directories in the _RO-Crate Metadata Document_ are all Web-based Data Entities.
+    - If stored in a file, known as a _Detached RO-Crate Metadata File_, the filename SHOULD be `${prefix}-ro-crate-metadata.json` rather than `ro-crate-metadata.json` where the variable `${prefix}` is a human readable version of the dataset's ID or name, to signal that on disk, the presence of the file does not indicate an _Attached RO-Crate Data Package_.
+    - Typically, software processing a _Detached RO-Crate Package_ would be passed a path to a file, an absolute URI, or a JSON string or object, without a directory context.
 nav_order: 3
 parent: RO-Crate 1.3-DRAFT
 ---
diff --git a/docs/pages/about/about_ro_crate.md b/docs/pages/about/about_ro_crate.md
@@ -1,5 +1,6 @@
 ---
 title: About RO-Crate
+description: What RO-Crate is, how RO-Crate makes research FAIR, and how to get started
 sidebar: about
 ---
 
diff --git a/docs/pages/community/blog.md b/docs/pages/community/blog.md
@@ -1,5 +1,6 @@
 ---
 title: Blog
+description: Latest updates from the RO-Crate community
 permalink: /blog
 sidebar: blog
 ---
diff --git a/docs/pages/community/community.md b/docs/pages/community/community.md
@@ -1,5 +1,6 @@
 ---
 title: Community
+description: The RO-Crate team, community meetings, and how to get in touch
 ---
 <!--
    Copyright 2019-2024 The University of Manchester and RO-Crate contributors 
diff --git a/docs/pages/community/outreach.md b/docs/pages/community/outreach.md
@@ -1,5 +1,6 @@
 ---
 title: Outreach and Publications
+description: Recent publications, presentations, and citations of RO-Crate
 ---
 <!--
    Copyright 2019-2025 The University of Manchester and RO Crate contributors 
diff --git a/docs/pages/domains.md b/docs/pages/domains.md
@@ -1,7 +1,10 @@
 ---
 title: Domains
+description: This page organises the RO-Crate use cases based on different research domains.
 layout: default
 sidebar: main
 ---
 
-{% include section-navigation-tiles.html type="domains" search=true %}
+This page organises the use cases based on different research domains, which may have different approaches on how they manage their data. Click on a domain to see the related use cases.
+
+{% include section-navigation-tiles.html type="domains" search=true %}
diff --git a/docs/pages/resources/examples.md b/docs/pages/resources/examples.md
@@ -1,5 +1,6 @@
 ---
 title: Examples
+description: Example RO-Crates from the specification and real-world applications
 ---
 <!--
    Copyright 2019-2020 The University of Manchester and RO Crate contributors 
diff --git a/docs/pages/resources/tools.md b/docs/pages/resources/tools.md
@@ -1,5 +1,6 @@
 ---
 title: Tools and resources list
+description: RO-Crate tools and resources developed by the community
 datatable: true
 sidebar: resources
 ---
diff --git a/docs/pages/resources/tutorials.md b/docs/pages/resources/tutorials.md
@@ -1,5 +1,6 @@
 ---
 title: Tutorials
+description: Technical tutorials and videos for learning how to use RO-Crate
 sidebar: resources
 ---
 <!--
@@ -36,4 +37,3 @@ sidebar: resources
   * [Workflow Run RO-Crate introduction](https://training.galaxyproject.org/topics/fair/tutorials/ro-crate-workflow-run-ro-crate/tutorial.html): guides you through constructing an RO-Crate which captures an execution of a computational workflow.
 
 {% include callout.html type="tip" content="The [Crate-O](https://language-research-technology.github.io/crate-o/) and [RO-Crate playground](https://ro-crate.ldaca.edu.au/) provide graphical ways to create and explore RO-Crate." %}
-
diff --git a/docs/pages/resources/vocabularies.md b/docs/pages/resources/vocabularies.md
@@ -1,5 +1,6 @@
 ---
 title: Vocabularies
+description: Useful vocabularies for extending RO-Crates, and tips on how to use them
 sidebar: resources
 ---
 
diff --git a/docs/pages/roles.md b/docs/pages/roles.md
@@ -1,7 +1,12 @@
 ---
 title: Roles
+description: This page organises the RO-Crate use cases based on the different roles a professional can have in research data management.
 layout: default
 sidebar: main
 ---
 
-{% include section-navigation-tiles.html type="roles" search=true %}
+# Roles
+
+This page organises the use cases based on the different roles a professional can have in research data management. Click on a role to see the related use cases.
+
+{% include section-navigation-tiles.html type="roles" search=true %}
diff --git a/docs/pages/specification.md b/docs/pages/specification.md
diff --git a/docs/pages/tasks.md b/docs/pages/tasks.md
diff --git a/docs/pages/tasks/software_development.md b/docs/pages/tasks/software_development.md
diff --git a/docs/pages/use_cases.md b/docs/pages/use_cases.md
