docs: Lint with markdownlint (#3128)

Co-authored-by: Balduin Landolt <[email protected]>

.markdownlint.yml

@@ -0,0 +1,43 @@
+---
+
+# Config file for https://github.com/igorshubovych/markdownlint-cli
+
+# MD007/ul-indent - Unordered list indentation
+MD007: 
+    # Whether to indent the first level of the list
+    start_indented: false
+    # By how many spaces every next level must be indented. The default of 2 is not compatible with mkdocs!
+    indent: 4
+
+# MD009/no-trailing-spaces - Trailing spaces
+MD009: false
+
+# MD012/no-multiple-blanks - Multiple consecutive blank lines
+MD012: false
+
+# MD013/line-length - Line length
+MD013: 
+    line_length: 120
+    heading_line_length: 120
+    code_block_line_length: 120
+    # Include code blocks
+    code_blocks: true
+    # Include tables
+    tables: false
+    # Include headings
+    headings: true
+    headers: true
+    # Strict length checking
+    strict: false
+    # Stern length checking
+    stern: false
+
+# MD033/no-inline-html - Inline HTML
+MD033: 
+    allowed_elements: [br, center]
+
+# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading
+MD041: false
+
+# MD045/no-alt-text - Images should have alternate text (alt text)
+MD045: false

docs/01-introduction/example-project.md

@@ -117,7 +117,8 @@ have the same predicate; a comma (`,`) is used to avoid repeating the
 predicate. The definition of `:title` says:
 
 * `rdf:type owl:ObjectProperty`: It is an `owl:ObjectProperty`. There are
-  two kinds of OWL properties: object properties and datatype properties. Object properties point to objects, which have IRIs and
+  two kinds of OWL properties: object properties and datatype properties. 
+  Object properties point to objects, which have IRIs and
   can have their own properties. Datatype properties point to literal
   values, such as strings and integers.
 * `rdfs:subPropertyOf knora-base:hasValue, dcterms:title`: It is a

docs/01-introduction/standoff-rdf.md

@@ -55,5 +55,6 @@ original XML.
 To represent overlapping or non-hierarchical markup in exported and imported XML, DSP-API supports
 [CLIX](https://web.archive.org/web/20171222112655/http://conferences.idealliance.org/extreme/html/2004/DeRose01/EML2004DeRose01.html) tags.
 
-As XML-to-Standoff has proved to be complicated and not very well performing, the use of standoff with custom mappings is discouraged. 
+As XML-to-Standoff has proved to be complicated and not very well performing, 
+the use of standoff with custom mappings is discouraged. 
 Improved integration of text with XML mark up, particularly TEI-XML, is in planning.

docs/02-dsp-ontologies/knora-base.md

@@ -616,18 +616,19 @@ because it does not allow to perform searches across multiple documents.
 The recommended way to store text with markup in DSP-API is to use the built-in support for "standoff" markup, which
 is stored separately from the text. This has some advantages over embedded markup such as XML. While XML requires markup
 to have a hierarchical structure, and does not allow overlapping tags, standoff nodes do not have these limitations
-(
-see [Using Standoff Properties for Marking-up Historical Documents in the Humanities](https://doi.org/10.1515/itit-2015-0030)).
+(see 
+[Using Standoff Properties for Marking-up Historical Documents in the Humanities](https://doi.org/10.1515/itit-2015-0030)).
 A standoff tag can be attached to any substring in the text by giving its start and end positions. Unlike in corpus
 linguistics, we do not use any tokenisation resulting in a form of predefined segmentation, which would limit the user's
 ability to freely annotate any ranges in the text.
 
 For example, suppose we have the following text:
 
+```xml
 <blockquote>This <i>sentence <strong>has overlapping</strong></i> <strong>visual</strong> attributes.</blockquote>
+```
 
-This would require just two standoff tags: `(italic, start=5, end=29)`
-and `(bold, start=14, end=36)`.
+This would require just two standoff tags: `(italic, start=5, end=29)` and `(bold, start=14, end=36)`.
 
 Moreover, standoff makes it possible to mark up the same text in different, possibly incompatible ways, allowing for
 different interpretations without making redundant copies of the text. In the Knora base ontology, any text value can
@@ -1011,17 +1012,17 @@ only if the value's class has some cardinality for that property.
 
 Knora supports, and attempts to enforce, the following cardinality constraints:
 
-* `owl:cardinality 1`
-  : _Exactly One `1`_ - A resource of this class must have exactly one instance of the specified property.
+- `owl:cardinality 1`:
+  _Exactly One `1`_ - A resource of this class must have exactly one instance of the specified property.
 
-* `owl:minCardinality 1`
-  : _At Least One `1-n`_ - A resource of this class must have at least one instance of the specified property.
+- `owl:minCardinality 1`:
+  _At Least One `1-n`_ - A resource of this class must have at least one instance of the specified property.
 
-* `owl:maxCardinality 1`
-  : _Zero Or One `0-1`_ - A resource of this class must have either zero or one instance of the specified property.
+- `owl:maxCardinality 1`:
+  _Zero Or One `0-1`_ - A resource of this class must have either zero or one instance of the specified property.
 
-* `owl:minCardinality 0`
-  : _Unbounded `0-n`_ - A resource of this class may have zero or more instances of the specified property.
+- `owl:minCardinality 0`:
+  _Unbounded `0-n`_ - A resource of this class may have zero or more instances of the specified property.
 
 Knora requires cardinalities to be defined using blank nodes, as in the following example from `knora-base`:
 

docs/03-endpoints/api-admin/groups.md

@@ -94,7 +94,7 @@ specified by the `id` in the request body as below:
 }
 ```
 
-### Change Group Status:
+### Change Group Status
 
 - Required permission: SystemAdmin / hasProjectAllAdminPermission
 - Changeable information: `status`
@@ -108,7 +108,7 @@ specified by the `id` in the request body as below:
 }
 ```
 
-### Delete Group:
+### Delete Group
 
 - Required permission: SystemAdmin / hasProjectAllAdminPermission
 - Remark: The same as changing the groups `status` to

docs/03-endpoints/api-admin/index.md

@@ -1,6 +1,6 @@
+We provide an [OpenAPI](https://spec.openapis.org/oas/latest.html) specification. 
+The latest version is located at [api.dasch.swiss/api/docs/docs.yaml](https://api.dasch.swiss/api/docs/docs.yaml).
+For an interactive documentation of all API endpoints, 
+please visit [api.dasch.swiss/api/docs/](https://api.dasch.swiss/api/docs/).
 
-We provide an [OpenAPI](https://spec.openapis.org/oas/latest.html) specification. The latest version is located at [api.dasch.swiss/api/docs/docs.yaml](https://api.dasch.swiss/api/docs/docs.yaml).
-For an interactive documentation of all API endpoints, please visit [api.dasch.swiss/api/docs/](https://api.dasch.swiss/api/docs/).
-
-
-[OAD(./docs/03-endpoints/generated-openapi/openapi-admin-api.yml)]
+[OAD](../generated-openapi/openapi-admin-api.yml)

docs/03-endpoints/api-admin/introduction.md

@@ -21,7 +21,9 @@ values (see
 ## Knora IRIs in the Admin API
 
 Every resource that is created or hosted by Knora is identified by a
-unique ID called an Internationalized Resource Identifier ([IRI](https://tools.ietf.org/html/rfc3987)). The IRI is required for every API operation to identify the resource in question. A Knora IRI has itself the format of a URL.
+unique ID called an Internationalized Resource Identifier ([IRI](https://tools.ietf.org/html/rfc3987)). 
+The IRI is required for every API operation to identify the resource in question. 
+A Knora IRI has itself the format of a URL. 
 For some API operations, the IRI has to be URL-encoded (HTTP GET requests).
 
 Unlike the DSP-API v2, the admin API uses internal IRIs, i.e. the actual IRIs