ci(markdownlint): add markdownlint code formatting checks (#655)

Also adds basic `.markdownlint.yaml` configuration since
this is the primary way how to align markdown lint styles.

Author: Michael Buchar

.github/workflows/ci.yml

@@ -143,6 +143,20 @@ jobs:
           pip install yamllint
           ./run-tests.sh --check-yamllint
 
+  lint-markdownlint:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+
+      - name: Lint Markdown files
+        run: |
+          npm install markdownlint-cli2 --global
+          ./run-tests.sh --check-markdownlint
+
   docs-sphinx:
     runs-on: ubuntu-24.04
     steps:

.markdownlint.yaml

@@ -0,0 +1,4 @@
+# Allow prompt dollar sign in console examples without showing output
+MD014: false
+# Allow multiple headings with same content (but for different versions)
+MD024: false

CHANGELOG.md

@@ -1,11 +1,12 @@
 # Contributing
 
-Bug reports, issues, feature requests, and other contributions are welcome. If you find
-a demonstrable problem that is caused by the REANA code, please:
+Bug reports, issues, feature requests, and other contributions are welcome. If
+you find a demonstrable problem that is caused by the REANA code, please:
 
-1. Search for [already reported problems](https://github.com/reanahub/reana-workflow-controller/issues).
-2. Check if the issue has been fixed or is still reproducible on the
-   latest `master` branch.
+1. Search for
+   [already reported problems](https://github.com/reanahub/reana-workflow-controller/issues).
+2. Check if the issue has been fixed or is still reproducible on the latest
+   `master` branch.
 3. Create an issue, ideally with **a test case**.
 
 If you create a pull request fixing a bug or implementing a feature, you can run

CONTRIBUTING.md

@@ -9,9 +9,9 @@
 
 ## About
 
-REANA-Workflow-Controller is a component of the [REANA](http://www.reana.io/) reusable
-and reproducible research data analysis platform. It takes care of instantiating and
-managing computational workflows.
+REANA-Workflow-Controller is a component of the [REANA](http://www.reana.io/)
+reusable and reproducible research data analysis platform. It takes care of
+instantiating and managing computational workflows.
 
 ## Features
 

README.md

@@ -1,3 +1,5 @@
+# REANA Workflow Controller
+
 ```{include} ../README.md
 :end-before: "## About"
 ```
@@ -10,7 +12,8 @@
 ## REST API
 
 The REANA-Workflow-Controller component offers a REST API for managing
-workflows. Detailed REST API documentation can be found <a href="_static/api.html">here</a>.
+workflows. Detailed REST API documentation can be found
+[in openapi.json under the docs directory](https://github.com/reanahub/reana-workflow-controller/blob/master/docs/openapi.json).
 
 ```{eval-rst}
 .. automodule:: reana_workflow_controller.rest.workflows

docs/index.md

@@ -119,6 +119,10 @@ check_yamllint() {
     yamllint .
 }
 
+check_markdownlint() {
+    markdownlint-cli2 "**/*.md"
+}
+
 check_pytest() {
     clean_old_db_container
     start_db_container
@@ -149,6 +153,7 @@ check_all() {
     check_docker_build
     check_shfmt
     check_yamllint
+    check_markdownlint
 }
 
 if [ $# -eq 0 ]; then
@@ -171,5 +176,6 @@ case $arg in
 --check-docker-build) check_docker_build ;;
 --check-shfmt) check_shfmt ;;
 --check-yamllint) check_yamllint ;;
+--check-markdownlint) check_markdownlint ;;
 *) echo "[ERROR] Invalid argument '$arg'. Exiting." && exit 1 ;;
 esac