CI: use pymarkdownlnt

.devcontainer/devcontainer.json

@@ -35,7 +35,6 @@
         "ms-vscode.test-adapter-converter",
         "njpwerner.autodocstring",
         "cschlosser.doxdocgen",
-        "davidanson.vscode-markdownlint",
         // version pinned (for now) since an old version (1.6.2) is installed otherwise
         "biomejs.biome@3.3.0"
       ],

.github/workflows/check-code-quality.yml

@@ -52,14 +52,15 @@ jobs:
         run: |
           uv run --frozen gersemi -i --warnings-as-errors src/ tests/ cmake/
 
-      - name: Install npm packages
+      - name: Run pymarkdown
         run: |
-          npm ci
+          echo "Running pymarkdown"
+          git ls-files -z -- '*.md' | xargs -0 -r uv run --frozen pymarkdown --strict-config fix
+          git ls-files -z -- '*.md' | xargs -0 -r uv run --frozen pymarkdown --strict-config scan
 
-      - name: Run markdownlint
+      - name: Install npm packages
         run: |
-          echo "Running markdownlint"
-          npx markdownlint --fix .
+          npm ci
 
       - name: Run Biome
         run: |

.github/workflows/refresh-lock-and-linter-dependencies.yml

@@ -41,7 +41,7 @@ jobs:
         uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
 
       - name: upgrade uv lock
-        run: uv lock --upgrade  
+        run: uv lock --upgrade
 
       - name: Install linters from uv
         run: |
@@ -78,7 +78,6 @@ jobs:
             echo "${nospecialchars_pkg}=$version" >> "$GITHUB_OUTPUT"
           }
           grab_installed_version_npm "@biomejs/biome"
-          grab_installed_version_npm "markdownlint-cli"
 
       - name: Update .pre-commit-config.yaml
         uses: cuchi/jinja2-action@8bd801365a8d36a0b20f45ee969161685de7785a # v1.3.0
@@ -91,7 +90,6 @@ jobs:
             mypy=${{ steps.versions_uv.outputs.mypy }}
             gersemi=${{ steps.versions_uv.outputs.gersemi }}
             biome=${{ steps.versions_npm.outputs.biomejsbiome }}
-            markdownlint_cli=${{ steps.versions_npm.outputs.markdownlint-cli }}
 
       - name: show changed files
         run: |

.pre-commit-config.yaml

@@ -47,11 +47,22 @@ repos:
         language: system
         pass_filenames: true
         types: [ cmake ]
-  - repo: https://github.com/igorshubovych/markdownlint-cli  # outside pypi 
-    rev: v0.49.1
-    hooks:
-      - id: markdownlint
-        args: ["--fix"]
+      - id: pymarkdown-fix
+        name: pymarkdown-fix
+        alias: markdown-fix
+        entry: uv run --frozen pymarkdown --strict-config fix
+        language: system
+        pass_filenames: true
+        types: [ markdown ]
+        require_serial: true
+      - id: pymarkdown-scan
+        name: pymarkdown-scan
+        alias: markdown-check
+        entry: uv run --frozen pymarkdown --strict-config scan
+        language: system
+        pass_filenames: true
+        types: [ markdown ]
+        require_serial: true
   # format .json and .jsonc files
   - repo: https://github.com/biomejs/pre-commit  # outside pypi 
     rev: v2.5.6

.pre-commit-config.yaml.jinja

@@ -47,11 +47,23 @@ repos:
         language: system
         pass_filenames: true
         types: [ cmake ]
-  - repo: https://github.com/igorshubovych/markdownlint-cli  # outside pypi 
-    rev: v{{ markdownlint_cli }}
-    hooks:
-      - id: markdownlint
-        args: ["--fix"]
+      - id: pymarkdown-fix
+        name: pymarkdown-fix
+        alias: markdown-fix
+        entry: uv run --frozen pymarkdown --strict-config fix
+        language: system
+        pass_filenames: true
+        types: [ markdown ]
+        require_serial: true
+      - id: pymarkdown-scan
+        name: pymarkdown-scan
+        alias: markdown-check
+        entry: uv run --frozen pymarkdown --strict-config scan
+        language: system
+        pass_filenames: true
+        types: [ markdown ]
+        require_serial: true
+        # format .json and .jsonc files
   # format .json and .jsonc files
   - repo: https://github.com/biomejs/pre-commit  # outside pypi 
     rev: v{{ biome }}

.pymarkdown

@@ -0,0 +1,37 @@
+{
+  "plugins": {
+    "heading-increment": {
+      "enabled": false
+    },
+    "no-duplicate-heading": {
+      "enabled": false
+    },
+    "line-length": {
+      "enabled": true,
+      "tables": false,
+      "line_length": 120,
+      "heading_line_length": 120,
+      "code_block_line_length": 120
+    }
+  },
+  "extensions": {
+    "front-matter": {
+      "enabled": true
+    },
+    "linter-pragmas": {
+      "enabled": true
+    },
+    "markdown-tables": {
+      "enabled": true
+    },
+    "markdown-task-list-items": {
+      "enabled": false
+    },
+    "markdown-strikethrough": {
+      "enabled": false
+    },
+    "markdown-disallow-raw-html": {
+      "enabled": false
+    }
+  }
+}

.pymarkdown.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+
+SPDX-License-Identifier: MPL-2.0

.vscode/tasks.json

@@ -54,7 +54,7 @@
     {
       "label": "markdownlint",
       "type": "shell",
-      "command": "npx markdownlint --fix .",
+      "command": "pymarkdown fix .",
       "group": {
         "kind": "build",
         "isDefault": false

README.md

@@ -4,7 +4,8 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridm
 SPDX-License-Identifier: MPL-2.0
 -->
 
-[![Power Grid Model logo](https://raw.githubusercontent.com/PowerGridModel/.github/main/artwork/svg/color.svg)](#) <!-- markdownlint-disable-line first-line-h1 line-length no-empty-links -->
+<!-- pyml disable-next-line first-line-heading,no-empty-links-->
+[![Power Grid Model logo](https://raw.githubusercontent.com/PowerGridModel/.github/main/artwork/svg/color.svg)](#)
 
 [![PyPI version](https://badge.fury.io/py/power-grid-model.svg?no-cache)](https://badge.fury.io/py/power-grid-model)
 [![PyPI Downloads](https://static.pepy.tech/badge/power-grid-model)](https://pepy.tech/project/power-grid-model)
@@ -110,6 +111,7 @@ references.
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8054429.svg)](https://zenodo.org/record/8054429)
 
+<!-- pyml disable line-length -->
 ```bibtex
 @software{Xiang_PowerGridModel_power-grid-model,
   author = {Xiang, Yu and Salemink, Peter and van Westering, Werner and Bharambe, Nitish and Govers, Martinus G.H. and van den Bogaard, Jonas and Stoeller, Bram and Wang, Zhen and Guo, Jerry Jinfeng and Figueroa Manrique, Santiago and Jagutis, Laurynas and Wang, Chenguang and van Raalte, Marc and {Contributors to the LF Energy project Power Grid Model}},
@@ -130,6 +132,7 @@ references.
   doi={10.1049/icp.2023.0633}
 }
 ```
+<!-- pyml enable line-length -->
 
 ## Contact
 

docs/advanced_documentation/build-guide.md

@@ -104,15 +104,13 @@ are automatically downloaded and used during the build — you do not need to in
 Manual installation is only required for standalone CMake builds.
 ```
 
-<!-- pyml disable line-length-->
 | Library name                                                        | Requirements to build Python package | Requirements to build CMake project         | Remark      | License                                                                                                      |
 | ------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
 | [boost](https://www.boost.org/)                                     | Installed automatically              | CMake needs to be able find `boost`         | header-only | [Boost Software License - Version 1.0](https://www.boost.org/LICENSE_1_0.txt)                                |
 | [eigen3](https://eigen.tuxfamily.org/)                              | Installed automatically              | CMake needs to be able find `eigen3`        | header-only | [Mozilla Public License, version 2.0](https://www.mozilla.org/en-US/MPL/2.0/)                                |
 | [nlohmann-json](https://github.com/nlohmann/json)                   | Installed automatically              | CMake needs to be able find `nlohmann_json` | header-only | [MIT](https://github.com/nlohmann/json/blob/develop/LICENSE.MIT)                                             |
 | [msgpack-cxx](https://github.com/msgpack/msgpack-c/tree/cpp_master) | Installed automatically              | CMake needs to be able find `msgpack-cxx`   | header-only | [Boost Software License - Version 1.0](https://github.com/msgpack/msgpack-c/blob/cpp_master/LICENSE_1_0.txt) |
 | [doctest](https://github.com/doctest/doctest)                       | None                                 | CMake needs to be able find `doctest`       | header-only | [MIT](https://github.com/doctest/doctest/blob/master/LICENSE.txt)                                            |
-<!-- pyml enable line-length-->
 
 To install the C++ dependencies for a CMake build, use your platform's package manager of choice.
 In the platform-specific examples below, we will give some suggestions.
@@ -126,7 +124,6 @@ Set `CMAKE_PREFIX_PATH` to the installation prefix of your package manager so CM
 
 The table below shows the Python dependencies.
 
-<!-- pyml disable line-length-->
 | Library name                                                           | Remark                 | License                                                                                    |
 |------------------------------------------------------------------------|------------------------|--------------------------------------------------------------------------------------------|
 | [numpy](https://numpy.org/)                                            | Runtime dependency     | [BSD-3](https://github.com/numpy/numpy/blob/main/LICENSE.txt)                              |
@@ -135,7 +132,6 @@ The table below shows the Python dependencies.
 | [pytest-cov](https://github.com/pytest-dev/pytest-cov)                 | Development dependency | [MIT](https://github.com/pytest-dev/pytest-cov/blob/master/LICENSE)                        |
 | [msgpack-python](https://github.com/msgpack/msgpack-python)            | Development dependency | [Apache License, Version 2.0](https://github.com/msgpack/msgpack-python/blob/main/COPYING) |
 | [uv](https://github.com/astral-sh/uv)                                  | Development dependency | [Apache License, Version 2.0](https://github.com/astral-sh/uv/blob/main/LICENSE-APACHE)    |
-<!-- pyml enable line-length-->
 
 ## Build Python Package
 

docs/advanced_documentation/high-level-design.md

@@ -46,6 +46,7 @@ wrapper layer core module, that wraps the exposition-only core module, that expo
 
 This can be visualized graphically as follows.
 
+<!-- pyml disable line-length -->
 ```{mermaid}
     :title: Full design
 
@@ -93,6 +94,7 @@ flowchart TD
     cpp_user -->|experimental<br>links +<br>includes| power_grid_model_cpp -->|links +<br>includes| power_grid_model_c
     python_user -->|import| power_grid_model_python -->|internal import| power_grid_model_core_python -->|internal import| power_grid_core_python -->|"CDLL<br>(dynamic loading)"| power_grid_model_c_dll
 ```
+<!-- pyml enable line-length -->
 
 ## Creating a custom library or interface
 

docs/algorithms/lu-solver.md

@@ -303,6 +303,7 @@ where $i,j = 0..(N-1)$.
 For readbility, we use $:$ to denote a range slicing operation to along a dimension of matrix $\mathbf{M}$, e.g.
 $\mathbf{M}\left[0:3, j\right]$.
 
+<!-- pyml disable line-length -->
 1. Initialize the permutations $\mathbf{P}$ and $\mathbf{Q}$ to the identity permutation.
 2. Initialize fill-in elements to $0$.
 3. Loop over all rows: $p = 0..(N-1)$:
@@ -326,11 +327,12 @@ $\mathbf{M}\left[0:3, j\right]$.
       2. $\mathbf{M}_p\left[0:N_p,0\right] \leftrightarrow \mathbf{M}\left[0:N_p,j_p\right]$
    6. Apply Gaussian elimination for the current pivot element:
       1. $\mathbf{M}_p\left[0,0:N_p\right] \gets \frac{1}{\mathbf{M}_p[0,0]}\mathbf{M}_p\left[0,0:N_p\right]$
-      2. $\mathbf{M}_p\left[1:N_p,0:N_p\right] \gets \mathbf{M}_p\left[1:N_p,0:N_p\right] - \mathbf{M}_p\left[1:N_p,0\right] \otimes \mathbf{M}_p\left[0,0:N_p\right]$  <!-- markdownlint-disable-line line-length -->
+      2. $\mathbf{M}_p\left[1:N_p,0:N_p\right] \gets \mathbf{M}_p\left[1:N_p,0:N_p\right] - \mathbf{M}_p\left[1:N_p,0\right] \otimes \mathbf{M}_p\left[0,0:N_p\right]$
    7. Accumulate the permutation matrices:
       1. In $\mathbf{P}$: swap $p \leftrightarrow p + i_p$
       2. In $\mathbf{Q}$: swap $p \leftrightarrow p + j_p$
    8. Continue with the next $p$ to factorize the the bottom-right block.
+<!-- pyml enable line-length -->
 
 $\mathbf{L}$ is now the matrix containing the lower triangle of $\mathbf{M}$, ones on the diagonal and zeros in the
 upper triangle.
@@ -801,7 +803,7 @@ The equation $\mathbf{L}\boldsymbol{y} = \mathbf{P}\boldsymbol{b}$ is solved as
 
 1. Loop over all block-rows: $i=0..(N-1)$:
    1. Loop over all lower-triangle off-diagonal columns (beware of sparsity): $j=0..(i-1)$:
-      1. $\boldsymbol{b}\left[i\right] \gets \boldsymbol{b}\left[i\right] - \mathbf{L}\left[i,j\right] \cdot \boldsymbol{b}\left[j\right]$.  <!-- markdownlint-disable-line line-length -->
+      1. $\boldsymbol{b}\left[i\right] \gets \boldsymbol{b}\left[i\right] - \mathbf{L}\left[i,j\right] \cdot \boldsymbol{b}\left[j\right]$.
       2. Continue with next block-column.
    2. If the matrix is a block matrix:
       1. Follow the same steps within the block.
@@ -815,7 +817,7 @@ The equation $Uz = y$ is solved as follows.
 
 1. Loop over all block-rows in reverse order: $i=(N-1)..0$:
    1. Loop over all upper-triangle off-diagonal columns (beware of sparsity): $j=(i+1)..0$:
-      1. $\boldsymbol{b}\left[i\right] \gets \boldsymbol{b}\left[i\right] - \mathbf{U}\left[i,j\right] \cdot \boldsymbol{b}\left[j\right]$.  <!-- markdownlint-disable-line line-length -->
+      1. $\boldsymbol{b}\left[i\right] \gets \boldsymbol{b}\left[i\right] - \mathbf{U}\left[i,j\right] \cdot \boldsymbol{b}\left[j\right]$.
       2. Continue with next block-column.
    2. Handle the diagonal element:
       1. If the matrix is a block matrix:
@@ -871,16 +873,16 @@ as well as the well-known
 
 #### Pivot perturbation algorithm
 
-Let $\mathbf{M}$ be the matrix, $\left\|\mathbf{M}\right\|_{\infty ,\text{bwod}}$ the
+Let $\mathbf{M}$ be the matrix, $\left|\mathbf{M}\right|_{\infty ,\text{bwod}}$ the
 [block-wise off-diagonal infinite norm](#block-wise-off-diagonal-infinite-matrix-norm) of the matrix.
 
-1. $\epsilon \gets \text{perturbation\_threshold} * \left\|\mathbf{M}\right\|_{\text{bwod}}$.
-2. If $|\text{pivot\_element}| \lt \epsilon$, then:
-   1. If $|\text{pivot\_element}| = 0$, then:
+1. $\epsilon \gets \text{perturbation\_threshold} * \lvert\mathbf{M}\rvert_{\text{bwod}}$.
+2. If $\lvert\text{pivot\_element}\rvert \lt \epsilon$, then:
+   1. If $\lvert\text{pivot\_element}\rvert = 0$, then:
       1. $\text{phase\_shift} \gets 1$.
       2. Proceed.
    2. Else:
-      1. $\text{phase\_shift} \gets \text{pivot\_element} / |\text{pivot\_element}|$.
+      1. $\text{phase\_shift} \gets \text{pivot\_element} / \lvert\text{pivot\_element}\rvert$.
       2. Proceed.
    3. $\text{pivot\_element} \gets \epsilon * \text{phase\_shift}$.
 
@@ -909,7 +911,7 @@ The residual $\boldsymbol{r}$ can be calculated.
 An estimation for the left-hand side can be obtained by using the pivot-perturbed matrix $\tilde{\mathbf{M}}$ instead of
 the original matrix $\mathbf{M}$.
 Convergence is reached when $\boldsymbol{r} \to \boldsymbol{0}$, which implies
-$\left\|\boldsymbol{\Delta x}\right\| \to 0$.
+$\left|\boldsymbol{\Delta x}\right| \to 0$.
 Solving for $\boldsymbol{\Delta x}$ and substituting back into
 $\boldsymbol{x}_{i+1} = \boldsymbol{x}_i + \boldsymbol{\Delta x}$ provides the next best approximation
 $\boldsymbol{x}_{i+1}$ for $\boldsymbol{x}$.
@@ -1131,7 +1133,7 @@ with dimensions $N_i\times N_j$.
          3. Loop over all rows of the current block: $k = 0..(N_{i,j} - 1)$:
             1. $\text{block\_row\_norm} \gets 0$.
             2. Loop over all columns of the current block: $l = 0..(N_{i,j} - 1)$:
-               1. $\text{block\_row\_norm} \gets \text{block\_row\_norm} + \left\|\mathbf{M}_{i,j}\left[k,l\right]\right\|$.  <!-- markdownlint-disable-line line-length -->
+               1. $\text{block\_row\_norm} \gets \text{block\_row\_norm} + \lvert\mathbf{M}_{i,j}\left[k,l\right]\rvert$.
             3. Calculate the new block norm: set
                $\text{block\_norm} \gets \max\left\{\text{block\_norm}, \text{block\_row\_norm}\right\}$.
             4. Continue with the next row of the current block.
@@ -1186,10 +1188,11 @@ $$
 \end{bmatrix}
 $$
 
+<!-- pyml disable line-length -->
 * The regular $L_{\infty}$-norm is $\max\left\{1+3, 3, 5, \frac{1}{2}, 1, 1\right\} = 5$.
 * The block-wise off-diagonal infinity $L_{\infty ,\text{bwod}}$-norm is
-  <!-- markdownlint-disable-next-line line-length -->
   $\max\left\{\max\left\{1, 3\right\}+\max\left\{3, 0\right\},\max\left\{5, 0\right\} + \max\left\{0, \frac{1}{2}\right\}, 1\right\} = \max\left\{3+3, 5+\frac{1}{2}, 1, 1\right\} = 6$.
+<!-- pyml enable line-length -->
 
 The two norms clearly differ and even the elements that contribute most to the norm are different.
 
@@ -1214,9 +1217,10 @@ $$
 \end{bmatrix}
 $$
 
+<!-- pyml disable line-length -->
 * The regular $L_{\infty}$-norm is $\max\left\{20+20+2+2,30+3,100,3+1\right\} = \max\left\{44,33,100,4\right\} = 100$.
 * The block-wise infinity norm with diagonals would be
-  <!-- markdownlint-disable-next-line line-length -->
   $\max\left\{\max\left\{20+20, 30\right\}+\max\left\{2+2, 3\right\},\max\left\{0,3\right\} + \max\left\{100, 1\right\}\right\} = \max\left\{40+4, 3+100\right\} = \max\left\{44, 103\right\} = 103$.
 * The $L_{\infty ,\text{bwod}}$-norm is
   $\max\left\{\max\left\{2+2, 3\right\},\max\left\{0,3\right\}\right\} = \max\left\{4, 3\right\} = 4$.
+<!-- pyml enable line-length -->

docs/algorithms/pf-algorithms.md

@@ -37,7 +37,9 @@ The following bus types can be present in the system:
   Note: this bus is not supported by power-grid-model yet.
 
 ```{note}
-Asymmetric power flow calculations require the network to have a reference to ground. For details and internal solution of asymmetric floating grids calculations in power-grid-model, please refer to [Floating grid handling](../user_manual/calculations.md#floating-grid-handling). 
+Asymmetric power flow calculations require the network to have a reference to ground. For details and internal solution
+of asymmetric floating grids calculations in power-grid-model, please refer to
+[Floating grid handling](../user_manual/calculations.md#floating-grid-handling).
 ```
 
 ## Newton-Raphson power flow

docs/algorithms/sc-algorithms.md

@@ -22,7 +22,8 @@ This gives the initial symmetrical short circuit current ($I_k^{\prime\prime}$)
 This quantity is then used to derive almost all further calculations of short circuit studies applications.
 
 ```{note}
-Short-circuit calculations are currently implemented in the phase (abc) domain and therefore require a grounded network, similar to asymmetric power flow calculations.
+Short-circuit calculations are currently implemented in the phase (abc) domain and therefore require a grounded network,
+similar to asymmetric power flow calculations.
 Note that this limitation does not exist in the sequence (0-1-2) domain but is present in the phase domain calculation.
 ```