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.

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

Table of Contents menu shows links to headings within a collapsed <details> #7265

Closed
7 tasks done
JoshuaKGoldberg opened this issue Apr 29, 2022 · 4 comments
Closed
7 tasks done
Labels
bug An error in the Docusaurus core causing instability or issues with its execution closed: duplicate This issue or pull request already exists in another issue or pull request

Comments

@JoshuaKGoldberg
Copy link
Contributor

JoshuaKGoldberg commented Apr 29, 2022

Have you read the Contributing Guidelines on issues?

Prerequisites

  • I'm using the latest version of Docusaurus.
  • I have tried the npm run clear or yarn clear command.
  • I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
  • I have tried creating a repro with https://new.docusaurus.io.
  • I have read the console error message carefully (if applicable).

Description

The generated tables of contents (ToC) for a markdown page includes headings inside collapsed <details>. Clicking the ToC link does nothing.

This was mentioned back in #5790. I haven't found anything in the [HTML5 spec](https://html.spec.whatwg.org/#the-details-element section on <details>) about disallowing heading content inside it. Some online sites such as https://a11ysupport.io/tech/html/summary_element reference them being allowed. https://stackoverflow.com/questions/49594772/should-i-specify-h2-h6-sub-headings-for-a-details-tag-to-make-the-details-a-dist#:~:text=Headings%20within%20details,)%2C%20provide%20heading%20elements%20within even references it being preferred (though I again can't find a source).

See the typescript-eslint site and PR referenced in this issue for an example of where I'd want this. Specifically, I wanted to include headings inside a details view because there's a lot of content that could benefit from having sections. The details content isn't something most page readers need, though, so I didn't want to have the reading journey on the page include it so early.

member-ordering._.TypeScript.ESLint.-.Google.Chrome.2022-04-29.09-11-02.mp4

Reproducible demo

https://j2rm6f.sse.codesandbox.io/markdown-page

Steps to reproduce

  1. Add a <details> element to a markdown page
  2. Include a ## ... heading inside that details element
  3. View the markdown page

Expected behavior

I would think one of the two would happen:

  • Clicking the ToC heading would expand the <details> element
  • The ToC doesn't show headings inside collapsed <details>

#5790 is related

Actual behavior

The ToC includes headings inside collapsed <details>. Clicking the ToC link does nothing.

Your environment

Self-service

  • I'd be willing to fix this bug myself.
@JoshuaKGoldberg JoshuaKGoldberg added bug An error in the Docusaurus core causing instability or issues with its execution status: needs triage This issue has not been triaged by maintainers labels Apr 29, 2022
@Josh-Cena
Copy link
Collaborator

Duplicate of #7165

@Josh-Cena Josh-Cena marked this as a duplicate of #7165 Apr 29, 2022
@Josh-Cena
Copy link
Collaborator

So

  1. This is working as intended because the TOC algorithm doesn't really know what's containing each heading node (because the MDAST doesn't encode this info)
  2. You shouldn't put structural content in details
  3. As a workaround, you can use JSX tags like <h2>Heading</h2> which will be ignored by the TOC algorithm
  4. You may want to watch out for Ergonomic way to enhance ToC within Markdown: insert TOC slice, exclude headings #6201

@Josh-Cena Josh-Cena added closed: duplicate This issue or pull request already exists in another issue or pull request and removed status: needs triage This issue has not been triaged by maintainers labels Apr 29, 2022
@JoshuaKGoldberg
Copy link
Contributor Author

Aha, I missed that one - sorry for the dup, and thanks for the quick answer!

@Josh-Cena
Copy link
Collaborator

No problem, that one was worded a bit differently so it's hard to search...

@Josh-Cena Josh-Cena closed this as not planned Won't fix, can't repro, duplicate, stale May 28, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug An error in the Docusaurus core causing instability or issues with its execution closed: duplicate This issue or pull request already exists in another issue or pull request
Projects
None yet
Development

No branches or pull requests

2 participants