Add spellcheck and URI link validation on Markdown files in tests

[PlagueHO]

To help improve the quality of the MD files in the DSC Resource Kit, we could add tests for spelling and URI link validation. As per discussion with @vors here.

• Spellchecking: New-MarkdownHelp Generates Markdown that violates many MD rules platyPS#345 (comment)
• Markdown link check: https://github.com/vors/MarkdownLinkCheck

These look like they could be added pretty easily. We'd want to use the "Opt-in" model for this like most tests.

[johlju]

All for this!

Not sure if it can be applied here, but this also have npm packages. For spell checking I use Code Spell Checker in Visual Studio Code which uses cspell. Mostly because it has dictionaries for several languages (source), even Swedish 😍. It can test the code as well, like comment-based help and variables. Although I have a massive list of exclusions.
The spell check with different dictionaries could be used when testing localization files. But that could be an enhancement down the line 😄

[johlju]

Looking at the MarkdownLinkCheck module, it seems it very outdated. The source Markdig is on version 0.15.1 now; https://github.com/lunet-io/markdig#download. Looking at the change log it feels that we want to use a newer version.
Maybe we can use the module, but replace the .dll to a newer version before we import the module, or if we can download the npm and use it directly in some way?

[vors]

I bumped MarkdownLinkCheck to use 0.15.1 Markdig and published it as 0.2.0
Let me know if you see any problems!

[johlju]

@vors many thanks for updating the module for us! 😃

[johlju]

Looking at the spellchecker. Running that in for example SqlServerDsc it generates a lot of spelling errors because it does not recognize a lot of word that are specific to the module. But those are easy added to the .spelling file.

npm install -g markdown-spellcheck
mdspell '**/*.md' -report --ignore-numbers --ignore-acronyms --en-us

.spelling

SqlScript
DscAdmin1

[johlju]

If cSpell is used for spelling, then the same configuration file can be used for the VSCode extension "Code Spell Checker".
Personally I'm using this extension to spell check the code, and it helps making sure to not use abbreviations, and not making spelling mistakes in variables. Would be great if this could spell check at least comments in code, but that can be a future enhancement. First markdown I think. 🙂

Also, the output of cSpell looked easier to parse, or rather, no need to parse it.

No errors:

CSpell: Files checked: 1, Issues found: 0 in 0 files

Errors:

README.md:158:28 - Unknown word (sqlserviceaccount)
README.md:160:19 - Unknown word (sqlsetup)
README.md:161:23 - Unknown word (sqlwaitforag)
README.md:163:29 - Unknown word (sqlwindowsfirewall)
Tests/Integration/README.md:26:1 - Unknown word (DSCTABULAR)
Tests/Integration/README.md:74:57 - Unknown word (adatper)
Tests/Integration/README.md:96:1 - Unknown word (DSCRS)
Tests/Integration/README.md:181:31 - Unknown word (dbcreator)
Tests/Integration/README.md:188:1 - Unknown word (dbcreator)
CSpell: Files checked: 2, Issues found: 9 in 1 files

Install:

npm install -g cspell
cspell '**/*.md' -local 'en-US' --no-color  --config 'cSpell.json'

.vscode/cSpell.json (stripped version of the config file used for SqlServerDsc):

{
    "ignorePaths": [
        ".git",
        ".vscode"
    ],
    "language": "en",
    "dictionaries": [
        "powershell"
    ],
    "words": [
        "Addnode"
    ],
    "ignoreRegExpList": [
        "/windowsservercore/g",
        "/SQLPS/g",
        "/AppVeyor/g"
    ]
}

[johlju]

@vors Tried MarkdownLinkCheck, and it finds broken links in my tests, but there are one issue, do you know if it can be solved (easily)? The issue is that it seems to think a correct link that points to a folder is broken. For example it fails on all the links in the README.md here.

https://github.com/PowerShell/SqlServerDsc/tree/dev/Examples

Path       : C:\Source\SqlServerDsc\Examples\README.md
Text       : SqlAG
Url        : /Examples/Resources/SqlAG
IsBroken   : True
IsAbsolute : False
Line       : 10
Column     : 3

[johlju]

Opened issue vors/MarkdownLinkCheck#5 for previous comment.

[johlju]

Markdown link linting is proposed in PR #273. Looking at adding spell check when I have time.

[johlju]

Issue vors/MarkdownLinkCheck#5 is closed, I did not use relative path - made a review comment so we can add that to the docs.

[johlju]

Added PR #279 for spell-checking, although there is currently a problem with using cSpell, it sends output to stderr even when there is no error, submitted issue streetsidesoftware/cspell#61.