chore(docs): migrate HTML comments to MDX comment syntax - #4629
Open
thetaPC wants to merge 1 commit into
Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
thetaPC
commented
Aug 10, 2026
|
|
||
| TODO | ||
| --> | ||
| {/* ## Customization */} |
Contributor
Author
There was a problem hiding this comment.
Multi-line comments don't work with Prettier so changed them to per line. I plan to evaluate if we can just remove them in a separate PR.
thetaPC
commented
Aug 10, 2026
| See the [theming documentation](/docs/theming/css-variables) for more information. | ||
|
|
||
| --> | ||
| {/* TODO add this functionality back as a css variable */} |
Contributor
Author
There was a problem hiding this comment.
Multi-line comments don't work with Prettier so changed them to per line. I plan to evaluate if we can just remove them in a separate PR.
thetaPC
commented
Aug 10, 2026
| Running an app on an iOS device requires a provisioning profile. If a provisioning profile has not been created yet follow these directions: | ||
|
|
||
| 1. <strong>Set the [Package ID](../reference/glossary.md#package-id).</strong> | ||
| 1. **Set the [Package ID](../reference/glossary.md#package-id).** |
Contributor
Author
There was a problem hiding this comment.
By swapping to **, we no longer need to use prettier ignore.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Issue URL:
What is the current behavior?
Our docs use HTML comments (
<!-- ... -->) for authoring notes and tooling directives. These are not valid MDX. Docusaurus only accepts them today because of themarkdown.mdx1Compat.commentsshim, which strips them before MDX parses the file. That shim is disabled by default in Docusaurus v4 viafuture.v4.mdx1CompatDisabledByDefault.Separately,
troubleshooting/native.mdused three<!-- prettier-ignore -->guards inside an ordered list. Those guards were doing more than suppressing formatting: an HTML comment is a block level node, so each one split the list, which is why steps 2, 3, and 4 each restarted their own numbering instead of forming one list of four.What is the new behavior?
HTML comments in the live docs trees are migrated to MDX comment syntax, and the
native.mdguards are removed by fixing what they were working around.<!-- ... -->to{/* ... */}{/* ... */}commentsindex.md's 2 guards converted; the JSX form is honored there because the guard precedes the start of a list, which is a real node boundarynative.md's 6 guards deleted entirely, by replacing the<strong>wrappers with Markdown**The
native.mdchange is the substantive one. Prettier was reflowing the<strong>children onto their own lines, after which MDX wrapped that text in its own paragraph and emitted invalid<strong><p>...</p></strong>. The guards existed to prevent that. Using Markdown emphasis instead removes the hazard at the source, so no guard is needed and the four steps now form a single well-formed ordered list. Nested<b>tags are preserved; one**Identity**became<b>Identity</b>to avoid nesting**inside**, matching how the file already marks up<b>Xcode</b>and<b>Signing</b>.Multiline blocks use per-line comments because Prettier mangles every multiline form into
{/\*, which then fails to compile. Verified against three variants: with blank lines, without blank lines, and with a{""expression prefix. All three were mangled.110 HTML comments are intentionally left in place: 108 inside code fences and 2 inside inline code spans, where they are example markup shown to readers rather than real comments.
Does this introduce a breaking change?
Other information
This is part of a series preparing the docs for the
.mdto.mdxmigration.How to test
Review the pages below. The comment changes should be invisible, since comments never rendered. Confirm no stray
<!--,{/*, or*/}text appears anywhere on the page.One page deserves a closer look:
https://ionic-docs-git-fw-6456-pt3-ionic1.vercel.app/docs/troubleshooting/native
Current (v8)
v7