diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 000000000..b0e93e394 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,20 @@ +# Markdownlint Rules + +# Configuration file schema: +# https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml + +# Markdown lint rules: +# Individual rules: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md +# Tags: https://github.com/DavidAnson/markdownlint#tags + +# Markdownlint CLI usage: +# https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#usage +# +# Example with Docker: +# docker run -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest . [--fix] + +default: true + +descriptive-link-text: false # MD059 +line-length: false # MD013 +no-duplicate-heading: false # MD024 diff --git a/.mdl_style.rb b/.mdl_style.rb deleted file mode 100644 index e5a02a7af..000000000 --- a/.mdl_style.rb +++ /dev/null @@ -1,17 +0,0 @@ -# Markdownlint Rules -# -# The Markdownlint style is defined according to the following rules: -# https://github.com/markdownlint/markdownlint/blob/main/docs/creating_styles.md -# -# The rules are defined in the following page: -# https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md - -all - -# Excluded rules -exclude_rule "MD013" # Line length -exclude_rule "MD024" # Multiple headers with the same content - -# Rule parameters -rule "MD007", :indent => 2 # Unordered list indentation -rule "MD026", :punctuation => ".,;:!" # Trailing punctuation in header diff --git a/doc/contributing/source/coding-style.rst b/doc/contributing/source/coding-style.rst index 2053dceef..ec6290fb6 100644 --- a/doc/contributing/source/coding-style.rst +++ b/doc/contributing/source/coding-style.rst @@ -1911,73 +1911,79 @@ add the following configuration to ``.vscode/settings.json``: 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 +.. _MarkdownLint: https://github.com/DavidAnson/MarkdownLint +.. _MarkdownLint Rules: https://github.com/DavidAnson/MarkdownLint/blob/main/doc/Rules.md +.. _MarkdownLint Installation: https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#installation +.. _MarkdownLint Configuration File: https://github.com/DavidAnson/MarkdownLint/blob/main/schema/.MarkdownLint.yaml +.. _MarkdownLint Docker: https://github.com/igorshubovych/MarkdownLint-cli/pkgs/container/MarkdownLint-cli +.. _MarkdownLint VS Code Extension: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-MarkdownLint -|ns3| uses `Markdownlint`_ as a linter of Markdown files. +|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 detects linting issues and can fix most of them automatically. +Some issues may need to be manually fixed. -Markdownlint configuration +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. +MarkdownLint's settings are saved in the file ``.markdownlint.yml``. +This schema of this file is defined in `MarkdownLint Configuration 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`_. +The list of Markdown rules supported by MarkdownLint is available in `MarkdownLint Rules`_. -Install and Run Markdownlint +Install and Run MarkdownLint ============================ -Markdownlint is written in Ruby. To run Markdownlint, either use the official -Markdownlint Docker image or install Ruby and Markdownlint. +MarkdownLint is written in NodeJS. To run MarkdownLint, either use the official +MarkdownLint Docker image, install it natively in macOS via Homebrew, +or install MarkdownLint with NodeJS / npm. -Run Markdownlint with Docker image +Run MarkdownLint with Docker image ################################## -Markdownlint has an official Docker image in `Markdownlint Docker Hub`_ with the tool +MarkdownLint has an official Docker image in `MarkdownLint Docker`_ 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: +To run MarkdownLint in a Docker container, use the following command: .. sourcecode:: console - docker run -v .:/data markdownlint/markdownlint -s .mdl_style.rb . + # Check all Markdown files in the current directory and subdirectories + docker run --rm -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest . [--fix] -Install and Run Markdownlint with Ruby -###################################### + # Check specific Markdown file + docker run --rm -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest PATH_TO_FILE [--fix] -To install Markdownlint natively, you need to have Ruby installed in your system. -Check the installation instructions in the Ruby's official documentation. +If the ``fix`` flag is used, the tool tries to automatically fix the detected issues. +Otherwise, it only reports the issues found. -After installing Ruby in your system, install Markdownlint using the following command: +Install and Run MarkdownLint natively +##################################### + +To install MarkdownLint natively, either on macOS via Homebrew or using NodeJS / npm, +follow the instructions available in `MarkdownLint Installation`_. + +To run MarkdownLint, use the following command: .. sourcecode:: console - gem install mdl + # Check all Markdown files in the current directory and subdirectories + markdownlint-cli . [--fix] -To run Markdownlint and check Markdown files for linting issues, run Markdownlint -using the following command: - -.. sourcecode:: console - - mdl -s .mdl_style.rb . + # Check specific Markdown file + markdownlint-cli PATH_TO_FILE [--fix] 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. +For VS Code users, the `MarkdownLint VS Code Extension`_ extension is available in the marketplace. +This extension uses the same engine and respects the configuration file. -The Markdownlint extension automatically analyzes files open in the editor and provides inline hints +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. +As explained in the "Integration with IDEs" section, VS Code can be configured to automatically +format code when saving, editing or pasting code. diff --git a/utils/tests/gitlab-ci-code-linting.yml b/utils/tests/gitlab-ci-code-linting.yml index 7b701c43e..02e270a4e 100644 --- a/utils/tests/gitlab-ci-code-linting.yml +++ b/utils/tests/gitlab-ci-code-linting.yml @@ -144,8 +144,10 @@ python-format-3.8: # Markdown lint markdown-lint: stage: .pre - image: ruby:slim + image: node:slim before_script: - - gem install mdl + - npm install -g markdownlint-cli script: - - mdl -s .mdl_style.rb . + - markdownlint . + timeout: 1h + interruptible: true