Markdown lint english resource files

[rousik]

Added basic configuration to _scripts/mdlint-rules.yml

Processed our existing english resource files and removed most of the lint complaints. Adjusted line length to 100 characters to allow for more convenient editing and displaying.

[rousik]

@emersonthis who works on page design (my changes to md files may interfere with your work) and @nditada and @mverzilli who are my usual reviewers.

[github-actions]

This pull request is being automatically deployed with now-deployment

Built with commit 51f0dcb

✅ Preview: https://guide-preview-qmffh9yzd.now.sh

[rousik]

This is related to issue #253

[emersonthis]

The removal of these classes is causing a bit of a regression. You'll notice in the preview that the three main section headings no longer match.

[emersonthis]

I don't care much about stripping the styles from "Things you should do" or "Things you should not do" but the same should happen for "Myths" if we do that. And, ideally, we'd remove the unused CSS rules that will be left over.

[rousik]

Oh. I thought that when both {:.only_toc} and {:.do.no_toc} had the same header they could be collapsed into one. At least that was the way it used to be in the older version of the website.

Do we have some documentation or summary of how these mdfiles should be structured that I can look at so that I avoid making these erroneous assumptions?

[emersonthis]

whatever we do here should be reconciled with the classes for "Things you should do" and "Things you should not do"

[nditada]

@rousik I'm afraid this will trigger a massive list of files that need re-translation... Is the lenght limit the source of most of the changes?

[rousik]

Line lengths are source of some of this, but there are other non-content changes that would propagate into Lokalise. Let me hold off on this and see if there'd be a way to make it less disruptive to translations. Ideally we'd have a way to tell Lokalise to not force/request re-translation if all that changed was just whitespace/newlines.

…

On Tue, Apr 7, 2020 at 7:23 PM nditada ***@***.***> wrote: @rousik <https://github.com/rousik> I'm afraid this will trigger a massive list of files that need re-translation... Is the lenght limit the source of most of the changes? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#326 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABYSCGAUEG6QZA4KWCDSMNLRLPG2XANCNFSM4MDPRPOA> .

[rousik]

If I understand the localization process correctly I don't think that line-lenghts are the real deal-breaker here. My assumption is that as soon as we change even a little thing in the source, this will invalidate all existing translations and mark them for "re-translation". It's possible that breaking lines will make the diffs more noisy though and that may make the translation process more difficult.

[jaysonvirissimo]

What do we think of semantic, rather than merely length-based line breaks? For example, "severely impacted" would still be on line 10, because it is part of the same unit of thought (sentence, in this case). I personally find this style leads to easier to understand GitHub diffs.

[rousik]

I'd be in favor of that but I think it's also much easier to enforce at the time of writing rather than when we try to make the markdown files compliant.

[rousik]

I think that this conversion is not worth the translation/lokalise disruption as-is so I'm going to retract it and experiment with some more relaxed approach.