Add markdown linting #16453
Labels
audience/nvda-dev
PR or issue is relevant to NVDA / Add-on developers
component/documentation
p4
https://github.com/nvaccess/nvda/blob/master/projectDocs/issues/triage.md#priority
triaged
Has been triaged, issue is waiting for implementation.
Is your feature request related to a problem? Please describe.
NVDA's internal repository documentation uses markdown.
Currently this is not linted, which means small formatting issues can occur if reviewers miss it.
NVDA's internal repository uses GitHub flavoured markdown, so any linting will require supporting this.
Additionally, NVDA's user documentation is being converted from text2tags to markdown (#16144).
After #16144 is merged making markdown the source of truth, it may be worth linting the English base, so that translators can adjust their files to match the English formatting.
Eventually, the user guide, changes and developer guide will have an English markdown version only, and translators will only be translating the documentation strings through a
*.po
file.After this happens, when we lint the English markdown base, it will ensure all translations have the same correct formatting.
NVDA's user documentation uses custom markdown rules, so any linting process will require supporting custom rules.
Describe the solution you'd like
A markdown linter that supports GitHub flavoured markdown, as well as adding custom rules.
Ideally this should be in Python to match the rest of the repository.
A promising solution is pymarkdownlnt.
Note this is currently in beta and approaching a stable release.
The linter passes all GitHub Flavoured Markdown conformance tests and CommonMark conformance tests.
The linter also supports git pre-commit hooks, which is useful for developers.
The linter also supports custom rules.
The linter does not support diffs - meaning we must fix the lint for files on a file-by-file basis, or all files at once.
Alternatively, we could fix lints for the whole repository on a rule by rule basis (excluding certain rules for the lint).
This is a lot easier than doing the same for python (#12261) and C++ (#12407) as we have less markdown files.
Describe alternatives you've considered
Encouraging linting on the developer side such as IDE tools (e.g. this VC code extension)
More stable/mature linters:
Additional context
None so far
The text was updated successfully, but these errors were encountered: