docs: Add markdownlint check to CI (#3191)

dasch-swiss · Apr 16, 2024 · 7a1ae2c · 7a1ae2c
1 parent d4c8c02
commit 7a1ae2c
Show file tree

Hide file tree

Showing 8 changed files with 69 additions and 56 deletions.
diff --git 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
@@ -14,7 +14,7 @@ The following table shows the accepted file formats:
 
 | Category              | Accepted format                        | Converted during ingest?                                                   |
 | --------------------- | -------------------------------------- | -------------------------------------------------------------------------- |
-| Text, XML<sup>1</sup> | 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
@@ -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
@@ -193,11 +193,11 @@ PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
         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
 <?xml version="1.0" encoding="UTF-8"?>
 <rdf:RDF
-	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#">
+    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#">
 <beol:letter rdf:about="http://rdfh.ch/0801/MbZdHVcsR_Ky5pZoytaiBA">
-	<beol:creationDate rdf:resource="http://rdfh.ch/0801/MbZdHVcsR_Ky5pZoytaiBA/values/Ob_1YRO_QmaDxTRI64vGOQ"/>
-	<beol:hasAuthorValue rdf:resource="http://rdfh.ch/0801/MbZdHVcsR_Ky5pZoytaiBA/values/zt4a3XoESTq9To4mSN8Dug"/>
-	<beol:hasRecipientValue rdf:resource="http://rdfh.ch/0801/MbZdHVcsR_Ky5pZoytaiBA/values/pVerHO_FRXePZQT9kgEp_Q"/>
-	<rdfs:label rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Testletter</rdfs:label>
+    <beol:creationDate rdf:resource="http://rdfh.ch/0801/MbZdHVcsR_Ky5pZoytaiBA/values/Ob_1YRO_QmaDxTRI64vGOQ"/>
+    <beol:hasAuthorValue rdf:resource="http://rdfh.ch/0801/MbZdHVcsR_Ky5pZoytaiBA/values/zt4a3XoESTq9To4mSN8Dug"/>
+    <beol:hasRecipientValue rdf:resource="http://rdfh.ch/0801/MbZdHVcsR_Ky5pZoytaiBA/values/pVerHO_FRXePZQT9kgEp_Q"/>
+    <rdfs:label rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Testletter</rdfs:label>
 </beol:letter>
 <knora-api:DateValue rdf:about="http://rdfh.ch/0801/MbZdHVcsR_Ky5pZoytaiBA/values/Ob_1YRO_QmaDxTRI64vGOQ">
-	<knora-api:dateValueHasCalendar rdf:datatype="http://www.w3.org/2001/XMLSchema#string">GREGORIAN</knora-api:dateValueHasCalendar>
-	<knora-api:dateValueHasEndDay rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">10</knora-api:dateValueHasEndDay>
-	<knora-api:dateValueHasEndEra rdf:datatype="http://www.w3.org/2001/XMLSchema#string">CE</knora-api:dateValueHasEndEra>
-	<knora-api:dateValueHasEndMonth rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">6</knora-api:dateValueHasEndMonth>
-	<knora-api:dateValueHasEndYear rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">1703</knora-api:dateValueHasEndYear>
-	<knora-api:dateValueHasStartDay rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">10</knora-api:dateValueHasStartDay>
-	<knora-api:dateValueHasStartEra rdf:datatype="http://www.w3.org/2001/XMLSchema#string">CE</knora-api:dateValueHasStartEra>
-	<knora-api:dateValueHasStartMonth rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">6</knora-api:dateValueHasStartMonth>
-	<knora-api:dateValueHasStartYear rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">1703</knora-api:dateValueHasStartYear>
-	<knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">GREGORIAN:1703-06-10 CE</knora-api:valueAsString>
+    <knora-api:dateValueHasCalendar rdf:datatype="http://www.w3.org/2001/XMLSchema#string">GREGORIAN</knora-api:dateValueHasCalendar>
+    <knora-api:dateValueHasEndDay rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">10</knora-api:dateValueHasEndDay>
+    <knora-api:dateValueHasEndEra rdf:datatype="http://www.w3.org/2001/XMLSchema#string">CE</knora-api:dateValueHasEndEra>
+    <knora-api:dateValueHasEndMonth rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">6</knora-api:dateValueHasEndMonth>
+    <knora-api:dateValueHasEndYear rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">1703</knora-api:dateValueHasEndYear>
+    <knora-api:dateValueHasStartDay rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">10</knora-api:dateValueHasStartDay>
+    <knora-api:dateValueHasStartEra rdf:datatype="http://www.w3.org/2001/XMLSchema#string">CE</knora-api:dateValueHasStartEra>
+    <knora-api:dateValueHasStartMonth rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">6</knora-api:dateValueHasStartMonth>
+    <knora-api:dateValueHasStartYear rdf:datatype="http://www.w3.org/2001/XMLSchema#integer">1703</knora-api:dateValueHasStartYear>
+    <knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">GREGORIAN:1703-06-10 CE</knora-api:valueAsString>
 </knora-api:DateValue>
 <knora-api:LinkValue rdf:about="http://rdfh.ch/0801/MbZdHVcsR_Ky5pZoytaiBA/values/zt4a3XoESTq9To4mSN8Dug">
-	<knora-api:linkValueHasTarget>
-		<beol:person rdf:about="http://rdfh.ch/0801/_9LEnLM7TFuPRjTshOTJpQ">
-			<beol:hasFamilyName rdf:resource="http://rdfh.ch/0801/_9LEnLM7TFuPRjTshOTJpQ/values/NG42jDqSTz2U35N6sJ8cqg"/>
-			<beol:hasGivenName rdf:resource="http://rdfh.ch/0801/_9LEnLM7TFuPRjTshOTJpQ/values/W2lVG1mvQU2MauAvCGB13w"/>
-			<beol:hasIAFIdentifier rdf:resource="http://rdfh.ch/0801/_9LEnLM7TFuPRjTshOTJpQ/values/N2TVtntdToqJQpdZhYPc5g"/>
-			<rdfs:label rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Johann Jacob Scheuchzer</rdfs:label>
-		</beol:person>
-	</knora-api:linkValueHasTarget>
+    <knora-api:linkValueHasTarget>
+        <beol:person rdf:about="http://rdfh.ch/0801/_9LEnLM7TFuPRjTshOTJpQ">
+            <beol:hasFamilyName rdf:resource="http://rdfh.ch/0801/_9LEnLM7TFuPRjTshOTJpQ/values/NG42jDqSTz2U35N6sJ8cqg"/>
+            <beol:hasGivenName rdf:resource="http://rdfh.ch/0801/_9LEnLM7TFuPRjTshOTJpQ/values/W2lVG1mvQU2MauAvCGB13w"/>
+            <beol:hasIAFIdentifier rdf:resource="http://rdfh.ch/0801/_9LEnLM7TFuPRjTshOTJpQ/values/N2TVtntdToqJQpdZhYPc5g"/>
+            <rdfs:label rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Johann Jacob Scheuchzer</rdfs:label>
+        </beol:person>
+    </knora-api:linkValueHasTarget>
 </knora-api:LinkValue>
 <knora-api:TextValue rdf:about="http://rdfh.ch/0801/_9LEnLM7TFuPRjTshOTJpQ/values/NG42jDqSTz2U35N6sJ8cqg">
-	<knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Scheuchzer</knora-api:valueAsString>
+    <knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Scheuchzer</knora-api:valueAsString>
 </knora-api:TextValue>
 <knora-api:TextValue rdf:about="http://rdfh.ch/0801/_9LEnLM7TFuPRjTshOTJpQ/values/W2lVG1mvQU2MauAvCGB13w">
-	<knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Johann Jacob</knora-api:valueAsString>
+    <knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Johann Jacob</knora-api:valueAsString>
 </knora-api:TextValue>
 <knora-api:TextValue rdf:about="http://rdfh.ch/0801/_9LEnLM7TFuPRjTshOTJpQ/values/N2TVtntdToqJQpdZhYPc5g">
-	<knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">(DE-588)118607308</knora-api:valueAsString>
+    <knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">(DE-588)118607308</knora-api:valueAsString>
 </knora-api:TextValue>
 <knora-api:LinkValue rdf:about="http://rdfh.ch/0801/MbZdHVcsR_Ky5pZoytaiBA/values/pVerHO_FRXePZQT9kgEp_Q">
-	<knora-api:linkValueHasTarget>
-		<beol:person rdf:about="http://rdfh.ch/0801/JaQwPsYEQJ6GQrAgKC0Gkw">
-			<beol:hasFamilyName rdf:resource="http://rdfh.ch/0801/JaQwPsYEQJ6GQrAgKC0Gkw/values/k1Exqf93SsWi7LWK9ozXkw"/>
-			<beol:hasGivenName rdf:resource="http://rdfh.ch/0801/JaQwPsYEQJ6GQrAgKC0Gkw/values/gkqK5Ij_R7mtO59xfSDGJA"/>
-			<beol:hasIAFIdentifier rdf:resource="http://rdfh.ch/0801/JaQwPsYEQJ6GQrAgKC0Gkw/values/C-Dl15S-SV63L1KCCPFfew"/>
-			<rdfs:label rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Jacob Hermann</rdfs:label>
-		</beol:person>
-	</knora-api:linkValueHasTarget>
+    <knora-api:linkValueHasTarget>
+        <beol:person rdf:about="http://rdfh.ch/0801/JaQwPsYEQJ6GQrAgKC0Gkw">
+            <beol:hasFamilyName rdf:resource="http://rdfh.ch/0801/JaQwPsYEQJ6GQrAgKC0Gkw/values/k1Exqf93SsWi7LWK9ozXkw"/>
+            <beol:hasGivenName rdf:resource="http://rdfh.ch/0801/JaQwPsYEQJ6GQrAgKC0Gkw/values/gkqK5Ij_R7mtO59xfSDGJA"/>
+            <beol:hasIAFIdentifier rdf:resource="http://rdfh.ch/0801/JaQwPsYEQJ6GQrAgKC0Gkw/values/C-Dl15S-SV63L1KCCPFfew"/>
+            <rdfs:label rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Jacob Hermann</rdfs:label>
+        </beol:person>
+    </knora-api:linkValueHasTarget>
 </knora-api:LinkValue>
 <knora-api:TextValue rdf:about="http://rdfh.ch/0801/JaQwPsYEQJ6GQrAgKC0Gkw/values/k1Exqf93SsWi7LWK9ozXkw">
-	<knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Hermann</knora-api:valueAsString>
+    <knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Hermann</knora-api:valueAsString>
 </knora-api:TextValue>
 <knora-api:TextValue rdf:about="http://rdfh.ch/0801/JaQwPsYEQJ6GQrAgKC0Gkw/values/gkqK5Ij_R7mtO59xfSDGJA">
-	<knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Jacob</knora-api:valueAsString>
+    <knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Jacob</knora-api:valueAsString>
 </knora-api:TextValue>
 <knora-api:TextValue rdf:about="http://rdfh.ch/0801/JaQwPsYEQJ6GQrAgKC0Gkw/values/C-Dl15S-SV63L1KCCPFfew">
-	<knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">(DE-588)119112450</knora-api:valueAsString>
+    <knora-api:valueAsString rdf:datatype="http://www.w3.org/2001/XMLSchema#string">(DE-588)119112450</knora-api:valueAsString>
 </knora-api:TextValue>
 
 </rdf:RDF>

diff --git 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**:
 
 ![Figure 1](administration-fig4.dot.png "Figure 4")
 

diff --git 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
@@ -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 <knora-base:objectClassConstraint> t
-        i p j
-        ------------------------------------
-        j <rdf:type> t
+```
+Consistency: object_class_constraint
+    p <knora-base:objectClassConstraint> t
+    i p j
+    ------------------------------------
+    j <rdf:type> t
+```
 
 ### Cardinality constraints
 

diff --git 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"