Feature/linter adjustments

.editorconfig

@@ -16,8 +16,9 @@ trim_trailing_whitespace = true
 indent_style = space
 indent_size = 2
 
-# 4 space indentation
-[*.md]
+# Matches multiple files with brace expansion notation
+# Set default charset
+[*.{md}]
 indent_style = space
 indent_size = 4
 

.github/workflows/test.yml

@@ -64,6 +64,12 @@ jobs:
       - name: check
         run: task check
 
+      - name: Publish Test Results
+        if: always()
+        uses: EnricoMi/publish-unit-test-result-action@v2
+        with:
+          files: "dist/md-lint-issues.xml"
+
       - name: build
         run: task clean build
 

.gitignore

@@ -8,4 +8,4 @@ tmp
 .DS_Store
 .vscode/
 .python-version
-
+dist/

.markdownlint.jsonc

@@ -1,34 +1,35 @@
 {
-  // Example markdownlint JSON(C) configuration with all properties set to their default value
-
-  // Default state for all rules
   "default": true,
-
-  // not enforcing line break a specific lenght
+  "MD012": false,
   "MD013": false,
-
   "MD007": {
     "indent": 4
   },
-
-  // allow Multiple headings with the same content
   "MD024": false,
-
-  // to be consistent with prettier
+  "MD025": false,
   "MD030": {
-    "ul_single": 3,
-    "ul_multi": 3
+    "ul_single": 1,
+    "ul_multi": 1
   },
-
-  // allow some html
   "MD033": {
-    "allowed_elements": ["figure", "figcaption", "div"]
+    "allowed_elements": [
+      "a",
+      "br",
+      "cite",
+      "details",
+      "div",
+      "figcaption",
+      "figure",
+      "img",
+      "p",
+      "span",
+      "summary"
+    ]
   },
-
-  // allow missing img alt text
+  "MD035": false,
+  "MD041": false,
   "MD045": false,
-
-  // disabled due to admonition / tabs using indented blocks
-  "MD046": false
-  //"MD046": { "style": "fenced" }
+  "MD046": false,
+  "MD059": false,
+  "MD060": false
 }

.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+
+---
+repos:
+  - repo: local
+    hooks:
+
+      - id: markdownlint
+        name: check:rumdl
+        entry: task check:rumdl
+        language: python
+        pass_filenames: false

CONTRIBUTING.md

@@ -31,9 +31,9 @@ We suggest to use a specialized markdown editor such as [obsidian](https://obsid
 
 The following tools you need locally to get started:
 
--   [poetry](https://python-poetry.org/)
--   [task](https://taskfile.dev/)
--   git, markdown editor
+- [poetry](https://python-poetry.org/)
+- [task](https://taskfile.dev/)
+- git, markdown editor
 
 On a few OS distributions (e.g. Arch Linux) the tool/binary is named `go-task`.
 
@@ -71,26 +71,26 @@ Have a look at the [mkdocs-material documentation](https://squidfunk.github.io/m
 <details>
   <summary>Extend section</summary>
 
--   always create a directory + `index.md`, e.g. `my-topic/index.md` ([Example](https://github.com/eccenca/documentation.eccenca.com/tree/main/docs/automate/cmemc-command-line-interface))
--   add new pages to the `.pages` file to add them in the right order and with correct title to the menu ([Example](https://github.com/eccenca/documentation.eccenca.com/blob/main/docs/automate/cmemc-command-line-interface/.pages))
--   put images side by side to the `index.md` ([Example](https://github.com/eccenca/documentation.eccenca.com/tree/main/docs/release-notes/corporate-memory-22-1))
--   do not use images for icons esp. icons from the application
-    -   use eccenca icons, e.g. [:eccenca-application-queries:](https://github.com/eccenca/documentation.eccenca.com/blob/main/overrides/.icons/eccenca/application-queries.svg) -> [list](https://github.com/eccenca/documentation.eccenca.com/tree/main/overrides/.icons/eccenca)
-    -   use theme icons where no eccenca icon is available -> [list](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search)
--   name image files properly (not just `Screenshot.xxx.png`, [Example](https://github.com/eccenca/documentation.eccenca.com/tree/main/docs/release-notes/corporate-memory-22-1))
--   used advanced features where suitable
-    -   [Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage) (esp. use notes and warnings where needed) -> see Admonition section for more details
-    -   [Code Blocks](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#usage) (e.g. enable highlightning and add a title)
-    -   [Content Tabs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#usage) (to structure complex pages)
--   code blocks:
-    -   do not use line numbers except you refer to it in the text
-    -   use correct syntax highlightning (often used: `shell-session`, `bash`, `sparql`, `turtle`, `json`) -> [list of syntax IDs](https://pygments.org/docs/lexers/)
-    -   do not confuse `shell-session` with `bash` (the first is a terminal output, the latter a script syntax)
-    -   when using `shell-session`, use `$` as the prompt
--   Links:
-    -   do not use absolute links for internal documents, e.g. `https://documentation.eccenca.com/latest/...`
-    -   do not use base-relative links, e.g. `/automate/...`
-    -   use relative links to `index.md` files
+- always create a directory + `index.md`, e.g. `my-topic/index.md` ([Example](https://github.com/eccenca/documentation.eccenca.com/tree/main/docs/automate/cmemc-command-line-interface))
+- add new pages to the `.pages` file to add them in the right order and with correct title to the menu ([Example](https://github.com/eccenca/documentation.eccenca.com/blob/main/docs/automate/cmemc-command-line-interface/.pages))
+- put images side by side to the `index.md` ([Example](https://github.com/eccenca/documentation.eccenca.com/tree/main/docs/release-notes/corporate-memory-22-1))
+- do not use images for icons esp. icons from the application
+    - use eccenca icons, e.g. [:eccenca-application-queries:](https://github.com/eccenca/documentation.eccenca.com/blob/main/overrides/.icons/eccenca/application-queries.svg) -> [list](https://github.com/eccenca/documentation.eccenca.com/tree/main/overrides/.icons/eccenca)
+    - use theme icons where no eccenca icon is available -> [list](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search)
+- name image files properly (not just `Screenshot.xxx.png`, [Example](https://github.com/eccenca/documentation.eccenca.com/tree/main/docs/release-notes/corporate-memory-22-1))
+- used advanced features where suitable
+    - [Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage) (esp. use notes and warnings where needed) -> see Admonition section for more details
+    - [Code Blocks](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#usage) (e.g. enable highlightning and add a title)
+    - [Content Tabs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#usage) (to structure complex pages)
+- code blocks:
+    - do not use line numbers except you refer to it in the text
+    - use correct syntax highlightning (often used: `shell-session`, `bash`, `sparql`, `turtle`, `json`) -> [list of syntax IDs](https://pygments.org/docs/lexers/)
+    - do not confuse `shell-session` with `bash` (the first is a terminal output, the latter a script syntax)
+    - when using `shell-session`, use `$` as the prompt
+- Links:
+    - do not use absolute links for internal documents, e.g. `https://documentation.eccenca.com/latest/...`
+    - do not use base-relative links, e.g. `/automate/...`
+    - use relative links to `index.md` files
 
 </details>
 
@@ -104,13 +104,13 @@ On this page is search function for icons available as well.
 <details>
   <summary>Extend section</summary>
 
-|Admonition Name|Used For |Example|
-|---------------|---------|-------|
-|Info |Information in documentation provides details about a topic or process that the reader needs to know. It is usually essential and relevant to the main subject of the document.|Statement annotations provide a way to express knowledge about statements. This group is dedicated to properties that configure the Statement Annotation feature|
-|Note |A note provides additional details that may or may not be directly related to the main topic. It could be an explanation, clarification, or an aside that the writer thinks would be helpful for the reader to know.|The graph selection drop-down might or might not be visible depending the existence of an (optional) EasyNav Module configuration. In case no specific module configuration exists or non has not has been set for the current workspace the graph selection will be shown. A EasyNav Module configuration pre-configures a graph. Thus, the dropdown will not be shown if such has been configured for the current workspace.|
-|Abstract|An abstract is a brief summary that provides an overview of the main points or contents of a document. It typically appears at the beginning of a document and is intended to give the reader an idea of what to expect from the document.|This tutorial explores the benefits of using cloud computing in enterprise organizations. It discusses the advantages of cloud computing over traditional on-premises infrastructure, and provides guidance for migrating to the cloud.|
-|Warning|It is used to convey the seriousness of the risk and the importance of taking necessary precautions to avoid harm.|If the remote file resource is used in more than one dataset, the other datasets are also affected by this command.|
-|Tip|A tip is a type of admonition in documentation that provides a helpful suggestion or best practice related to the content of the document. It is typically used to guide the reader towards a more efficient or effective way of using a product or service, or to provide additional insights or recommendations.|We have the suggestion option as well; click on the +icon and select the suggestion mapping.|
+| Admonition Name | Used For | Example |
+| ----  ----------- | -------- | ------- |
+| Info | Information in documentation provides details about a topic or process that the reader needs to know. It is usually essential and relevant to the main subject of the document. | Statement annotations provide a way to express knowledge about statements. This group is dedicated to properties that configure the Statement Annotation feature |
+| Note | A note provides additional details that may or may not be directly related to the main topic. It could be an explanation, clarification, or an aside that the writer thinks would be helpful for the reader to know. | The graph selection drop-down might or might not be visible depending the existence of an (optional) EasyNav Module configuration. In case no specific module configuration exists or non has not has been set for the current workspace the graph selection will be shown. A EasyNav Module configuration pre-configures a graph. Thus, the dropdown will not be shown if such has been configured for the current workspace. |
+| Abstract | An abstract is a brief summary that provides an overview of the main points or contents of a document. It typically appears at the beginning of a document and is intended to give the reader an idea of what to expect from the document. | This tutorial explores the benefits of using cloud computing in enterprise organizations. It discusses the advantages of cloud computing over traditional on-premises infrastructure, and provides guidance for migrating to the cloud. |
+| Warning | It is used to convey the seriousness of the risk and the importance of taking necessary precautions to avoid harm. | If the remote file resource is used in more than one dataset, the other datasets are also affected by this command. |
+| Tip | A tip is a type of admonition in documentation that provides a helpful suggestion or best practice related to the content of the document. It is typically used to guide the reader towards a more efficient or effective way of using a product or service, or to provide additional insights or recommendations. | We have the suggestion option as well; click on the +icon and select the suggestion mapping. |
 |Success|Success admonitions are a type of documentation element used to highlight successful outcomes or positive results associated with a particular task, process, or feature|Graph is created successfully.|
 |Bug|A bug admonition include a description of the bug or issue, as well as steps that the user can take to avoid or work around the problem. It may also include information about when the bug will be fixed or patched, if applicable.|Users may experience issues with the file saving feature when running this software on Windows 10. To avoid data loss or corruption, be sure to save your work frequently and consider using an external backup device. Our development team is working to resolve this issue in the next software update.|
 |Example|The example admonition is typically used in instructional or educational documents to clarify complex concepts or demonstrate how to perform a specific task.|To create a new email account, click on the "Sign Up" button on the homepage and enter your name, email address, and desired password. Be sure to choose a strong password with a mix of uppercase and lowercase letters, numbers, and special characters. Once you have entered your information, click "Create Account" to complete the process.|
@@ -123,27 +123,27 @@ On this page is search function for icons available as well.
 <details>
   <summary>Extend section</summary>
 
--   do not use a cluttered desktop
--   do not show other esp. personal project artifacts than relevant for the tutorial / feature to show
--   select cropping area carefully (omit backgrounds, lines on the edges, etc.)
--   use the same or a similar area for similar screens
--   all relevant elements should be clearly visible and not be truncated
--   irrelevant elements / details should be omitted completely and not be half visible
--   crop scrollbars (they can make edges look unclean, especially if a scrollbar is directly on an edge)
--   keep an equal distance of all visible elements to the edges of the screenshot
+- do not use a cluttered desktop
+- do not show other esp. personal project artifacts then relevant for the tutorial / feature to show
+- select cropping area carefully (omit backgrounds, lines on the edges, etc.)
+- use the same or a similar area for similar screens
+- all relevant elements should be clearly visible and not be truncated
+- irrelevant elements / details should be omitted completely and not be half visible
+- crop scrollbars (they can make edges look unclean, especially if a scrollbar is directly on an edge)
+- keep an equal distance of all visible elements to the edges of the screenshot
 
 </details>
 
 ## Generated Content
 
 <details>
   <summary>The following files are generated from other sources and should not be changed:</summary>
-    
--   cmemc Command Reference: [docs/automate/cmemc-command-line-interface/command-reference](https://github.com/eccenca/documentation.eccenca.com/tree/main/docs/automate/cmemc-command-line-interface/command-reference)
+
+- cmemc Command Reference: [docs/automate/cmemc-command-line-interface/command-reference](https://github.com/eccenca/documentation.eccenca.com/tree/main/docs/automate/cmemc-command-line-interface/command-reference)
     - to update, start `task update:cmemc`
--   Coporate Memory Application Icons: [overrides/.icons/eccenca](https://github.com/eccenca/documentation.eccenca.com/tree/main/overrides/.icons/eccenca)
+- Coporate Memory Application Icons: [overrides/.icons/eccenca](https://github.com/eccenca/documentation.eccenca.com/tree/main/overrides/.icons/eccenca)
     - to update, start `task update:icons`
--   Shapes and Datatypes: [docs/explore-and-author/graph-exploration/building-a-customized-user-interface/node-shapes|property-shapes|datatype-reference](https://github.com/eccenca/documentation.eccenca.com/tree/main/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/node-shapes)
+- Shapes and Datatypes: [docs/explore-and-author/graph-exploration/building-a-customized-user-interface/node-shapes|property-shapes|datatype-reference](https://github.com/eccenca/documentation.eccenca.com/tree/main/docs/explore-and-author/graph-exploration/building-a-customized-user-interface/node-shapes)
     - to update, start `task update:shape-reference`
 
 Where applicable, we added the following disclaimer: `<!-- This file was generated - DO NOT CHANGE IT MANUALLY -->`

README.md

@@ -4,10 +4,10 @@
 
 Shared repository of the eccenca Corporate Memory documentation.
 
-| Branch       | Deployment |
-| :---         | :--- |
-| `main`       | [https://dev.documentation.eccenca.com](https://dev.documentation.eccenca.com) |
-| `published`  | [https://documentation.eccenca.com](https://documentation.eccenca.com) |
+| Branch | Deployment |
+| :----- | :--------- |
+| `main` | [https://dev.documentation.eccenca.com](https://dev.documentation.eccenca.com) |
+| `published` | [https://documentation.eccenca.com](https://documentation.eccenca.com) |
 
 If you consider to contribute to this project, please have a look on [CONTRIBUTING.md](https://github.com/eccenca/documentation.eccenca.com/blob/main/CONTRIBUTING.md)
 
@@ -27,4 +27,3 @@ This work is licensed under a [Creative Commons Attribution-ShareAlike 4.0 Inter
 [mkdocs-shield]: https://img.shields.io/badge/Made%20with-mkdocs-brightgreen
 [mkdocs]: https://www.mkdocs.org/
 [markdown-shield]: https://img.shields.io/badge/Made%20with-Markdown-1f425f.svg
-

Taskfile.yml

@@ -51,6 +51,7 @@ tasks:
     desc: Run complete test suite
     deps:
       - check:links
+      - check:rumdl
 
   check:links:
     desc: Check outgoing links
@@ -180,3 +181,36 @@ tasks:
     cmds:
       - poetry run mike serve -b {{.PUBLIC_BRANCH}}
 
+  format:fix:
+    desc: rumdl (md-lint) and apply possible style fixes
+    cmds:
+      - |
+        {
+          # recurse
+          find ./docs -type f -name '*.md' -print0
+
+          # no recursion (top-level only)
+          find . -maxdepth 1 -type f -name '*.md' -print0
+        } | xargs -0 poetry run rumdl --config .markdownlint.jsonc check --fix
+
+  check:rumdl:
+    desc: run rumdl (md-linter) for style issues
+    cmds:
+      - mkdir -p ./dist
+      - rm -f ./dist/md-lint-issues.xml
+      - |
+        {
+          # recurse
+          find ./docs -type f -name '*.md' -print0
+
+          # no recursion (top-level only)
+          find . -maxdepth 1 -type f -name '*.md' -print0
+        } | xargs -0 poetry run rumdl --config .markdownlint.jsonc check --output-format junit > ./dist/md-lint-issues.xml || true
+      - |
+        {
+          # recurse
+          find ./docs -type f -name '*.md' -print0
+
+          # no recursion (top-level only)
+          find . -maxdepth 1 -type f -name '*.md' -print0
+        } | xargs -0 poetry run rumdl --config .markdownlint.jsonc check