-
-
Notifications
You must be signed in to change notification settings - Fork 7.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Docs] Improve README.md & CONTRIBUTING.md syntax #1864
Conversation
- Lists should be surrounded by blank lines - Use only `1.` for ordered list item prefix - Starting bulleted lists at the beginning of the line - Fenced code blocks should be surrounded by blank lines
@ljharb anything else I need to do here? Thanks. |
CONTRIBUTING.md
Outdated
@@ -5,14 +5,16 @@ We love pull requests and issues, they're our favorite. | |||
However, before submitting, please review the following: | |||
|
|||
For bug reports: | |||
- Please make sure the bug is reproducible, and give us the steps to reproduce it, so that we can dig into the problem. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i'm confused why this is an improvement; it seems like it'd render the same in the markdown, but it's much less readable in raw form.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's suggested by the markdownlint tool:
https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md006---consider-starting-bulleted-lists-at-the-beginning-of-the-line, the lists should start at the beginning of the lines, sounds reasonable?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No, i don’t agree with that rationale - i don’t care about the editing experience, but the reading experience in raw form is important to me.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
okay, I'll rollback this one, how about the others? Look good to you?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i think so; i'll take another look once the diff is updated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have a concern here, some of them, including the table of contents, start from the beginning of the lines, won't this make some inconsistency? and in that case of table of contents, it looks different.
Let me know if I should just "rollback" or the consistency should also be maintained, thanks.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i guess i'm not sure i see a need for consistency between all lists - lists that are top-level things like a TOC are one thing, and lists that are subpoints of another paragraph are another.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Okay, I'll just rollback those changes.
1d923c8
to
ccb9f4d
Compare
@ljharb are we good to go now? Thanks. |
ccb9f4d
to
accd1dd
Compare
accd1dd
to
f3fd5ef
Compare
There are four kinds of changes in this PR in a single commit:
1.
for ordered list item prefixThis improvement helps maintain the consistency in the document and the maintainability, readability in the document source.