Markdown linting: Lists should be surrounded by blank lines (MD032)

[dshevtsov]

Bug report

Description

The Markdown linter reports about 2897 issues when the rule 'MD032' is enabled.

Steps to reproduce

1. In the _checks/styles/style-rules-prod change exclude_rule 'MD032' to rule 'MD032'.
2. In your terminal, run rake test:md.

Test your updates

1. Follow "Steps to reproduce" locally to get list of errors to fix.
2. Preview the HTML locally to ensure your changes did not break formatting in the resulting HTML (run rake:preview). For more information, refer to the README.

Note-->Do NOT use special keywords in your commit message.

Expected result

All the reported issues are fixed.
The rake test:md command returns No issues found.

[jeff-matthews]

PR #5415 fixes a majority of the errors, but before we can close this issue and enable the rule on production we need to fix the remaining issues:

rake test:md
Testing Markdown style with mdl ...
guides/v2.2/cloud/cdn/trouble-fastly.md:208: MD032 Lists should be surrounded by blank lines
guides/v2.2/cloud/cdn/trouble-fastly.md:237: MD032 Lists should be surrounded by blank lines
guides/v2.2/mrg/ce/Signifyd.md:48: MD032 Lists should be surrounded by blank lines
guides/v2.3/cloud/cdn/trouble-fastly.md:208: MD032 Lists should be surrounded by blank lines
guides/v2.3/cloud/cdn/trouble-fastly.md:237: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/b2b/CompanyCredit.md:15: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Analytics.md:38: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Catalog.md:8: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/CatalogWidget.md:10: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Deploy.md:16: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Deploy.md:17: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Indexer.md:10: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/InstantPurchase.md:12: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Paypal.md:8: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Reports.md:8: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Robots.md:8: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Sales.md:12: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Sales.md:15: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/SalesSequence.md:12: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/SalesSequence.md:15: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/SampleData.md:30: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/SampleData.md:64: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Security.md:11: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Signifyd.md:50: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Tax.md:12: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Tax.md:13: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Tax.md:17: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Tax.md:22: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Tax.md:24: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Weee.md:25: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ce/Weee.md:32: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ee/CatalogPermissions.md:9: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ee/CatalogPermissions.md:12: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ee/Staging.md:13: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ee/Staging.md:19: MD032 Lists should be surrounded by blank lines
guides/v2.3/mrg/ee/Staging.md:31: MD032 Lists should be surrounded by blank lines

A detailed description of the rules is available at https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md

The Markdown linter has found 38 issues

We're considering some architectural changes that will eliminate the need to lint MRG topics, but we still need to address the cloud issues @hguthrie & @meker12.

[jeff-matthews]

Unfortunately, the error count rose to 6410 since #5415.

[jeff-matthews]

I fixed all the errors in https://github.com/magento/devdocs/tree/5250-enable-MD032, except for the following false positives:

guides/v2.2/cloud/cdn/trouble-fastly.md:215: MD032 Lists should be surrounded by blank lines
guides/v2.2/cloud/cdn/trouble-fastly.md:219: MD032 Lists should be surrounded by blank lines
guides/v2.2/cloud/cdn/trouble-fastly.md:223: MD032 Lists should be surrounded by blank lines
guides/v2.2/cloud/cdn/trouble-fastly.md:244: MD032 Lists should be surrounded by blank lines
guides/v2.3/cloud/cdn/trouble-fastly.md:215: MD032 Lists should be surrounded by blank lines
guides/v2.3/cloud/cdn/trouble-fastly.md:219: MD032 Lists should be surrounded by blank lines
guides/v2.3/cloud/cdn/trouble-fastly.md:223: MD032 Lists should be surrounded by blank lines
guides/v2.3/cloud/cdn/trouble-fastly.md:244: MD032 Lists should be surrounded by blank lines

The tool is identifying asterisks inside a code block as list items.

```terminal
* STATE: INIT => CONNECT handle 0x600057800; line 1402 (connection #-5000)
* Rebuilt URL to: https://www.mymagento.biz.c.sv7gVom4qrpek.ent.magento.cloud/
* Added connection 0. The cache now contains 1 members
* Trying 192.0.2.31...
...

[jeff-matthews]

I added some blank lines to resolve the errors, but it's not ideal since the rendered output will show extra lines as well. I can live with it though.