-
Notifications
You must be signed in to change notification settings - Fork 42
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
Add documentation style guide and tool configs #5320
Conversation
"style": "leading_and_trailing" | ||
}, | ||
"ul-style": { | ||
"style": "dash" |
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 always use *
, but this dog can learn new tricks!
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 used to also; the rationale I drew this from was that it's easier to read when you do things like this:
* **A bold bullet**
vs.
- **A bold bullet**
But frankly, this is a nit - if *
are more comfortable/natural I'm not opposed to changing this - consistency is more important than which character.
Markdownlint also support a sublist
style which uses different symbols as you nest:
* Item 1
+ Item 2
- Item 3
+ Item 4
* Item 4
+ Item 5
Summary
This PR proposes a documentation style guide and configurations for Prettier, markdownlint, and ESLint tooling. The style guide is a subset of Google's documentation and Markdown style guides.
If accepted, I will follow up with another PR to format/lint all of the current docs files.
A final step will be to propose automated checks by way of GitHub workflows to validate formatting on PRs that modify docs.
Change Type
Mark the type of change your PR introduces:
Testing
Tested that the prettier, markdownlint, and eslint configurations are reporting issues as expected. Auto-generated docs (API/CLI/protocol) have been excluded/ignored.
Review Checklist: