diff --git a/docs/_static/voc4cat-pylode-docs.webp b/docs/_static/voc4cat-pylode-docs.webp
new file mode 100644
index 00000000..47e89398
Binary files /dev/null and b/docs/_static/voc4cat-pylode-docs.webp differ
diff --git a/docs/_static/xlsx-icon-on-concept-sheet.webp b/docs/_static/xlsx-icon-on-concept-sheet.webp
new file mode 100644
index 00000000..d6933222
Binary files /dev/null and b/docs/_static/xlsx-icon-on-concept-sheet.webp differ
diff --git a/docs/conf.py b/docs/conf.py
index c04bf706..9149547c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -88,5 +88,5 @@
},
],
# HTML to be show in a announcement banner at the top of the page
- "announcement": "🛠️ Work-in-progress! This will soon replace the GitHub project page as the main access point to Voc4Cat. 🛠️",
+ "announcement": "🛠️ Work-in-progress! This site will soon replace the GitHub project page as the main access point to Voc4Cat. 🛠️",
}
diff --git a/docs/index.md b/docs/index.md
index 157b0b25..38a8df4d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -11,42 +11,77 @@ which reflects the community's shared understanding of the concept's meaning.
By using the identifiers provided by Voc4Cat to annotate data, rather than just words and symbols, ambiguity as to what is meant is avoided.
Producing Voc4Cat-annotated data contributes to realising the vision of machine-actionability described as the ultimate goal of the [FAIR principles](https://doi.org/10.1038/sdata.2016.18).
-Voc4Cat conforms to the [SKOS](https://www.w3.org/TR/skos-reference/) standard.
+Voc4Cat conforms to the [SKOS](https://www.w3.org/TR/skos-reference/) standard.
The vocabulary is available in rdf/turtle or rdf/xml format to facilitate integration with other tools and services.
Voc4Cat is also available in xlsx (Excel) format, making it easy for researchers to submit additions and updates.
-## Vocabulary Files & Documentation
+::::{grid} 3
+:::{grid-item-card} Documentation (HTML)
+:link: https://w3id.org/nfdi4cat/voc4cat/dev
-```{todo} Add links to rdf and xlsx vocabulary files and to the pylode html-documentation generated from SKOS.
+```{image} _static/voc4cat-pylode-docs.webp
+:height: 180
+:align: center
+:alt: screenshot of pylode generated vocabulary documentation
```
-::::{grid} 2
-:::{grid-item-card} Title Card 1
-Header 1
-^^^
-Card 1 content
+++
-Footer 1
+Development preview
:::
-:::{grid-item-card} Title Card 2
-Header 2
-^^^
-Card 2 content
+:::{grid-item-card} Spreadsheet file (xlsx)
+:link: https://nfdi4cat.github.io/voc4cat/dev/voc4cat.xlsx
+
+```{image} _static/xlsx-icon-on-concept-sheet.webp
+:height: 180
+:align: center
+:alt: xlsx file icon
+```
+++
-Footer 2
+Most current
:::
-::::
-:::{card} Clickable Card (external)
-:link: https://example.com
+:::{grid-item-card} Documentation (HTML)
+:link: https://w3id.org/nfdi4cat/voc4cat
-The entire card can be clicked to navigate to .
+```{image} _static/voc4cat-pylode-docs.webp
+:height: 180
+:align: center
+:alt: screenshot of pylode generated vocabulary documentation
+```
++++
+Latest release
:::
+::::
+
+By default the HTML documentation is served from the URLs below.
+Corresponding RDF-files (turtle or xml) can be requested from the same URLs using content negotiation.
+
+| Version | Permanent URL |
+| ----------------------------- | ------------------------------------------- |
+| Most current (in development) | ```https://w3id.org/nfdi4cat/voc4cat/dev``` |
+| Latest release | ```https://w3id.org/nfdi4cat/voc4cat``` |
+
+```{tip}
+:class: dropdown
+:class: open
+**`voc4cat`** is the preferred and [registered](https://bioregistry.io/registry/voc4cat) **prefix** for the Voc4Cat vocabulary.
+
+With the prefix, long URIs can be shortened to **compact URI**s (also called *CURIES*). These short notations are typically preferred in linked-data applications.
+
+For example, the compact URI of `https://w3id.org/nfdi4cat/voc4cat_0005001` is `voc4cat:0005001`.
+```
+
+## Older releases
+
+- **v2024-04-08**: [Documentation (HTML)](https://w3id.org/nfdi4cat/voc4cat/v2024-04-08), permanent url `https://w3id.org/nfdi4cat/voc4cat/v2024-04-08`
+- **v2023-09-03**: [Documentation (HTML)](https://w3id.org/nfdi4cat/voc4cat/v2023-09-03"), permanent url `https://w3id.org/nfdi4cat/voc4cat/v2023-09-03`
+- **v2023-08-17**: [Documentation (HTML)](https://w3id.org/nfdi4cat/voc4cat/v2023-08-17), permanent url `https://w3id.org/nfdi4cat/voc4cat/v2023-08-17`
```{toctree}
:hidden:
-SKOS files & docs
+Overview
+GitHub page
About
```
diff --git a/docs/usage/about.md b/docs/usage/about.md
index 88c473bd..5b3dd4ac 100644
--- a/docs/usage/about.md
+++ b/docs/usage/about.md
@@ -1,4 +1,4 @@
-# About Voc4cat
+# About Voc4Cat
Voc4Cat is an example for applying *open data, open code, and open infrastructure (O3)* to create community-curated scientific resources that can outlast funding.
For more information on the *O3* idea, see [C. Hoyt and B. Gyori, 2024](https://doi.org/10.1038/s41597-024-03406-w).
diff --git a/docs/usage/how-to-contribute.md b/docs/usage/how-to-contribute.md
index eb918206..27334576 100644
--- a/docs/usage/how-to-contribute.md
+++ b/docs/usage/how-to-contribute.md
@@ -1,4 +1,6 @@
# How to contribute to Voc4Cat?
-```{todo} Move and merge documentation on contribution process from readme and guidelines-V2 here.
+```{todo}
+Move and merge documentation on contribution process from [readme](https://github.com/nfdi4cat/voc4cat/blob/main/README.md)
+and {ref}`guidelines-v2.0 ` here.
```
diff --git a/docs/usage/how-to-use.md b/docs/usage/how-to-use.md
index 72d560e3..2a547160 100644
--- a/docs/usage/how-to-use.md
+++ b/docs/usage/how-to-use.md
@@ -1,5 +1,14 @@
# How to use Voc4Cat?
-```{todo} Section has to written.
-Possible Topics: use in data systems like nomad, use in linkml datamodels, correct use of skos in owl onotlogies, etc.
+```{todo} Possible topics:
+* Using content negotiation to download RDF versions
+* Use of voc4cat in RDM tools/portals
+ * dataverse (repo4cat)
+ * nomad of FAIRMAT
+ * LabImotion(?) of NFDI4Chem / Daphne
+* Use in linkml datamodels
+* Tips for using SKOS concepts in OWL ontologies
+* Short guide (jupyter notebook): using voc4cat/SKOS from Python with rdflib
+
+What other topics would you like to read about here? Let us know by [creating an issue](https://github.com/nfdi4cat/voc4cat/issues/new?assignees=&labels=voc4cat+guidelines&projects=&template=improvement_guidelines.yaml&title=%F0%9F%93%9D+%3Ctitle%3E)!
```