From ad1a8e9f862e603d0397d7906cc460066cdfa748 Mon Sep 17 00:00:00 2001
From: Eduardo Almeida <enmsa@outlook.pt>
Date: Fri, 18 Oct 2024 13:58:03 +0100
Subject: [PATCH] doc: Add Markdown lint section to coding-style.rst

---
 doc/contributing/source/coding-style.rst | 74 ++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/doc/contributing/source/coding-style.rst b/doc/contributing/source/coding-style.rst
index 449eec853..f17b91b57 100644
--- a/doc/contributing/source/coding-style.rst
+++ b/doc/contributing/source/coding-style.rst
@@ -1820,3 +1820,77 @@ add the following configuration to ``.vscode/settings.json``:
       "pyproject.toml",
     ],
   }
+
+Markdown Lint
+*************
+
+.. _Markdownlint: https://github.com/markdownlint/markdownlint
+.. _Markdownlint Rules: https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md
+.. _Markdownlint Configuration Style File: https://github.com/markdownlint/markdownlint/blob/main/docs/creating_styles.md
+.. _Markdownlint Docker Hub: https://hub.docker.com/r/markdownlint/markdownlint
+.. _Markdownlint Docker Instructions: https://github.com/markdownlint/markdownlint/tree/main/tools/docker
+.. _Markdownlint VS Code Extension: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
+
+|ns3| uses `Markdownlint`_ as a linter of Markdown files.
+This linter checks if Markdown files follow a set of defined rules, in order to encourage
+standardization and consistency of Markdown files across parsers.
+It also ensures that Markdown files are correctly interpreted and rendered.
+
+Markdownlint detects linting issues, but it can not fix them automatically.
+The issues must be fixed manually.
+
+Markdownlint configuration
+==========================
+
+Markdownlint's settings are saved in the file ``.mdl_style.rb``.
+This file is defined in `Markdownlint Configuration Style File`_, which explains how to
+customize the tool to enable / disable rules or customize its parameters.
+
+The list of Markdown rules supported by Markdownlint is available in `Markdownlint Rules`_.
+
+Install and Run Markdownlint
+============================
+
+Markdownlint is written in Ruby. To run Markdownlint, either use the official
+Markdownlint Docker image or install Ruby and Markdownlint.
+
+Run Markdownlint with Docker image
+##################################
+
+Markdownlint has an official Docker image in `Markdownlint Docker Hub`_ with the tool
+and all dependencies installed.
+The instructions to use the Docker image are available in `Markdownlint Docker Instructions`_.
+
+To run Markdownlint in a Docker container, use the following command:
+
+.. sourcecode:: console
+
+  docker run -v .:/data markdownlint/markdownlint -s .mdl_style.rb .
+
+Install and Run Markdownlint with Ruby
+######################################
+
+To install Markdownlint natively, you need to have Ruby installed in your system.
+Check the installation instructions in the Ruby's official documentation.
+
+After installing Ruby in your system, install Markdownlint using the following command:
+
+.. sourcecode:: console
+
+  gem install mdl
+
+To run Markdownlint and check Markdown files for linting issues, run Markdownlint
+using the following command:
+
+.. sourcecode:: console
+
+  mdl -s .mdl_style.rb .
+
+VS Code Extension
+=================
+
+For VS Code users, the `Markdownlint VS Code Extension`_ extension is available in the marketplace.
+This extension is inspired in `Markdownlint`_ and follows the same set of rules.
+
+The Markdownlint extension automatically analyzes files open in the editor and provides inline hints
+when issues are detected. It can automatically fix most issues related with formatting.