Add separate & improved how-to-contribute page

CONTRIBUTING.md

@@ -4,9 +4,9 @@ Thank you for your interest in contributing to the Voc4Cat vocabulary! This SKOS
 
 ## Quick Start
 
-1. **Download** the current vocabulary Excel file: [voc4cat.xlsx](https://nfdi4cat.github.io/voc4cat/dev/voc4cat.xlsx)
-2. **Edit** the Excel file to add/modify concepts
-3. **Request a range of IDs** (for new concepts): [Create an issue](https://github.com/nfdi4cat/voc4cat/issues/new/choose)
+1. **Request a range of IDs** (for new concepts): [Create an issue](https://github.com/nfdi4cat/voc4cat/issues/new/choose)
+2. **Download** the current vocabulary Excel file: [voc4cat.xlsx](https://nfdi4cat.github.io/voc4cat/dev/voc4cat.xlsx)
+3. **Edit** the Excel file to add/modify concepts
 4. **Submit** your Excel file in a pull request:
    - Create a new branch for the changes in your fork and switch to it
    - Place file in `inbox-excel-vocabs/` folder

README.md

@@ -69,10 +69,10 @@ you can use this link to the [SKOS testing tool](http://skos-play.sparna.fr/skos
 
 The latest release of voc4cat is available via
 
-* [SKOSMOS](https://semanticlookup.zbmed.de/skosmos/voc4cat/en/) operated by [ZBmed](https://www.zbmed.de/en/). The SKOSMOS API is used for the integration of Voc4Cat into the NFDI4Cat data repository **[repo4cat](https://repository.nfdi4cat.org/)**.
+* [Skosmos](https://semanticlookup.zbmed.de/skosmos/voc4cat/en/) operated by [ZB MED](https://www.zbmed.de/en/). The Skosmos API is used for the integration of Voc4Cat into the NFDI4Cat data repository **[repo4cat](https://repository.nfdi4cat.org/)**.
 * [TIB Terminology Service](https://terminology.tib.eu/ts/ontologies/voc4cat) which is based on a customized OLS version.
 
-Both services offer API access to voc4cat. SKOSMOS has more SKOS-specific features than OLS and is therefore recommended.
+Both services offer API access to voc4cat. Skosmos has more SKOS-specific features than OLS and is therefore recommended.
 
 ## Contributing to vocabularies
 
@@ -155,7 +155,7 @@ This work was funded by the German Research Foundation (DFG) through the project
 
 Special thanks to:
 
-- Roman Baum (@rombaum) who helped us to make voc4cat accessible via SKOSMOS in a [TS4NFDI incubator project](https://terminology.services.base4nfdi.de/incubators), see also [doi:10.5281/zenodo.16736361](https://doi.org/10.5281/zenodo.16736361).
-- [ZBmed](https://www.zbmed.de/en/) for operating the SKOSMOS instance that provides a modern [user interface](https://semanticlookup.zbmed.de/skosmos/voc4cat/en/) for browsing Voc4Cat plus REST API access.
+- [Roman Baum](https://github.com/rombaum) and his team who helped us to make voc4cat accessible via Skosmos in a [TS4NFDI incubator project](https://terminology.services.base4nfdi.de/incubators), see also [doi:10.5281/zenodo.16736361](https://doi.org/10.5281/zenodo.16736361).
+- [ZB MED](https://www.zbmed.de/en/) for operating the Skosmos instance that provides a modern [user interface](https://semanticlookup.zbmed.de/skosmos/voc4cat/en/) for browsing Voc4Cat plus REST API access.
 - [TIB - Leibniz Information Centre for Science and Technology](https://www.tib.eu/en/) for providing API access to Voc4Cat.
 - [W3ID Consortium](https://w3id.org) for making its permanent URL service available to the community.

docs/conf.py

@@ -20,8 +20,8 @@
     # External extensions
     "myst_parser",
     "sphinx_copybutton",
-    "sphinx_inline_tabs",
-    "sphinx_design",
+    "sphinx_design",  # design extensions like tabs/cards
+    "sphinxcontrib.mermaid",  # diagrams via MyST directive {mermaid}
 ]
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md']
@@ -50,10 +50,13 @@
 
 myst_enable_extensions = [
     "attrs_inline", # enable {}-attribute syntax like ![](img/fish.png){w=100px align=center}
-    "colon_fence",  # enable the colon_fence ::: syntax for admonitions
+    "colon_fence",  # required for ::: tab-set / tab-item and admonitions syntax
     "html_image",   # convert HTML <img> elements to sphinx image nodes
 ]
 
+# generate slug anchors for headings (levels 1..3) so fragment links resolve
+myst_heading_anchors = 3
+
 # -- Options for Furo theme ---------------------------------------------------
 # https://pradyunsg.me/furo/customisation/
 
@@ -90,7 +93,7 @@
     ],
     # HTML to be show in a announcement banner at the top of the page
     "announcement":
-        '<em>News: Voc4Cat is available via <a class="reference external" href="https://semanticlookup.zbmed.de/skosmos/voc4cat/en/">SKOSMOS</a>'
-        ' at ZBmed thanks to a <a class="reference external" href="https://terminology.services.base4nfdi.de/incubators">TS4NFDI incubator</a> project.'
+        '<em>News: Voc4Cat is available via <a class="reference external" href="https://semanticlookup.zbmed.de/skosmos/voc4cat/en/">Skosmos</a>'
+        ' at ZB MED thanks to a <a class="reference external" href="https://terminology.services.base4nfdi.de/incubators">TS4NFDI incubator</a> project.'
         ' (2025-11-09) </em>',
 }

docs/docs_maintenance/creating-docs-locally.md

@@ -1,21 +1,25 @@
 # Building the docs locally
 
-You need a recent Python version on your computer and a local clone of the repository.
+You need on your computer:
+- A recent Python version,
+- The [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) and
+- A local clone of the repository.
 
 The following commands should be run from the root directory of the clone.
 
-First, install the required packages into a virtual environment. The documentation is built with Sphinx and MyST for markdown support.
+First, install the required packages into a virtual environment.
 
 ```bat
-py -m venv .venv
-.venv\Scripts\activate
-pip install -r docs\requirements.txt
+uv venv
+.venv/Scripts/activate
+uv pip install -r docs\requirements.txt
 ```
 
-Build the documentation (option `-a` tells sphinx to rebuild all files, `--nitpicky` warns on missing references):
+Then build the documentation with Sphinx and MyST for markdown support
+(`-a` tells sphinx to rebuild all files, `--nitpicky` warns on missing references). 
 
-```bat
+```bash
 sphinx-build -a --nitpicky docs docs/_build
 ```
 
-The documentation is created in `docs/_build` and can be previewed by opening the file `docs\_build\html\index.html` in a web browser.
+The documentation is created in `docs/_build` and can be previewed by opening the file `docs/_build/html/index.html` in your web browser.

docs/docs_maintenance/making-releases.md

@@ -1,11 +1,12 @@
-# Making Releases on GitHub
+# Making Releases
 
 ```{note} This guide is only relevant for maintainers with commit rights.
 ```
 
 ## Overview
 
-Releases in the voc4cat repository publish versioned snapshots of the vocabulary and documentation to permanent URLs following the pattern `https://w3id.org/nfdi4cat/voc4cat/vYYYY-MM-DD`. The release process is automated via GitHub Actions, triggered by pushing a tag with the version pattern.
+Releases in the voc4cat repository publish versioned snapshots of the vocabulary and documentation to permanent URLs following the pattern `https://w3id.org/nfdi4cat/voc4cat/vYYYY-MM-DD`.
+The release process is automated via GitHub Actions, triggered by pushing a tag with the version pattern.
 
 The voc4cat version tags reflect the date when a release is created.
 Tags must follow the pattern `vYYYY-MM-DD`: