-
Notifications
You must be signed in to change notification settings - Fork 832
Make props in documentation easier to parse (#984) #993
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
Conversation
mcnuttandrew
left a comment
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.
Wow! Thanks for doing this, this is great. This is a good win for consistency across the docs. I pulled down your PR and applied a few tweeks. I think using blue for a stronger highlighting is a good move, but I think it's a little distracting for prop so i moved it to be as the code blocks and made the prop titles bigger and underlined. What do you think?
I think it is good to break up the lines of the prop description so that it is a little easier to see. I know this is a kinda big/tedious ask, but as long as you are doing such good legibility upgrade would you mind inserting line breaks before and after all the type declaration, eg
#### data
Type: `Array<Object>`
Array of data for the series.
will become
#### data
Type: `Array<Object>`
Array of data for the series.
Which is important i guess for how our markdown interpreter interprets the markdown?
I'm really glad you are taking a look at this, making docs easier to read is real important. I ran a lighthouse accessibility audit over the docs page and we don't really do very well. This PR pushes us in a good direction on that front.
|
Ah yes, good call! Updated to the underline and moved the blue highlight to code elements following a h4/h5. This also includes inline code elements in the text - I could go either way on the blue highlight in general. I think it's a little loud, but not necessarily too much, plus it gives the docs a bit of personality which I like. I went through and added new lines around |
|
This rules! You are big a hero for doing all this. I'll merge it in now, and I'll try to cut a new copy of the docs this evening. |


I took a stab at making the props in the docs easier to parse - I like when the attributes are very visible, but totally understand if the style is too bold.
Since props in the docs are just generic headers (h3, h4, h5), I targeted h4 and h5s to prevent changing headers in other parts of the docs. There are a few prop declarations that use
h3s, which are updated in the second commit 🙌