chore(api): generate component API partials as .mdx - #4640
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
ShaneK
left a comment
ShaneK
left a comment
There was a problem hiding this comment.
I'm worried about the impact of these changes on i18n
ShaneK
left a comment
ShaneK
left a comment
There was a problem hiding this comment.
Wearily approved with comments. Still not sure right before v9 releases is the best time to merge this one, in case of issues caused by it.
| createData(`${basePath}/events.md`, data.events), | ||
| createData(`${basePath}/methods.md`, data.methods), | ||
| createData(`${basePath}/parts.md`, data.parts), | ||
| createData(`${basePath}/props.mdx`, data.props), |
There was a problem hiding this comment.
The plugin change is global but the page rewrites only live on main, so this leaves the major branches inconsistent. Their api pages still import the .md partials, both in docs/api and in the versioned copies, and major-10.0 only gets this through major-9.0 since a direct sync from main won't run.
On this line the base has v8 with .md, main has v8 with .mdx, and major-9.0 has v9 with .md, so resolving it the way we normally do, where the major branch wins, quietly drops the migration and leaves those pages on .md while the plugin only emits .mdx for en. For this reason, I believe this merge will require extra care and is kind of dangerous to do at this time. Could you try to do companion commits on the major branches alongside this one? Emitting the .md names unconditionally would work too and it's closer to what I asked for originally, since it's safe whatever order things merge in.
To see what I'm concerned about, it may be worth creating a worktree off of major-9.0 and try merging this branch into it and see what gets left out.
| * `.docusaurus` rather than a docs content root, so they are never routed as pages | ||
| * and the duplicate basenames cannot collide. | ||
| */ | ||
| if (context.i18n.currentLocale === 'ja') { |
There was a problem hiding this comment.
Did you get a chance to run a ja build against this?
Could you also file something to track dropping these? There's no issue linked from the comment and translation/jp moves slowly enough that I think this outlives the PR by a good while.
2 participants
Issue URL: internal
What is the current behavior?
The component API plugin writes its generated partials with a
.mdextension: props, events, methods, parts and slots. Those files are MDX, not CommonMark, so the extension is inaccurate. The sixth partial, custom-props, is already.mdx, which suggests this was hit once before and fixed for a single file.Each API page then imports them by explicit filename, so the extension is repeated across every page, for example importing Props from
@ionic-internal/component-api/v8/button/props.md.What is the new behavior?
The plugin emits
.mdxfor the five remaining partials, and the import specifiers are updated to match.plugins/docusaurus-plugin-ionic-component-api/index.jsdocs/(94) andversioned_docs/version-v7(87)Every doc file change is a specifier swap; there are no other edits.
Does this introduce a breaking change?
Other information
Part of the mdx migration.
How to test
Check a page where all six partial types have content:
The content, datetime, popover and select pages also populate all six if you want another sample.