Markdown linting: Code block style (MD046)

[dshevtsov]

Bug report

Description

The Markdown linter reports about 704 issues when the rule 'MD046' is enabled.

Steps to reproduce

1. In the _checks/styles/style-rules-prod change exclude_rule 'MD046' to rule 'MD046', :style => :fenced.
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.

[atwixfirster]

Hi, @dshevtsov !

I have a question about MD046 rule.

For example, when this rule is active it reports issues:

README.md:160: MD046 Code block style
README.md:170: MD046 Code block style
...

If you open README.md and check lines 160 and 170 you will see code blocks:

Should we ignore this report or the marked code blocks are incorrect?

Thank you!

[dshevtsov]

@atwixfirster, a code bock have to be aligned with first symbol of text in the parent ordered list item.
The indentation for code blocks should be equal to 3 spaces in this case:

[atwixfirster]

Thank you for the explanations, @dshevtsov!

Per my opinion the Editorial label of this issue is a very low price for the requested changes. There are more than 1000 places where we should change code blocks.

This is a big piece of manual work.

[atwixfirster]

@jeff-matthews , does someone from DevDocs team work on this issue?

Thank you!

[jeff-matthews]

@atwixfirster, thanks for asking. This issue is not ready for development. In fact, none of the markdown linting issues that are ready for development. See https://github.com/magento/devdocs/wiki/Markdown-linting-issues for more information.

[jeff-matthews]

There are still MD046 errors that we cannot fix. The mdl tool identifies code blocks inside nested lists as errors. For example:

1. Lorem ipsum

   - Lorem ipsum

      ```bash
      mkdir
      ```

We can fix these "errors" by removing the line between the bullet and the code block, but that makes the source less readable. Since our goal with enabling linting rules is to promote the readability of source markdown, that's not a viable option.

For now, we should merge the fixes for legitimate errors and report this issue to the mdl maintainers. Until it's fixed however, we won't be enabling this rule on production.

[jeff-matthews]

No need to report this to the maintainers. It appears that it's already been reported and a PR is in place to fix it: markdownlint/markdownlint#293. It's been open since Jan 11.

[jeff-matthews]

Looks like the fix just got merged, which is great!

Now the question becomes, will we be able to use it when they bump the package version with this fix? For example, I don't think we can currently use the latest release (v0.8), but I don't remember why... I think there's a reason we're stuck on v0.7.

Cc: @dshevtsov

[dshevtsov]

It still fails on v0.8, I have not investigated the reason yet.

[dshevtsov]

It doesn't fail in the merchdocs project by the way: https://github.com/magento/merchdocs/blob/master/Gemfile#L11

[shrielenee]

Should this be moved out of Dev in Progress @dshevtsov @jeff-matthews ? What's the status on this?

[jeff-matthews]

As far as I know, we're still stuck on version .7 of the MDL tool, but it is not currently in progress. I'll move it.