F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Replace markdownlint by markdownlint-cli

Browse Source
This commit is contained in:
Eduardo Almeida
2025-08-25 05:43:45 +01:00
parent 7a5b86565a
commit b90f4c0c64
4 changed files with 68 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
.markdownlint.yml Normal file
View File

@@ -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

17
.mdl_style.rb
View File

@@ -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

80
doc/contributing/source/coding-style.rst
View File

@@ -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.

8
utils/tests/gitlab-ci-code-linting.yml
View File

@@ -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