Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add markdown linting #16453

Open
seanbudd opened this issue Apr 26, 2024 · 0 comments
Open

Add markdown linting #16453

seanbudd opened this issue Apr 26, 2024 · 0 comments
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.

Comments

@seanbudd
Copy link
Member

seanbudd commented Apr 26, 2024

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

@seanbudd seanbudd added component/documentation p4 https://github.com/nvaccess/nvda/blob/master/projectDocs/issues/triage.md#priority audience/nvda-dev PR or issue is relevant to NVDA / Add-on developers triaged Has been triaged, issue is waiting for implementation. labels Apr 26, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
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.
Projects
None yet
Development

No branches or pull requests

1 participant