[docs] Fix some markdown spec issue #18428
Conversation
|
No bundle size changes comparing 3772c19...ff6bdc4 |
There was a problem hiding this comment.
@eps1lon What do you mean by "broken page"? The API markdown pages will likely soon be gone (so we can ignore them). The other pages seem to display correctly?
consider tags as code e.g. ->
<head>(otherwise crowdin produces broken markup: https://material-ui.com/zh/styles/api/#stylesprovider)
This one is definitely broken, it would be great to solve it 👍.
While mdx is currently not used in our docs
Do we want to migrate to mdx? What would we gain vs the time we spend on it? At least, the performance aspect of it didn't seem to make a significant difference.
I'm experimenting with it on the side though it's not part of this discussion.
The linked PR has nothing to do with what mdx does. The performance difference is significant (500-1000ms main thread work gone) but there are other issues that need to be solved. But again this is not part of this discussion.
markdown is malformed resulting in display of raw html or missing formatting etc.
Sure. As I said automatic task is not part of this PR. |
I don't fully understand. The content seems correctly formated when looking at https://material-ui.com/. However, it's not when we look at it from the GitHub interface. Is this accurate? |
|
We have probably more than 500 pages in markdown. The landing page isn't the only one displayed in markdown. I'm happy to discuss with you whether you consider some of the pages currently broken. But, again, these fixes will be applied via crowdin not PR.
I don't think I changed pages that are usually viewed in GitHub (e.g. readmes, changelogs, etc) |
oliviertassinari
changed the title
oliviertassinari
changed the title
|
I really don't understand, what does "broken" mean in this context? (https://material-ui.com/zh/styles/api/#stylesprovider is visually broken but the other pages seems to render identically) |
I don't have other words for "broken formatting", sorry. I guess if you don't consider https://material-ui.com/zh/styles/api/#stylesprovider "broken" then not understanding what broken means is understandable. |
|
@eps1lon Thank you! So if I understand it correctly, mdx has helped to identify one broken visual formatting page (https://material-ui.com/zh/styles/api/#stylesprovider). The other changes help to better fit into the markdown spec. They have no visual impact be are necessary to automate the issue detection 👍 . |
|
I isolated some of the issues: b8a1bf6 The link will likely get broken in the future since I heavily rebase while working. |
|
@eps1lon This issue is interesting: -`Checkbox`コンポーネントは` FormControlLabel<code>コンポーネントを説明のラベルとして使うことができます。</p>
+`Checkbox`コンポーネントは` FormControlLabel` コンポーネントを説明のラベルとして使うことができます。In the past, I had to go into the Crowdin interface to fix the translations (translations with missing closing tags |
|
Notice that if we sum all the usage of the translations, they account for 12% of the usage of the documentation, 88% is still in english. |
So is the argument to follow crowdin and drop these translations completely because no translation is better than a partial (or incorrect) translation? |
|
@eps1lon I wish we could have usage stats from reactjs.org. It could help know: if there is potential for the translations, for instance, if they have a 40% usage rate of the translated documentation, then, we know it's important and that we don't perform well enough.
|
While mdx1 is currently not used in our docs it helped detect broken pages (~30 currently, fixes will be deployed to crowdin).
<and>when it isn't used for tags<head>->`<head>`(otherwise crowdin produces broken markup: https://material-ui.com/zh/styles/api/#stylesprovider)<img>tagsstyle=""(here: extract inline svg into images which also makes them more accessible, reduces markdown parsing!, enables lazy loading)1 can be considered as a stricter subset of markdown for this purpose.
I'll work on automating detecting and fixing these issues in another PR.