From 7a1ae2ca4f937ea3e53a358eca2f0d16cae7303c Mon Sep 17 00:00:00 2001
From: Johannes Nussbaum <39048939+jnussbaum@users.noreply.github.com>
Date: Tue, 16 Apr 2024 10:13:15 +0200
Subject: [PATCH] docs: Add markdownlint check to CI (#3191)
---
.github/workflows/build-and-test.yml | 9 +-
docs/01-introduction/file-formats.md | 4 +-
docs/03-endpoints/api-v2/editing-values.md | 4 +-
docs/03-endpoints/api-v2/text/tei-xml.md | 84 +++++++++----------
.../design/api-admin/administration.md | 2 +-
docs/05-internals/design/api-v2/overview.md | 2 +-
.../design/principles/consistency-checking.md | 12 +--
justfile | 8 ++
8 files changed, 69 insertions(+), 56 deletions(-)
diff --git a/.github/workflows/build-and-test.yml b/.github/workflows/build-and-test.yml
index ee35475fa8..b72eb1e945 100644
--- a/.github/workflows/build-and-test.yml
+++ b/.github/workflows/build-and-test.yml
@@ -139,16 +139,19 @@ jobs:
- name: Checkout source
if: ${{ env.IS_NOOP == 'false' }}
uses: actions/checkout@v3
+ - uses: extractions/setup-just@v2
- name: Install requirements (pip, npm, apt)
if: ${{ env.IS_NOOP == 'false' }}
run: |
- python -m pip install --upgrade pip
- pip install -r docs/requirements.txt
+ just docs-install-requirements
npm install --global typedoc
sudo apt-get install graphviz
+ - name: markdownlint
+ if: ${{ env.IS_NOOP == 'false' }}
+ run: just markdownlint
- name: Build docs
if: ${{ env.IS_NOOP == 'false' }}
- run: make docs-build
+ run: just docs-build
- name: No-op step
if: ${{ env.IS_NOOP == 'true' }}
run: echo "No checks on main or release branches, skipping this job."
diff --git a/docs/01-introduction/file-formats.md b/docs/01-introduction/file-formats.md
index 5b075b1264..d1b159802f 100644
--- a/docs/01-introduction/file-formats.md
+++ b/docs/01-introduction/file-formats.md
@@ -14,7 +14,7 @@ The following table shows the accepted file formats:
| Category | Accepted format | Converted during ingest? |
| --------------------- | -------------------------------------- | -------------------------------------------------------------------------- |
-| Text, XML1 | ODD, RNG, TXT, XML, XSD, XSL | No |
+| Text, XML *) | ODD, RNG, TXT, XML, XSD, XSL | No |
| Tables | CSV, XLS, XLSX | No |
| 2D Images | JPG, JPEG, JP2, PNG, TIF, TIFF | Yes, converted to JPEG 2000 by [Sipi](https://github.com/dasch-swiss/sipi) |
| Audio | MPEG (MP3), WAV | No |
@@ -23,6 +23,6 @@ The following table shows the accepted file formats:
| Archives | ZIP, TAR, GZ, Z, TAR.GZ, TGZ, GZIP, 7Z | No |
-1: If your XML files represent text with markup (e.g. [TEI/XML](http://www.tei-c.org/)),
+*) If your XML files represent text with markup (e.g. [TEI/XML](http://www.tei-c.org/)),
it is possible to store it as [Standoff/RDF](standoff-rdf.md),
as described [here](../03-endpoints/api-v2/text/overview.md).
diff --git a/docs/03-endpoints/api-v2/editing-values.md b/docs/03-endpoints/api-v2/editing-values.md
index 939f0424f0..852efffb27 100644
--- a/docs/03-endpoints/api-v2/editing-values.md
+++ b/docs/03-endpoints/api-v2/editing-values.md
@@ -323,7 +323,7 @@ SIPI.
Still Image may be stored in SIPI or in an external IIIF server.
-**Images stored in SIPI**
+##### Images stored in SIPI
Here is an example of a request to create a resource of class `anything:ThingPicture` with a still image stored in SIPI.
The resource's class is a subclass of `knora-api:StillImageRepresentation` and therefore has the property `knora-api:hasStillImageFileValue`.
@@ -355,7 +355,7 @@ If the client's request to DSP-API is valid, DSP-API saves the file value in the
Otherwise, the temporary file that was stored by SIPI is deleted.
-**Images stored in an external IIIF server**
+##### Images stored in an external IIIF server
In the case of a Still image stored in an external IIIF server, the request is similar to the one above, but the file value is of type `knora-api:StillImageExternalFileValue`
and the `knora-api:externalUrl` property is used to provide the URL of the image in the IIIF server:
diff --git a/docs/03-endpoints/api-v2/text/tei-xml.md b/docs/03-endpoints/api-v2/text/tei-xml.md
index eee08f6531..01a5554beb 100644
--- a/docs/03-endpoints/api-v2/text/tei-xml.md
+++ b/docs/03-endpoints/api-v2/text/tei-xml.md
@@ -193,11 +193,11 @@ PREFIX xsd:
beol:hasFamilyName knora-api:objectType xsd:string .
beol:hasIAFIdentifier knora-api:objectType xsd:string .
- beol:hasAuthor knora-api:objectType knora-api:Resource .
+ beol:hasAuthor knora-api:objectType knora-api:Resource .
?letter beol:hasRecipient ?person2 .
- beol:hasRecipient knora-api:objectType knora-api:Resource .
+ beol:hasRecipient knora-api:objectType knora-api:Resource .
?person1 a knora-api:Resource .
?person2 a knora-api:Resource .
@@ -218,65 +218,65 @@ The Gravsearch query's result may look like this (`RDF/XML`):
```xml
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
+ xmlns:knora-api="http://api.knora.org/ontology/knora-api/v2#"
+ xmlns:beol="http://0.0.0.0:3333/ontology/0801/beol/v2#">
-
-
-
- Testletter
+
+
+
+ Testletter
- GREGORIAN
- 10
- CE
- 6
- 1703
- 10
- CE
- 6
- 1703
- GREGORIAN:1703-06-10 CE
+ GREGORIAN
+ 10
+ CE
+ 6
+ 1703
+ 10
+ CE
+ 6
+ 1703
+ GREGORIAN:1703-06-10 CE
-
-
-
-
-
- Johann Jacob Scheuchzer
-
-
+
+
+
+
+
+ Johann Jacob Scheuchzer
+
+
- Scheuchzer
+ Scheuchzer
- Johann Jacob
+ Johann Jacob
- (DE-588)118607308
+ (DE-588)118607308
-
-
-
-
-
- Jacob Hermann
-
-
+
+
+
+
+
+ Jacob Hermann
+
+
- Hermann
+ Hermann
- Jacob
+ Jacob
- (DE-588)119112450
+ (DE-588)119112450
diff --git a/docs/05-internals/design/api-admin/administration.md b/docs/05-internals/design/api-admin/administration.md
index a707fe08cf..e0036277fc 100644
--- a/docs/05-internals/design/api-admin/administration.md
+++ b/docs/05-internals/design/api-admin/administration.md
@@ -390,7 +390,7 @@ all the necessary information.
The following graphs show the class hierarchy and the structure of each
permission class.
-**Permission Class Hierarchy**
+**Permission Class Hierarchy**:
diff --git a/docs/05-internals/design/api-v2/overview.md b/docs/05-internals/design/api-v2/overview.md
index d8e5836d6d..acd1b54aff 100644
--- a/docs/05-internals/design/api-v2/overview.md
+++ b/docs/05-internals/design/api-v2/overview.md
@@ -155,7 +155,7 @@ not schema-specific (and are not cached). If a data IRI has been
received from a client request, it is better just to validate it using
`StringFormatter.validateAndEscapeIri`.
-#### Implementation
+#### Smart IRI Implementation
The smart IRI implementation, `SmartIriImpl`, is nested in the
`StringFormatter` class, because it uses Knora's
diff --git a/docs/05-internals/design/principles/consistency-checking.md b/docs/05-internals/design/principles/consistency-checking.md
index 19fd5a12ba..d8aca050ef 100644
--- a/docs/05-internals/design/principles/consistency-checking.md
+++ b/docs/05-internals/design/principles/consistency-checking.md
@@ -198,11 +198,13 @@ Consistency: subject_class_constraint
If subject `i` has a predicate `p` that requires an object of type `t`,
and the object of `p` is not a `t`, the constraint is violated:
- Consistency: object_class_constraint
- p t
- i p j
- ------------------------------------
- j t
+```
+Consistency: object_class_constraint
+ p t
+ i p j
+ ------------------------------------
+ j t
+```
### Cardinality constraints
diff --git a/justfile b/justfile
index dc32698baa..a43e6b966a 100644
--- a/justfile
+++ b/justfile
@@ -60,6 +60,7 @@ docs-openapi-generate:
./sbtx "webapi/runMain org.knora.webapi.slice.common.api.DocsGenerator {{ openapiDir }}"
docs-install-requirements:
+ python -m pip install --upgrade pip
pip3 install -r docs/requirements.txt
docs-clean:
@@ -73,3 +74,10 @@ docs-serve: docs-build-dependent
docs-build: docs-build-dependent
mkdocs build --strict
+
+markdownlint:
+ docker run \
+ -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest \
+ --config .markdownlint.yml \
+ --disable MD013 MD040 -- \
+ "docs/**/*.md"