rempairamore · Oct 19, 2026 · Oct 15, 2026 · Oct 15, 2026 · Oct 16, 2026 · Oct 16, 2026
diff --git a/.dockerignore b/.dockerignore
@@ -24,9 +24,7 @@ htmlcov/
 .idea/
 
 # Docs site build artifacts
-docs/node_modules/
-docs/.astro/
-docs/dist/
+site/
 
 # Runtime spool cache
 **/spool/

diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -5,11 +5,11 @@ on:
     branches: [main]
     paths:
       - 'docs/**'
+      - 'mkdocs.yml'
   workflow_run:
     workflows: ["Run tests"]
     types: [completed]
     branches: [main]
-  workflow_dispatch:
 
 permissions:
   contents: read
@@ -21,7 +21,8 @@ jobs:
     runs-on: ubuntu-latest
     if: >
       github.event_name != 'workflow_run' ||
-      github.event.workflow_run.conclusion == 'success'
+      (github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.event == 'push')
     steps:
       - uses: actions/checkout@v4
 
@@ -30,7 +31,7 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           name: coverage-report
-          path: docs/public/coverage
+          path: docs/coverage
           github-token: ${{ secrets.GITHUB_TOKEN }}
           run-id: ${{ github.event.workflow_run.id }}
 
@@ -39,13 +40,21 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           name: coverage-badge
-          path: docs/public/coverage
+          path: docs/coverage
           github-token: ${{ secrets.GITHUB_TOKEN }}
           run-id: ${{ github.event.workflow_run.id }}
 
-      - uses: withastro/action@v5
+      - uses: actions/setup-python@v5
         with:
-          path: ./docs
+          python-version: "3.13"
+
+      - run: pip install mkdocs-material "mkdocs<2"
+
+      - run: mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
 
   deploy:
     needs: build

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -11,6 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     if: >
       github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
       contains(github.event.workflow_run.head_commit.message, '[release]')
     permissions:
       contents: write
@@ -54,4 +55,4 @@ jobs:
           UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
         run: |
           uv build
-          uv publish --token $UV_PUBLISH_TOKEN
+          uv publish --check-url https://pypi.org/simple/ --token $UV_PUBLISH_TOKEN
diff --git a/.gitignore b/.gitignore
@@ -19,9 +19,11 @@ htmlcov/
 .idea/
 
 # Starlight/Astro
-docs/node_modules/
-docs/.astro/
-docs/dist/
+site/
 
 # saved files
 spool/
+
+# claude
+CLAUDE.md
+.claude/
diff --git a/Dockerfile b/Dockerfile
@@ -29,7 +29,7 @@ USER appuser
 
 # Install dependencies first for better layer caching (frozen = exact lockfile)
 COPY --chown=appuser:appuser pyproject.toml uv.lock README.md ./
-RUN uv sync --frozen --no-dev --no-install-project
+RUN uv sync --frozen --no-dev --no-install-project --extra server
 
 # Application code
 COPY --chown=appuser:appuser . .

diff --git a/LICENSE.md b/LICENSE.md
@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) 2025 Valentina Pasqual, Sivio Peroni
+Copyright (c) 2025 Valentina Pasqual, Silvio Peroni
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

diff --git a/README.md b/README.md
@@ -4,25 +4,31 @@
 [![Coverage](https://opencitations.github.io/lode/coverage/coverage-badge.svg)](https://opencitations.github.io/lode/coverage/)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
-LODE 2.0 is an open source service that automatically extracts entities from semantic artefacts (OWL, RDF/RDFS, SKOS) and renders them, together with their textual definitions, as a human-readable HTML page designed for browsing and navigation through embedded links. This new reengineered version of LODE is maintained by OpenCitations. 
+Live Owl Documentation Enviroment (LODE) is an open source service that automatically extracts entities from semantic artefacts (OWL, RDF/RDFS, SKOS) and renders them, together with their textual definitions, as a human-readable HTML page designed for browsing and navigation through embedded links. This new reengineered version of LODE is maintained by OpenCitations. 
+
+**Try it online:** a hosted instance of the web service is available at https://lode.opencitations.net/, with no installation needed.
+
 
 ## Installation
 
 ```bash
-pip install lode
+pip install oc-lode
+
+# with the web service (`lode serve`)
+pip install "oc-lode[server]"
 ```
 
-## Usage
+ ## Usage
 
-```python
-from lode import example_function
+```bash
+# Build static documentation from an ontology URL or a local file
+lode build --url <url> --read-as <owl|rdf|skos> [--out ./docs] [--lang en] [--artefact-name index] [--imported] [--closure]
+lode build --file <path> --read-as <owl|rdf|skos> [--out ./docs]
 
-result = example_function()
-print(result)
+# Run the web service locally (requires the [server] extra)
+lode serve --port 8000
 ```
 
-
-
 ## Documentation
 
 Full documentation is available at: https://opencitations.github.io/lode/
@@ -74,14 +80,47 @@ Replace `latest` with the desired version tag.
 
 The app will be available at `localhost:8080`.
 
-
-<!-- ### Running tests
+## Running tests
 
 ```bash
 uv run pytest tests/
 ```
 
-### Building documentation locally
+## How to cite
+
+If you use LODE, please cite both the paper and the software:
+
+Pasqual, V., Nazari, A., Peroni, S. (2026). Supporting the understanding of ontologies for scientific knowledge graphs with the new version of LODE. In *Proceedings of the 6th International Workshop on Scientific Knowledge: Representation, Discovery, and Assessment (Sci-K 2026), co-located with the 25th International Semantic Web Conference (ISWC) 2026, Bari, Italy*, CEUR Workshop Proceedings, Vol. 4291, pp. 12–26. https://ceur-ws.org/Vol-4291/paper1.pdf
+
+```bibtex
+@inproceedings{pasqual2026lode,
+  author    = {Pasqual, Valentina and Nazari, Ahmadreza and Peroni, Silvio},
+  title     = {Supporting the Understanding of Ontologies for Scientific Knowledge Graphs with the New Version of LODE},
+  booktitle = {Proceedings of the 6th International Workshop on Scientific Knowledge: Representation, Discovery, and Assessment (Sci-K 2026), co-located with the 25th International Semantic Web Conference (ISWC) 2026, Bari, Italy},
+  series    = {CEUR Workshop Proceedings},
+  volume    = {4291},
+  pages     = {12--26},
+  publisher = {CEUR-WS.org},
+  issn      = {1613-0073},
+  year      = {2026},
+  url       = {https://ceur-ws.org/Vol-4291/paper1.pdf}
+}
+```
+
+To cite the software (all versions), use this BibTeX entry:
+
+```bibtex
+@software{lode,
+  author    = {Pasqual, Valentina and Peroni, Silvio and Nazari, Ahmadreza},
+  title     = {LODE - Live OWL Documentation Environment},
+  year      = {2026},
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.21805185},
+  url       = {https://github.com/opencitations/lode}
+}
+```
+
+<!-- ### Building documentation locally
 
 ```bash
 cd docs
@@ -91,4 +130,4 @@ npm run dev
 
 ## License
 
-This project is licensed under the ISC License - see the [LICENSE.md](LICENSE.md) file for details.
+This project is licensed under the ISC License - see the [LICENSE.md](https://github.com/opencitations/lode/blob/main/LICENSE.md) file for details.
diff --git a/docs/.gitignore b/docs/.gitignore
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/src/content/docs/api/endpoints.md → docs/api/endpoints.md b/docs/src/content/docs/api/endpoints.md → docs/api/endpoints.md
@@ -1,7 +1,7 @@
----
-title: API Endpoints
-description: LODE REST API reference
----
+# API endpoints
+
+The API is part of the web service and needs the `[server]` extra
+(`pip install "oc-lode[server]"`, see [Getting started](../getting_started.md#which-install-do-i-need)).
 
 Interactive docs available at `/docs` (Swagger) and `/redoc` (ReDoc) when the server is running.
 
@@ -19,7 +19,7 @@ Render an artefact as HTML or RDF.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `read_as` | enum | yes | `owl` \| `rdf` \| `skos` |
+| `read_as` | enum | yes | `owl` \| `rdf` \| `skos` - Currently only `owl` is available|
 | `url` | string | one of | Public http(s) URL |
 | `upload_id` | string | one of | Token from a previous upload |
 | `resource` | string | no | IRI of a single resource |

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs