Add markdown style guide #46
Conversation
| * If possible, avoid double blank lines. | ||
| * Do not use indented code blocks, use 3+ backticks code blocks instead. | ||
| * Code blocks should have an explicit language tag. | ||
| * Do not wrap long lines. This helps with reviewing diffs of the source. |
There was a problem hiding this comment.
What was the outcome of last week's discussion about semantic line breaks?
My memory of the consensus was that we were not going to impose/enforce semantic line breaks.
However, what I think was left up in the air was the question of whether we would 1. accept material that has been authored with a semantic line break style, and also would 2. make a best effort attempt to retain any such pre-existing structure as changes are suggested to the text.
(For the time being, I'm going to author my own draft text assuming the latter is the case. But if we decide that is not a tenable position, then we should say so in this authoring.md text.)
There was a problem hiding this comment.
I don't think there was a very explicit outcome.
If there is a PR that had linebreaks after sentences, I would not comment on it.
If there is a PR that wrapped at some arbitrary column width, I would not want to accept that.
Perhaps a different way to state this is "Do not wrap long lines based on column widths"? Do you have a suggestion on what you would like it to say?
There was a problem hiding this comment.
(I don't want to block this further. I agree with Eric that there wasn't a very explicit outcome. And the text that is proposed here is consistent with that status. We can refine it later.)
|
I'm willing to merge this as-is. The only reason I did not do so already is that I did not want my question above to fall into the ether unaddressed if the PR is merge-closed. |
JoelMarcey
added
the
C-meta-formatting
This adds a guide for specific markdown formatting guidelines, along with a style checker for some of the rules.
Closes #40
Closes #37