Make props in documentation easier to parse (#984)#993
Make props in documentation easier to parse (#984)#993mcnuttandrew merged 5 commits intouber:masterfrom
Conversation
|
|
mcnuttandrew
left a comment
There was a problem hiding this comment.
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 🙌