OpenCraft Handbook Markdown Linting Rules

A couple of days ago, we had a problem with the Handbook, where the navigation items on the left weren’t being displayed properly. It turned out the updated Mkdocs requires a clean markdown file with some strict header rules that need to be watched.

Accordingly, we added a markdown linter to the handbook. Kudos to @Fox and @kahlil for reviewing those changes.

When reviewing the changes, there were conflicting discussions regarding the history that would be destroyed if certain errors where fixed, which are:

  • MD004/ul-style - Unordered list style
  • MD005/list-indent - Inconsistent indentation for list items at the same level
  • MD007/ul-indent - Unordered list indentation
  • MD013/line-length - Line length

Therefore, instead of addressing those quality errors, we ended up silencing them.

Later that day, @anon46505572 shared with us a link on how the python code formatter Black addresses the problem, Migrating your code style without ruining git blame.

Since it is possible to preserve history, we thought of discussing enabling the linting errors mentioned earlier.

Therefore, when you have the time, please consider taking a look at the pull request which:

  • Enforces an 80 character line length
  • Enforces specific list indentation
  • Enforces uniform list indentation for items at the same level
  • Enforces a specific style for unordered lists

Please share your thoughts on the merge request directly and vote below on whether you are with those changes, against them, or feel indifferent by them.

How do you feel about those changes?
  • Against
  • Indifferent
  • Support

0 voters

What line length do you prefer?
  • 80
  • 120
  • undefined :wink:

0 voters

[ Use SE-4028 for Logging Time ]

Can we make it 120? 80 characters make little sense in an HD, widescreen world.

3 Likes

@adolfo sure! 120 sounds good :smiley:

I’ll add some extra time to the ticket to address those changes in the pull request.


I’m glad there are two members who support this change already!

1 Like

80 to 100 characters means I can have 3 columns comfortably in my editor. 120 means only 2. Shorter lines are also so much nicer for readability and diffability imho. So they do still make sense. :stuck_out_tongue:

I can see the point for two columns (vdiff, etc), but can you enlighten me as to why one would need three?

For efficiency when making changes that require changing several files in quick succession (tracing, debugging, changes across multiple components, etc.). The more code that one can fit on the screen, the less context switching between files. It has always seemed silly to me that we have widescreen monitors but we usually don’t make good use of all that realestate.

@adolfo @swalladge let’s settle this with a poll :man_shrugging:

I added a poll above, please vote on it.

I also messed up and the previous poll’s statistics got reset.
So, @team please revote on the poll :sweat:.

I remember the votes were 5 for support and 1 for indifferent… But who knows, maybe this second ping will change the votes :cold_sweat:

1 Like

I agree with the sentiment, but I guess I’m just too used to thinking in windows/tabs/screens/what-have-you. (And no, I don’t like tiling window managers either. ;) )

@nizar @adolfo @anon46505572 Another reason I have for 80 is that my IDE creates a preview pane that live renders what I’m doing, so my three columns are the project listing, the code, and the preview render.

I can kind of squish things to make 120 fit, though, so my preference for 80 is slight.

I mean a lot of newer projects go for slightly wider than 80 characters (black the python formatter defaults to 88 chars, and I’ve seen 100 in several places). 120 is starting to get too long though. How about we compromise on middle ground - 100 characters? :wink:

I’ve commented on the PR already, but I don’t see the point of enforcing line length for text. Code ok, but this is a text file. Also don’t forget that this is meant to be edited by non-technical people - we should not be adding code-like linting to the handbook.

When you enforce a line length for prose (paragraphs of text) and then insert even a single word in the middle of the paragraph, it can generate a very ugly diff because you need to go through and modify the spacing of every single subsequent line to get it fixed:

Before:

the quick brown  |
fox jumped over  |
the lazy dog     |

After adding a single word (“sudo”):

the quick brown  |
-fox jumped over |
-the lazy dog    |
+ fox SUDO jumped|
+ over the lazy  |
+ dog            |

Literally everyone’s text editor is capable of soft wrapping the text at whatever width is perfect for their display, and it will always look best and have the cleanest diffs if you just use lines without any length limit and let the editor wrap them as needed based on where they’re being displayed.

So while I like most of these changes I personally don’t like line length limits for docs.

5 Likes

@braden’s comment is the reason I ended up closing the merge request.

I ended up running into that issue when making changes to the workflow manager discoveries on gitlab. And yeah, if we could avoid that, it would be better.

So I’m going to close the Jira ticket accordingly, since no additional work is needed.

Thanks to everyone who interacted with this forum thread, whether through the polls or replying to the thread!

1 Like

I agree that this is a problem if enforced in this way. However, the opposite problem is when entire paragraphs are on a single line, which is not nice even with soft wrapping. Git diffs are arguably just as bad because the entire paragraph has still changed. (except smart highlighting can point out the changes within the line usually).

May I introduce you to the idea of semantic line breaks. This is when you enter a line break where one would naturally pause anyway: at the end of sentences, after commas in long sentences, etc. Unfortunately some markdown processors treat these as hard breaks for some reason, but in most cases it’s the best of both worlds. Line lengths are manageable and diffs are informative.

But then you lose the usefulness of many linewise operators in some editors, and shorter semantically wrapped lines always look better than softwrapped lines. Plaintext is meant to be nicely manually formatted, not munged into one line.

Links:

2 Likes

Every tool I use has this smart highlighting, which is why I don’t see this as a problem.

Interesting, but I personally find this to be the “worst of both worlds.” I would prefer either other option.

I guess for Markdown my assumptions are different - I think of the plaintext formatting only as a convenience for the author and I assume that all readers are using a rendered version. Plus when I author I usually have a live preview of the rendered version open, so I find that soft wrapping is easy to work with and consistent with the final result:

However, I will grant that if you think of the plaintext version as the “final form” that people are consuming and authoring with, there is a strong case for line wraps. I don’t want to impose my opinion on the team here, but based on how I work I definitely prefer soft wraps.

That’s true, different workflows and different assumptions. For context, I never view the rendered output of a markdown document, unless in contains something mangled like a huge unaligned table or html escape codes. I take the view that markdown is a light markup syntax that is meant to be just as useful to consume in plain text as the rendered output (eg. I don’t see much difference in usability between a line prefixed with ## and a line in a larger font size). To quote John Gruber himself:

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

Curious though, what difference would it make to you if you always view a live preview of the rendered output?

Not every tool I use has it, so it is a problem often for me.

Yup, I think that explains our different opinions :)

Well I still see the plaintext version, and the varying line lengths bother me aesthetically.

To repeat something that I mentioned previously – remember that the handbook, and the rest of our non-technical documentation, need to remain simple to edit by non-technical team members. Adding constraints on the length of lines and requiring the use of specific line-wrapping in editors would add to an already pretty long list of non-intuitive requirements. We need to make it easier for non-technical users to participate in the team’s activities, not harder.

I’m generally on @anon46505572’s side of the debate, as I mostly write and consume markdown in its source format. Plus, I’m a vimmer, and vim doesn’t do arbitrary soft wrapping (one has to resize the window, which as a full-screener I’m loathe to do), so long lines are a bit of an eyesore.

I can’t say I like the proposed semantic breaks as an alternative, though. They’re too much of a departure from paragraphs, for me.

@antoviaque has a good point, though. I figure it’s part of our collective job description as open source folk to be highly adaptable to different text formatting standards. So I can work with whatever’s best for the intended audience that is least adaptable - which I’m guessing is unlimited line lengths.

(It’s too bad the non-technical world went that direction, though. I’m an RFC 822, 72 column person at heart, so between unlimited lines and 80 chars, I’ll pick 80 chars any time.)