Add markdownlint script to lint docs markup (WordPress#19855)

* Add markdownlint script to lint docs markup

Adds a new script `lint-md-docs` that runs markdownlint to lint markdown
files for proper syntax. A default `.markdownlint.json` config is
included, it will require some testing to tune.

Fixes WordPress#12426

* Clarify naming of lint-md scripts js and docs

- Updates lint-md scripts to lint-md-js for linting source included in the document and lint-md-docs for
linting the markup of the document itself.

- Update scripts changelog
- Update readme with commands

* Apply suggestions from code review

Co-Authored-By: Grzegorz (Greg) Ziółkowski <[email protected]>

* Fix URL for markdownlint CLI

* Add -i check, details around ignore on CLI

* Check for additional project config files

* Update script commands to all for lint:*

* Local changes applied to package-lock.json

* Update packages/scripts/README.md

Co-Authored-By: Grzegorz (Greg) Ziółkowski <[email protected]>

* Apply suggestions from code review

Thanks for the review and updates 👍

Co-Authored-By: Grzegorz (Greg) Ziółkowski <[email protected]>

Co-authored-by: Grzegorz (Greg) Ziółkowski <[email protected]>

.markdownlintignore

@@ -0,0 +1,9 @@
+bin
+build
+node_modules
+phpunit
+playground
+storybook
+test
+vendor
+wordpress

package.json

@@ -196,7 +196,8 @@
 		"lint-css": "wp-scripts lint-style '**/*.scss'",
 		"lint-css:fix": "npm run lint-css -- --fix",
 		"lint-types": "tsc",
-		"lint-md": "wp-scripts lint-md",
+		"lint:md-js": "wp-scripts lint-md-js",
+		"lint:md-docs": "wp-scripts lint-md-docs",
 		"package-plugin": "./bin/build-plugin-zip.sh",
 		"pot-to-php": "./bin/pot-to-php.js",
 		"publish:check": "lerna updated",

packages/scripts/CHANGELOG.md

@@ -8,8 +8,10 @@
 ### New Features
 
 - Add SVGR support to compile SVG files to React components using the `@svgr/webpack` plugin ([#18243](https://github.com/WordPress/gutenberg/pull/18243)).
+
 - Add `format-js` script to format JavaScript source code, it uses the [`wp-prettier`](https://github.com/Automattic/wp-prettier) – Prettier fork adjusted to WordPress coding style guidelines ([#18048](https://github.com/WordPress/gutenberg/pull/18048)).
-- Add `lint-md` script to lint JavaScript source code in markdown files, uses the `eslint-plugin-markdown` plugin ([#19518](https://github.com/WordPress/gutenberg/pull/19518)).
+- Add `lint-md-js` script to lint JavaScript source code in markdown files, uses the `eslint-plugin-markdown` plugin ([#19518](https://github.com/WordPress/gutenberg/pull/19518)).
+- Add `lint-md-docs` script to lint the markup of markdown files, uses the `markdownlint` module ([#19855](https://github.com/WordPress/gutenberg/pull/19855)).
 - Add `packages-update` script to update WordPress packages to the latest version automatically ([#19448](https://github.com/WordPress/gutenberg/pull/19448)).
 
 ## 6.1.1 (2020-01-01)

packages/scripts/README.md

@@ -33,7 +33,8 @@ _Example:_
 		"format:js": "wp-scripts format-js",
 		"lint:css": "wp-scripts lint-style",
 		"lint:js": "wp-scripts lint-js",
-		"lint:md": "wp-scripts lint-md",
+		"lint:md:docs": "wp-scripts lint-md-docs",
+		"lint:md:js": "wp-scripts lint-md-js",
 		"lint:pkg-json": "wp-scripts lint-pkg-json",
 		"packages-update": "wp-scripts packages-update",
 		"start": "wp-scripts start",
@@ -251,23 +252,47 @@ By default, files located in `build` and `node_modules` folders are ignored.
 
 It uses [npm-package-json-lint](https://www.npmjs.com/package/npm-package-json-lint) with the set of recommended rules defined in [@wordpress/npm-package-json-lint-config](https://www.npmjs.com/package/@wordpress/npm-package-json-lint-config) npm package. You can override default rules with your own as described in [npm-package-json-lint wiki](https://github.com/tclindner/npm-package-json-lint/wiki). Learn more in the [Advanced Usage](#advanced-usage) section.
 
-### `lint-md`
+### `lint-md-docs`
 
-Helps enforce standards for JS source code in your markdown files.
+Uses markdownlint to lint the markup of markdown files to enforce standards.
 
 _Example:_
 
 ```json
 {
 	"scripts": {
-		"lint:md": "wp-scripts lint-md"
+		"lint:md:docs": "wp-scripts lint-md-docs"
 	}
 }
 ```
 
 This is how you execute the script with presented setup:
 
-* `npm run lint:md` - lints markdown files in the entire project’s directories.
+* `npm run lint:md:docs` - lints markdown files in the entire project’s directories.
+
+By default, files located in `build` and `node_modules` folders are ignored.
+
+#### Advanced information
+
+It uses [markdownlint](https://github.com/DavidAnson/markdownlint) with the [.markdownlint.json](https://github.com/WordPress/gutenberg/blob/master/packages/scripts/config/.markdownlint.json) configuration. This configuration tunes the linting rules to match WordPress standard, you can override with your own config, see [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli/) for command-line parameters.
+
+### `lint-md-js`
+
+Uses ESLint to lint the source included in markdown files to enforce standards for JS code.
+
+_Example:_
+
+```json
+{
+	"scripts": {
+		"lint:md:js": "wp-scripts lint-md-js"
+	}
+}
+```
+
+This is how you execute the script with presented setup:
+
+* `npm run lint:md:js` - lints markdown files in the entire project’s directories.
 
 By default, files located in `build` and `node_modules` folders are ignored.
 

packages/scripts/config/.markdownlint.json

@@ -0,0 +1,8 @@
+{
+  "default": true,
+  "MD003": { "style": "atx" },
+  "MD007": { "indent": 4 },
+  "MD013": { "line_length": 9999 },
+  "no-hard-tabs": false,
+  "whitespace": false
+}

packages/scripts/package.json

@@ -53,6 +53,8 @@
 		"jest-puppeteer": "^4.3.0",
 		"js-yaml": "^3.13.1",
 		"lodash": "^4.17.15",
+		"markdownlint": "^0.18.0",
+		"markdownlint-cli": "^0.21.0",
 		"minimist": "^1.2.0",
 		"npm-package-json-lint": "^4.0.3",
 		"prettier": "npm:[email protected]",

packages/scripts/scripts/lint-md-docs.js

@@ -0,0 +1,55 @@
+/**
+ * External dependencies
+ */
+const { sync: spawn } = require( 'cross-spawn' );
+const { sync: resolveBin } = require( 'resolve-bin' );
+
+/**
+ * Internal dependencies
+ */
+const {
+	fromConfigRoot,
+	getArgsFromCLI,
+	hasArgInCLI,
+	hasFileArgInCLI,
+	hasProjectFile,
+} = require( '../utils' );
+
+const args = getArgsFromCLI();
+
+const defaultFilesArgs = hasFileArgInCLI() ? [] : [ '**/*.md' ];
+
+// See: https://github.com/igorshubovych/markdownlint-cli#configuration
+// Check if specified on command-line or project file for config
+const hasLintConfig = hasArgInCLI( '-c' ) || hasArgInCLI( '--config' ) ||
+	hasProjectFile( '.markdownlint.json' ) ||
+	hasProjectFile( '.markdownlint.yaml' ) ||
+	hasProjectFile( '.markdownlint.yml' );
+
+// When a configuration is not provided by the project, use from the default
+// provided with the scripts module.
+const defaultConfigArgs = ! hasLintConfig ?
+	[ '--config', fromConfigRoot( '.markdownlint.json' ) ] :
+	[];
+
+// See: https://github.com/igorshubovych/markdownlint-cli#ignoring-files
+// Check if ignore specified on command-line or project file
+const hasIgnoredFiles = hasArgInCLI( '--ignore' ) || hasArgInCLI( '-i' ) ||
+	hasProjectFile( '.markdownlintignore' );
+
+// Default ignore [ build, node_modules ] directories
+// TODO: Once https://github.com/igorshubovych/markdownlint-cli/issues/46 is in
+// we can switch this to specify an ignore file on the command-line. By default,
+// markdownlint looks for .markdownlintignore in project direcotry, but how our
+// scripts work we store the configs in the scripts/config directory
+const defaultIgnoreArgs = ! hasIgnoredFiles ?
+	[ '--ignore', '**/build/**', '--ignore', '**/node_modules/**' ] :
+	[];
+
+const result = spawn(
+	resolveBin( 'markdownlint-cli', { executable: 'markdownlint' } ),
+	[ ...defaultConfigArgs, ...defaultIgnoreArgs, ...args, ...defaultFilesArgs ],
+	{ stdio: 'inherit' }
+);
+
+process.exit( result.status );