doc: Add Markdown lint section to coding-style.rst
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user