[docs-infra] Fix markdown version for material

[alexfauquette]

Fix #40659

I prevent the prepareMarkdown from adding the API section, such that the MarkdownV2 does not have to use hack to remove this section the the table of content and not rendering the last markdown content

[oliviertassinari]

I did the change on purpose in 99acbfb as part of #38410 to improve the performance of the page transition (it's much faster between button pages than between other pages because they share the same layout component, one that doesn't need to remount).

I think the fix should go the other way around, fix MarkdownDocsV2 so we can progressively migrate everything to it and kill MarkdownDocs. This will yield faster page transitions.

(@Janpot @michaldudak this is an example of what I have in mind with docs-infra / code-infra / other-infra changes being propagated everywhere in the codebase: breaking changes goes into new APIs, until enough MUI X, Toolpad, projects migrated)

[Janpot]

(@Janpot @michaldudak this is an example of what I have in mind with docs-infra / code-infra / other-infra changes being propagated everywhere in the codebase: breaking changes goes into new APIs, until enough MUI X, Toolpad, projects migrated)

100% agreed. All changes should be opt-in until all repositories have migrated. imo, this shouldn't apply only to internal code, we could benefit from organizing the versioning of our public code around the same philosophy. Any breaking change is introduced opt-in before a major version makes it the default.
This gives users the freedom to plan the migration of individual features at their own pace before increasing a major. This in contrast with having a major version mandating an all-or-nothing migration effort which is way riskier and harder to plan for.

[alexfauquette]

this is an example of what I have in mind with docs-infra / code-infra / other-infra changes being propagated everywhere in the codebase: breaking changes goes into new APIs, until enough MUI X, Toolpad, projects migrated)

I agree with the principle of having the change opt-in. But this implies encouraging the team to move on those topics. Otherwise, we end up with 2 to the power the number of migrations not fully done. For example, Markdown/MarkdownV2 has existed for more than a year, and I assume few people care/know about it.

At least with the infra team we now have devs in each team aware of the modification, but opening issues and setting deadlines could help to avoid accumulating those

[Janpot]

At least with the infra team we now have devs in each team aware of the modification, but opening issues and setting deadlines could help to avoid accumulating those

The purpose of the opt-in behavior is to improve collaboration. To allow multiple people make breaking changes concurrently without requiring a release cadence. It is not to be used as a way to produce migration work for other teams.

I think the most effective way to enforce this is to establish end-to-end ownership of a feature. Ideally the person who builds the new feature also propagates it to dependent projects, either by actually coding it themselves or serving as a liaison for someone on the dependent team.

[mui-bot]

Netlify deploy preview

https://deploy-preview-41908--material-ui.netlify.app/

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against 0c572b7

[Janpot]

Looks good 👍

Suggestion could be to prefer polymorphism over conditionals here. i.e. use something like a headers.hasApiSection flag over checking the product id. But conditionals on product id are already all over the place, so... yeah 🤷

[alexfauquette]

Suggestion could be to prefer polymorphism over conditionals here. i.e. use something like a headers.hasApiSection flag over checking the product id. But conditionals on product id are already all over the place, so... yeah 🤷

Yes, I thought about it, more like ignoreApiSection, but the idea of adding that to all the base-ui markdown feels bad