diff --git a/.gitignore b/.gitignore
index b2d6de30624f651a6c584d4faefafceac6302be1..51d2e0f9105c3a182f45b7aaafb6aee53ca00ced 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,7 +2,7 @@
/node_modules
# Production
-/build
+/docs/_build
# Generated files
.docusaurus
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index e3628c0c2cbd8fb55fdb319b7eba7efaf50a4757..65f249862c4660bcf258035aa37740be2401ec67 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -6,12 +6,12 @@ stages:
docs-build:
stage: build
- image: python:latest
+ image: python:3.10
script:
- pip install -U jupyter-book
- jupyter-book clean docs
+ - jupyter-book toc from-project docs > docs/_toc.yml
- jupyter-book build docs
- - ls
artifacts:
paths:
- docs/_build/
diff --git a/docs/guides/web-api/categories-api.md b/docs/guides/web-api/categories-api.md
new file mode 100644
index 0000000000000000000000000000000000000000..d5b0e753fc62f2bd8a59a9d955692bad7ec2d401
--- /dev/null
+++ b/docs/guides/web-api/categories-api.md
@@ -0,0 +1,81 @@
+---
+displayed_sidebar: guidesSidebar
+sidebar_position: 3
+---
+
+# /categories
+
+This API provides the user information on the basic categories by the which the information in the HKG is grouped, and the total number of records found for each of this categories, respectively.
+
+### Method
+
+GET
+
+### Search Params
+
+None
+
+### URL
+
+[https://search.unhide.helmholtz-metadaten.de/api/categories](https://search.unhide.helmholtz-metadaten.de/api/categories)
+
+### Response Model
+
+```
+[
+ {
+ id: string,
+ text: string,
+ count: number
+ }
+]
+```
+
+where, `id` is the identifier of the category, `text` is the name of the category to be displayed on the UI, and `count` presents the total number of records available for the given category
+
+#### Example
+
+```
+[
+ {
+ id: "datasets",
+ text: "Datasets",
+ count: 411935,
+ },
+ {
+ id: "software",
+ text: "Software",
+ count: 3521,
+ },
+ {
+ id: "documents",
+ text: "Documents",
+ count: 1679342,
+ },
+ {
+ id: "instruments",
+ text: "Instruments",
+ count: 0,
+ },
+ {
+ id: "experts",
+ text: "Experts",
+ count: 229601,
+ },
+ {
+ id: "institutions",
+ text: "Institutions",
+ count: 64472,
+ },
+ {
+ id: "trainings",
+ text: "Trainings",
+ count: 667,
+ },
+ {
+ id: "projects",
+ text: "Projects",
+ count: 0,
+ },
+ ]
+```
diff --git a/docs/guides/web-api/hello-api.md b/docs/guides/web-api/hello-api.md
new file mode 100644
index 0000000000000000000000000000000000000000..03e7a6ae145fd363426bfc3f3222d0da91d29577
--- /dev/null
+++ b/docs/guides/web-api/hello-api.md
@@ -0,0 +1,36 @@
+---
+displayed_sidebar: guidesSidebar
+sidebar_position: 2
+---
+
+# /hello
+
+This API is currently used to test that the server is up and available. It will eventually be pointing to this documentation.
+
+### Method
+
+GET
+
+### Search Params
+
+None
+
+### URL
+
+[https://search.unhide.helmholtz-metadaten.de/api/hello](https://search.unhide.helmholtz-metadaten.de/api/hello)
+
+### Response Model
+
+```
+{
+ "message": string
+}
+```
+
+#### Example
+
+```
+{
+ "message": "Hello from Next.js!"
+}
+```
diff --git a/docs/guides/web-api/intro.md b/docs/guides/web-api/intro.md
deleted file mode 100644
index eaf6b0e5a4768e3c4943beaf06a33588c6551f9d..0000000000000000000000000000000000000000
--- a/docs/guides/web-api/intro.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-displayed_sidebar: guidesSidebar
-sidebar_position: 3
----
-
-### Web API GUIDE
diff --git a/docs/guides/web-api/introduction.md b/docs/guides/web-api/introduction.md
new file mode 100644
index 0000000000000000000000000000000000000000..e02a5d340b741f686be8c6ac71606d614a2c9cbe
--- /dev/null
+++ b/docs/guides/web-api/introduction.md
@@ -0,0 +1,8 @@
+---
+displayed_sidebar: guidesSidebar
+sidebar_position: 1
+---
+
+# Introduction
+
+The web APIs related to UnHIDE are made available at [https://search.unhide.helmholtz-metadaten.de/api/[endpoint]](https://search.unhide.helmholtz-metadaten.de/api/hello). There are currently four APIs defined, the details of which are covered in the following sections
diff --git a/docs/guides/web-api/json-ld-source-api.md b/docs/guides/web-api/json-ld-source-api.md
new file mode 100644
index 0000000000000000000000000000000000000000..3eb789ff031b83b436206f92c4ed2c31a51d3b88
--- /dev/null
+++ b/docs/guides/web-api/json-ld-source-api.md
@@ -0,0 +1,66 @@
+---
+displayed_sidebar: guidesSidebar
+sidebar_position: 5
+---
+
+# /source
+
+This API provides the user the JSON-LD object containing information of a record for the given ID.
+
+### Method
+
+GET
+
+### Search Params
+
+`id` - the identifier value of the record of interest
+
+#### Examples
+
+`id=e6be83435b277f34cab97adbefbe7b03` Or
+`id=https%3A%2F%2Fror.org%2F04t3en479`
+
+### URL
+
+[https://search.unhide.helmholtz-metadaten.de/api/source?id=](https://search.unhide.helmholtz-metadaten.de/api/source?id=)
+
+### Response Model
+
+```
+{
+ @type: string,
+ ...
+}
+```
+
+where, `@type` is the type of the metadata record identified,
+additionally, all information that is avaliable in the record, depending on its type is sent across as part of the response object
+
+#### Examples
+
+For `id=https%3A%2F%2Forcid.org%2F0000-0001-9827-4429`
+
+```
+{
+ "@id": "https://orcid.org/0000-0001-9827-4429",
+ "@type": "Person",
+ "affiliation": {
+ "@id": "https://ror.org/03v76x132",
+ "@type": "Organization",
+ "name": "Yale University"
+ },
+ "familyName": "Liang",
+ "givenName": "Yu",
+ "name": "Yu Liang"
+}
+```
+
+For `id=https%3A%2F%2Fror.org%2F04t3en479`
+
+```
+{
+ "@id": "https://ror.org/04t3en479",
+ "@type": "Organization",
+ "name": "Karlsruhe Institute of Technology"
+}
+```
diff --git a/docs/guides/web-api/search-api.md b/docs/guides/web-api/search-api.md
new file mode 100644
index 0000000000000000000000000000000000000000..a8cc9ec23fa0d6d78a4848822bcbec0b7b4fca7b
--- /dev/null
+++ b/docs/guides/web-api/search-api.md
@@ -0,0 +1,234 @@
+---
+displayed_sidebar: guidesSidebar
+sidebar_position: 3
+---
+
+# /search
+
+This API provides the user the search results for a given search query.
+
+### Method
+
+GET
+
+### Search Params
+
+`searchText` - term that is being searched for (string)
+
+`start` - row of record to start fetching from (optional; number; defaults to 0)
+
+`rows` - number of rows to be fetched in a call (optional; number; defaults to 10)
+
+`documentType` - the identifier of the category of interest (optional; string; see [/categories](/docs/guides/web-api/categories-api#example) for possible values)
+
+`includeFacet` - flag to indicate whether dynamic filters are required for a given search (optional; boolean)
+
+`facetType` - identifier of the dynamic filter (optional, works with `facetName`; string; see [data model](/docs//about/data-model/index.md#filters) for possible values)
+
+`facetName` - value of the dynamic filter chosen (optional, works with `facetType`; string; this depends on the possible values made available for this filter type)
+
+### URL
+
+[https://search.unhide.helmholtz-metadaten.de/api/search?[searchParams]](https://search.unhide.helmholtz-metadaten.de/api/search?)
+
+### Response Model
+
+```
+{
+ "records": [
+ {
+ "id": string,
+ "type": string,
+ "keys": [ string ],
+ ...
+ "recordConfig": {
+ "index_id": string,
+ "_version_": string,
+ "indexed_ts": timestamp string
+ }
+ },
+ ],
+ "totalCount": number,
+ "categoryCounts": {
+ {categoryid}: count,
+ ...
+ },
+ "filters": [
+ {
+ "filterName": string,
+ "itemName": string,
+ "itemCount": number
+ },
+ ...
+ ]
+}
+```
+
+where,
+
+`records` is a list of records fetched based on the search params. Each record object can have different key-value pairs depending upon the category of the data under interest.
+
+`totalCount` is the total number of records available for the given search
+
+`categoryCounts` presents the total number of records available for the given category and search,
+
+`filters` provides a list of filter objects if the `facetType` and `facetName` are supplied when `includeFacet` is set to true for a given search call.
+
+#### Example
+
+For the following search params:
+
+`searchText` - "Forschungszentrum Jülich"
+
+`documentType` - "documents"
+
+`facetType` - "txt_contributor"
+
+`facetName` - "Angst, Manuel"
+
+`facetType` - "txt_contributor"
+
+`facetName` - "Zorn, Reiner"
+
+`facetType` - "txt_publisher"
+
+`facetName` - "Forschungszentrum Jülich GmbH, JCNS / RWTH Aachen / Univ. Münster"
+
+`facetType` - "txt_keywords"
+
+`facetName` - "info:eu-repo/classification/ddc/600"
+
+```
+{
+ "records": [
+ {
+ "id": "https://juser.fz-juelich.de/record/22096",
+ "type": "DigitalDocument",
+ "txt_contributor": ["Angst, Manuel", "Brückel, Thomas", "Roth, G", "Zorn, Reiner"],
+ "txt_creator": ["Brückel, Thomas"],
+ "txt_identifier": [
+ "https://juser.fz-juelich.de/record/22096",
+ "https://juser.fz-juelich.de/search?p=id:%22PreJuSER-22096%22"
+ ],
+ "txt_keywords": [
+ "info:eu-repo/classification/ddc/530",
+ "info:eu-repo/classification/ddc/600"
+ ],
+ "txt_license": ["info:eu-repo/semantics/openAccess"],
+ "name": "01: Introduction: Neutron Scattering in Contemporary Research",
+ "txt_provider": [
+ "JCNS Neutron Lab Course / Th. Brückel, D. Richter, G. Roth, R. Zorn (Eds.) ; Schriften des Forschungszentrums Jülich / Reihe Schlüsseltechnologien / Key Technologies, Vol. 39, Forschungszentrum Jülich GmbH, 2012; 978-3-89336-789-4<br/>JCNS Neutron Laborator Course, Jülich/München, Germany, 2012-09-03 - 2012-09-14"
+ ],
+ "txt_publisher": ["Forschungszentrum Jülich GmbH, JCNS / RWTH Aachen / Univ. Münster"],
+ "txt_sameAs": ["[info:eu-repo, semantics, altIdentifier, hdl, 2128, 4740]"],
+ "keys": [
+ "id",
+ "type",
+ "txt_contributor",
+ "txt_creator",
+ "txt_identifier",
+ "txt_keywords",
+ "txt_license",
+ "name",
+ "txt_provider",
+ "txt_publisher",
+ "txt_sameAs"
+ ],
+ "recordConfig": {
+ "index_id": "3915592a-f9cd-4932-a048-7aa1019d3a67",
+ "_version_": "1778867342397145088",
+ "indexed_ts": "2023-10-04T22:54:56.738Z"
+ }
+ },
+ {
+ "id": "https://juser.fz-juelich.de/record/19548",
+ "type": "DigitalDocument",
+ "txt_contributor": ["Angst, Manuel", "Brückel, Thomas", "Roth, G", "Zorn, Reiner"],
+ "txt_creator": ["Frielinghaus, Henrich"],
+ "txt_identifier": [
+ "https://juser.fz-juelich.de/record/19548",
+ "https://juser.fz-juelich.de/search?p=id:%22PreJuSER-19548%22"
+ ],
+ "txt_keywords": [
+ "info:eu-repo/classification/ddc/530",
+ "info:eu-repo/classification/ddc/600"
+ ],
+ "txt_license": ["info:eu-repo/semantics/openAccess"],
+ "name": "05: Nanostructures Investigated by Small Angle Neutron Scattering",
+ "txt_provider": [
+ "JCNS Neutron Lab Course / Th. Brückel, D. Richter, G. Roth, R. Zorn (Eds.) ; Schriften des Forschungszentrums Jülich / Reihe Schlüsseltechnologien / Key Technologies, Vol. 39, Forschungszentrum Jülich GmbH, 2012; 978-3-89336-789-4<br/>JCNS Neutron Laborator Course, Jülich/München, Germany, 2012-09-03 - 2012-09-14"
+ ],
+ "txt_publisher": ["Forschungszentrum Jülich GmbH, JCNS / RWTH Aachen / Univ. Münster"],
+ "txt_sameAs": ["[info:eu-repo, semantics, altIdentifier, isbn, 978-3-89336-789-4]"],
+ "keys": [
+ "id",
+ "type",
+ "txt_contributor",
+ "txt_creator",
+ "txt_identifier",
+ "txt_keywords",
+ "txt_license",
+ "name",
+ "txt_provider",
+ "txt_publisher",
+ "txt_sameAs"
+ ],
+ "recordConfig": {
+ "index_id": "4e71f085-59f4-4dc0-8ac5-4f07a2c8af15",
+ "_version_": "1778856255287197696",
+ "indexed_ts": "2023-10-04T19:58:43.246Z"
+ }
+ }
+ ],
+ "totalCount": 2,
+ "categoryCounts": {
+ "experts": 0,
+ "documents": 2,
+ "datasets": 0,
+ "institutions": 0,
+ "trainings": 0,
+ "projects": 0,
+ "software": 0,
+ "instruments": 0
+ },
+ "filters": [
+ {
+ "filterName": "txt_keywords",
+ "itemName": "info:eu-repo/classification/ddc/530",
+ "itemCount": 2
+ },
+ {
+ "filterName": "txt_keywords",
+ "itemName": "info:eu-repo/classification/ddc/600",
+ "itemCount": 2
+ },
+ {
+ "filterName": "txt_contributor",
+ "itemName": "Angst, Manuel",
+ "itemCount": 2
+ },
+ {
+ "filterName": "txt_contributor",
+ "itemName": "Brückel, Thomas",
+ "itemCount": 2
+ },
+ { "filterName": "txt_contributor", "itemName": "Roth, G", "itemCount": 2 },
+ { "filterName": "txt_contributor", "itemName": "Zorn, Reiner", "itemCount": 2 },
+ {
+ "filterName": "txt_license",
+ "itemName": "info:eu-repo/semantics/openAccess",
+ "itemCount": 2
+ },
+ {
+ "filterName": "txt_provider",
+ "itemName": "JCNS Neutron Lab Course / Th. Brückel, D. Richter, G. Roth, R. Zorn (Eds.) ; Schriften des Forschungszentrums Jülich / Reihe Schlüsseltechnologien / Key Technologies, Vol. 39, Forschungszentrum Jülich GmbH, 2012; 978-3-89336-789-4<br/>JCNS Neutron Laborator Course, Jülich/München, Germany, 2012-09-03 - 2012-09-14",
+ "itemCount": 2
+ },
+ {
+ "filterName": "txt_publisher",
+ "itemName": "Forschungszentrum Jülich GmbH, JCNS / RWTH Aachen / Univ. Münster",
+ "itemCount": 2
+ }
+ ]
+}
+```
diff --git a/docs/guides/web-ui/intro.md b/docs/guides/web-ui/intro.md
deleted file mode 100644
index 6ed4c7331bf9229c77f93819651aee1e48c2fd6b..0000000000000000000000000000000000000000
--- a/docs/guides/web-ui/intro.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-displayed_sidebar: guidesSidebar
-sidebar_position: 2
----
-
-## WEB UI guide
diff --git a/docs/guides/web-ui/introduction.md b/docs/guides/web-ui/introduction.md
new file mode 100644
index 0000000000000000000000000000000000000000..d32e9a6c62626098e7878a57098518377e1119c9
--- /dev/null
+++ b/docs/guides/web-ui/introduction.md
@@ -0,0 +1,10 @@
+---
+displayed_sidebar: guidesSidebar
+sidebar_position: 1
+---
+
+# Introduction
+
+The web UI is primarily intended to search the HKG. Thus the most primary features that we provide currently include a search bar, a representation of basic categories for easy access to relevant information and the ability to filter information pertaining a specific category with appropriate filters.
+
+Additionally, we allow users a look at every meta-data records JSON-LD source. We also make it possible for the user to navigate to relevant sources when the source information in the form of hyperlink-able IDs, exist for any given piece of information. There are few more features that will be briefly mentioned in the following sections.
diff --git a/docs/guides/web-ui/primary-features.md b/docs/guides/web-ui/primary-features.md
new file mode 100644
index 0000000000000000000000000000000000000000..a08664fca2720251d7e96c1d6fd65046bdac22f7
--- /dev/null
+++ b/docs/guides/web-ui/primary-features.md
@@ -0,0 +1,35 @@
+---
+displayed_sidebar: guidesSidebar
+sidebar_position: 2
+---
+
+# Primary Features
+
+## Categorized Search
+
+As mentioned in the description of our [data model](/docs/about/data-model/index.md), we combine different types of harvested metadata based on their [schema.org](https://schema.org) type, into 8 categories. This feature allows users to easily search for their records of interest based on how we model our data. Depending upon what category is of interest to the user, the user can directly access records filtered based on their categories via the clickable buttons, that also show the total count of records for the said category, from the landing page.
+
+
+The same categorization is available in the results page as a tab as shown in the image below
+
+
+## Search Bar
+
+The user can also search for records of their interest via the search bar. The search bar also features a random set of queries that the user can try if they like. In the following example, a user is seen searching the HKG for records related to the term "Molecular Dynamics".
+
+
+The results are shown in the results view as a list of records where earch record is displayed within a card. A maximum of 10 records for a search are shown at a time, but the results are paginated so connected results are readily available to the user. The user can also use the category tab above the results to browse through records of that category for the users search query
+
+The search bar is always readily available to user regardless of the view they are in.
+
+## Dynamic Filters
+
+Depending on the category of results shown, the data could also be filtered if there are filters available for the category and the given search term. The different available filters are shown to the left of the list of resulting records.
+
+
+Each set of filters can be further filtered using a searchbar specific to the filter.
+
+
+Filters from a single or multiple set can be simultaneously selected. Please note that, each time a specific filter is chosen, the user would be refining their search and as such the filters could be dynamically updated.
+The selected filters are shown as tags above the results and can be individually or collectively unselected.
+
diff --git a/docs/guides/web-ui/secondary-features.md b/docs/guides/web-ui/secondary-features.md
new file mode 100644
index 0000000000000000000000000000000000000000..8ed3ec035cb8ed50f8fed0e0de634429d3105d34
--- /dev/null
+++ b/docs/guides/web-ui/secondary-features.md
@@ -0,0 +1,18 @@
+---
+displayed_sidebar: guidesSidebar
+sidebar_position: 3
+---
+
+# Other features
+
+## JSON-LD source
+
+For each metadata record shown in the results list, at the bottom of each card, the user can find a link to all information in the record displayed in its JSON-LD object form. This feature allows users to look for details of the record on a more granular level and might help in case a piece of information they are looking for exists as part of the record but is not explicitly shown in the record card of the web view.
+
+## Hyperlinked metadata
+
+In cases where a particular piece of information in a metadata record has a web address and can be navigated to, this piece of information is made clickable - which takes the user to the web page connected to the information.
+
+## Responsive UI
+
+The web UI application is available for usage on mobile, iPad, laptop and desktop views. This makes the application accessible for users in most widely used devices.
diff --git a/index.md b/docs/index.md
similarity index 100%
rename from index.md
rename to docs/index.md
diff --git a/sidebars.ts b/sidebars.ts
index 1d3795a8ab0b7001e271d28dec3f7ff5fbc61010..9d853bdfe40a5ff17ebe46d21a61f00e5b12e554 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -23,7 +23,11 @@ const sidebars: SidebarsConfig = {
type: "generated-index",
},
collapsed: true,
- items: ["guides/web-ui/intro"],
+ items: [
+ "guides/web-ui/introduction",
+ "guides/web-ui/primary-features",
+ "guides/web-ui/secondary-features",
+ ],
},
{
type: "category",
@@ -32,7 +36,13 @@ const sidebars: SidebarsConfig = {
type: "generated-index",
},
collapsed: true,
- items: ["guides/web-api/intro"],
+ items: [
+ "guides/web-api/introduction",
+ "guides/web-api/hello-api",
+ "guides/web-api/categories-api",
+ "guides/web-api/search-api",
+ "guides/web-api/json-ld-source-api",
+ ],
},
{
type: "category",
diff --git a/static/img/unhide-filter-tags.png b/static/img/unhide-filter-tags.png
new file mode 100644
index 0000000000000000000000000000000000000000..43b075db37cdb8b123a18d5c68a156175f6ee0b0
Binary files /dev/null and b/static/img/unhide-filter-tags.png differ
diff --git a/static/img/unhide-filters-filtered.png b/static/img/unhide-filters-filtered.png
new file mode 100644
index 0000000000000000000000000000000000000000..94c10cb3445148b2d96ce0e4f9440a370206decc
Binary files /dev/null and b/static/img/unhide-filters-filtered.png differ
diff --git a/static/img/unhide-landing-categories.png b/static/img/unhide-landing-categories.png
new file mode 100644
index 0000000000000000000000000000000000000000..32b2660c98b278f0e8b1caaecfaf45effa98f50a
Binary files /dev/null and b/static/img/unhide-landing-categories.png differ
diff --git a/static/img/unhide-landing-search.png b/static/img/unhide-landing-search.png
new file mode 100644
index 0000000000000000000000000000000000000000..7bf1a32357028c4b50cd961c75420bdabe8a1b79
Binary files /dev/null and b/static/img/unhide-landing-search.png differ
diff --git a/static/img/unhide-results-categories.png b/static/img/unhide-results-categories.png
new file mode 100644
index 0000000000000000000000000000000000000000..d12ea7edfdd5a67f73cb03745d26c70c3b8885bc
Binary files /dev/null and b/static/img/unhide-results-categories.png differ
diff --git a/static/img/unhide-results-filters.png b/static/img/unhide-results-filters.png
new file mode 100644
index 0000000000000000000000000000000000000000..755b804a6b55dcc88115a6f4ba481f3fba750a6e
Binary files /dev/null and b/static/img/unhide-results-filters.png differ
diff --git a/static/img/unhide-results-search.png b/static/img/unhide-results-search.png
new file mode 100644
index 0000000000000000000000000000000000000000..b690256e9fba59e52b206906690c16b1f3933e31
Binary files /dev/null and b/static/img/unhide-results-search.png differ