Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: backport #10173 to v3.3 + v3.4 & revise the content #10180

Merged
merged 5 commits into from
Jun 21, 2024
Merged

docs: backport #10173 to v3.3 + v3.4 & revise the content #10180

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3c0d6b1
docs: backport #10173 to v3.3
tats-u May 25, 2024
fb7d740
Reword
tats-u Jun 2, 2024
1fd9a76
wording
slorber Jun 21, 2024
f3808cb
Merge branch 'main' into fix-details2
slorber Jun 21, 2024
7eb56d7
wording
slorber Jun 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 39 additions & 24 deletions ...rsioned_docs/version-3.3.2/guides/markdown-features/markdown-features-intro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,42 +181,57 @@ Markdown quotes are beautifully styled:

Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) HTML elements are beautifully styled:

```md
{/* prettier-ignore */}
````md
### Details element example

<details>
<summary>Toggle me!</summary>
<div>
<div>This is the detailed content</div>
<br/>
<details>
<summary>
Nested toggle! Some surprise inside...
</summary>
<div>😲😲😲😲😲</div>
</details>
</div>

This is the detailed content

```js
console.log("Markdown features including the code block are available");
```

You can use Markdown here including **bold** and _italic_ text, and [inline link](https://docusaurus.io)
<details>
<summary>Nested toggle! Some surprise inside...</summary>

😲😲😲😲😲
</details>
</details>
```
````

```mdx-code-block
````mdx-code-block
<BrowserWindow>

<h3>Details element example</h3>

<details>
<summary>Toggle me!</summary>
<div>
<div>This is the detailed content</div>
<br/>
<details>
<summary>
Nested toggle! Some surprise inside...
</summary>
<div>😲😲😲😲😲</div>
</details>
</div>

This is the detailed content

```js
console.log("Markdown features including the code block are available");
```

You can use Markdown here including **bold** and _italic_ text, and [inline link](https://docusaurus.io)
<details>
<summary>Nested toggle! Some surprise inside...</summary>

😲😲😲😲😲
</details>
</details>

</BrowserWindow>
```
````

:::info

- You should not break lines between the starting or ending tag of the `<summary>` element and its content or an extra `<p>` element is inserted.
- Blank lines between the `<summary>` element and the first paragraph of the detailed content are optional in Docusaurus but strongly recommended to ensure MDX portability with other site generators.
- Blank lines between the nested `<details>` element and the paragraphs just around it are optional.
Copy link
Collaborator

@slorber slorber May 31, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would just quickly mention something like:

You may want to keep your <summary> on a single line. MDX creates extra HTML <p> paragraphs for line breaks.

And if there's a good mdx doc explaining this, link to it.

It's the responsibility of the user to decide whether or not they want line breaks, it might make sense in some cases 🤷‍♂️

About the portability, maybe that's true but even I am unsure of what you mean here? Do you mean the Docusaurus MDX v2+ code would be incompatible with other systems still using MDX v1? That seems overkill to me to mention that, most of the ecosystem is already using MDX v2+ and those who don't will probably upgrade

Copy link
Contributor Author

@tats-u tats-u Jun 2, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

other systems still using MDX v1?

Intended for not v1 but v2.
In the first place, I've just found React emits the following warning (error by the default behavior of React 18+) in the console in the DevTools: Warning: validateDOMNesting(...): <summary> cannot appear as a descendant of <p>.
I'll reword it as like "You should, or React emits the warning."

You may want to keep your <summary> on a single line. MDX creates extra HTML <p> paragraphs for line breaks.

I'll take this expression for the first item.

if there's a good mdx doc explaining this, link to it.

I think the current best item is https://mdxjs.com/migrating/v2/#jsx.


:::