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

Show file tree
Hide file tree
Changes from 2 commits
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
6 changes: 3 additions & 3 deletions website/docs/guides/markdown-features/markdown-features-intro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -230,8 +230,8 @@ Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/

:::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.
- You may want to keep your `<summary>` on a single line. [MDX creates extra HTML `<p>` paragraphs for line breaks.](https://mdxjs.com/migrating/v2/#jsx)
- You should add a blank line between the `<summary>` element and the first paragraph of the detailed content, or React will emit a warning in the console in the DevTools: `Warning: validateDOMNesting(...): <summary> cannot appear as a descendant of <p>.`
- You can optionally add a blank line between the nested `<details>` element and the paragraphs just around the nested `<details>` to clarify the semantic boundary between the two.
Copy link
Collaborator

Choose a reason for hiding this comment

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

I'm going to remove that too because this is incorrect

A blank line after summary is not required. In general, the only rule that apply is how MDX creates extra paragraphs on line breaks

These 2 forms do not involve blank lines and are perfectly valid:

<details>
  <summary>hey</summary>
  <>hoo</>
</details>
<details><summary>hey</summary>hoo</details>

Copy link
Contributor Author

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

Choose a reason for hiding this comment

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

@slorber

on line breaks

If the paragraph candidate is composed of only inline JSXes (<...>...</...>) and whitespaces (including line breaking), it's not enclosed by a <p>.

<>foo</>bar<>baz</>

↑ will be enclosed by <p> because bar is a bare element.

<>foo</><>bar
baz</><>qux</>
<>quux</>

↑ won't be enclosed by <p> because they consist of 3 inline JSXes and a newline (between <>qux</> and <>quux</>)

<details><summary>hey</summary>hoo</details>

↑The entire line is the paragraph candidate, but all the content is enclosed by the inline JSX, so no paragraph is inserted.

<details>
  <summary>hey</summary>
  <>hoo</>
</details>

↑Its paragraph candidate is (block JSX narrows the range of paragraph candidate):

  <summary>hey</summary>
  <>hoo</>

The entire content of both 2 lines is enclosed by an inline JSX tag (<summary> and <>).
With a notation like <>hoo</>, you can't add another paragraph or a code block there.

<summary>hey</summary>
<>foo
bar
baz</>
<>qux
quux</>

This is also OK because no bare elements (not enclosed by inline JSX)

<summary>hey</summary>
<>foo
bar</>
baz
<>qux
quux</>

baz is bare there, so a paragraph will be inserted.

I feel it's difficult for me to explain it to beginners simply.


:::
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 may want to keep your `<summary>` on a single line. [MDX creates extra HTML `<p>` paragraphs for line breaks.](https://mdxjs.com/migrating/v2/#jsx)
- You should add a blank line between the `<summary>` element and the first paragraph of the detailed content, or React will emit a warning in the console in the DevTools: `Warning: validateDOMNesting(...): <summary> cannot appear as a descendant of <p>.`
- You can optionally add a blank line between the nested `<details>` element and the paragraphs just around the nested `<details>` to clarify the semantic boundary between the two.

:::