I’m seeing this in scope markdown ci results. Why is this a thing? Don’t we all have editors that wrap long lines? Also there is also ‘blanks around headings’ and ‘lists surrounded by blanks’? None of this impacts how markdown renders?
The CI is a style na*i for no reason and I think we should make it stop – advice appreciated.
Markdown files are still code, so it makes sense to have a enforceable code style.
C++ codestyle doesn’t impact the behavior of generated machine code, but I don’t think anyone would object against having a enforceable code style, thus, I don’t see how markdown should be different. We still have to maintain markdown as code, it’s not like we are using a Google Docs for our readme. Just like any piece of code, the bigger audience is usually subsequent maintainers, if you follow the rules, the markdown source code is actually really nice to look at and read through due to its consistency.
Unfortunately there’s no auto formatter for markdown files, so we have to do all the formatting our-self. So I definitely feel your frustrations, I reformatted the original readme file and the entire beman repo against the same markdown config.
‘blanks around headings’ and ‘lists surrounded by blanks’ are what comes as default in markdownlint. It is very configurable.
The original line length limit was 80, current setting is 119 so it aligns with our clang-format file. I would very much against increasing the limit for the same reason an above 120 line length would be horrible for formatting C++.
To answer directly, there are still quite a lot of code viewer/ editor that doesn’t support line warp. For example, GitHub’s native code viewer doesn’t support it by default. I am pretty sure if someone submitted this as a PR for review it will get called out.
This line is 644 character long.
You can feel true pain if you view it from GitHub mobile web/app.
Note the clipping functionality from discourse also renders the line without warpping.
Plus there were talks (credit to @Sdowney ) about enforcing a format rule so that it’s one sentence max per line to help with git diff and align with standard paper formatting. Currently markdown-lint doesn’t support this so its not implemented, but I am pretty sure there won’t be any well-formed sentence that is 644 characters long.
I am definitely open to tweaking some rules in markdown-lint, right now the extra config is:
Increase line length from 80 to 119 to align with column width in clang-format, this is so we can copy-paste code from markdown file without triggering a reformat.
Allow extra HTML tags so we can use GitHub specific formatting tools like foldables.
Again, the main pain is because there’s no auto-format for markdown files. The errors from the linter is very descriptive and the resulting code is very consistent and nice to look at, it’s just a lot if you simply copy-paste a previously un-formatted markdown code in.
Oh yes they do – but that’s not important for this discussion.
This seems to make space for headers, but doesn’t care about long lines. There are some editor plug-ins around but I’m not seeing a command line tool.
Look at a markdown tutorial and show me one that does this? I think we should turn this off since it does not impact the output and arguably doesn’t improve the editing experience.
Paragraph text is very different than code. Code signals flow/structure with format and is rendered as-is on devices – that is unchanged from source format. For a markdown text paragraph it’s the opposite – the device/software renders the paragraph appropriate to the client. Markdown source paragraphs should not have line breaks in them - especially given that markdown requires space between paragraphs. On some devices those newlines will render as a second space.
The only place the line length of the source text matters is in code editors – all the ones I"m aware of can wrap those markdown source lines just fine. This constraint should be removed.
This is a non use case – display the rendered version on your phone.
Diff highlighters. Actually I think it’s the opposite. The highlighters will show individual word changes in a line, but they lose context when you have multiple lines. See the change on 104 and 105? Notice how it doesn’t highlight the godbolt link change?
Scan some of the diffs of that file for yourself – that’s org mode (different kind of markdown) and it has very long lines. Mostly it shows the diffs just fine.
I can live with the space between stuff rules if forced to, but it’s mostly an annoyance with no real benefit – the line length needs to be removed. It’s simply wrong and will trigger on long URLs and other things.
Whatever we do, I think consistency would be beneficial. I don’t want to commit to someone’s repository and have my change rejected in code review because I didn’t (or did) add spaces around a # heading. It would be better if pre-commit let me know before I committed (and even fixed it).
I prefer fixed line lengths in text files like markdown. There’s no need to configure any text editor to read those (including notepad). This isn’t the case for one-line-per-paragraph styling. I very much dislike the “sentence per line” approach as it makes it ackward to read in normal text editors.
These are my most humble opinions, offered up on bended knee to our one true Style Czar, the magnificent@Jeff-Garland, whose every pronouncement is gospel. I pray that he makes the right decision, guided by his infinite wisdom and mercy.