Update docs for "Organizing information with collapsed sections" to include GitHub Pages support

[jrzyshr]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections

What part(s) of the article would you like to see updated?

The sample Markdown displayed in the article will fail to render properly on a GitHub Pages website generated with Jekyll:

<details>

<summary>Tips for collapsed sections</summary>

### You can add a header

You can add text within a collapsed section. 

You can add an image or a code block, too.

```ruby
   puts "Hello World"
```

</details>

Problem: This Markdown will result in the Jekyll renderer (Kramdown or GHMarkdown) treating all content in the Markdown file after the first <summary/> tag being rendered as plain text. The webpage will hide the plain text in a collapsible section. If the user clicks on the text in the <summary> tag on the GH Pages webpage, it will expand revealing the plain text from the source Markdown file in the GitHub repo.

Solution: Adding a markdown="1" attribute to the <details> tag and a markdown="span" attribute to the <summary> tag will solve this issue.

I discovered the solution in this issue from the Kramdown repo: gettalong/kramdown#155 (comment)

I propose either the sample in the document be updated as per the block below, OR a note added afterwards calling out this scenario when GH Pages is used with your Markdown.

<details markdown="1">

<summary markdown="span">Tips for collapsed sections</summary>

### You can add a header

You can add text within a collapsed section. 

You can add an image or a code block, too.

```ruby
   puts "Hello World"
```

</details>

Additional information

To reproduce the issue:

1. Create a Markdown file with the content from the sample snippet from this page in the docs
2. Enable GH Pages to render a site from the branch where your Markdown file is.
3. View the corresponding HTML page in the GH Pages site.

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[nguyenalex836]

@jrzyshr Thanks so much for opening this issue! I'll get this triaged for review ✨

[subatoi]

Hi @jrzyshr—many thanks for opening an issue and explaining in such detail.

The documentation under https://docs.github.com/en/get-started/writing-on-github/ concerns writing on GitHub itself (that is, issues/comments/PRs etc.) and so I wouldn't necessarily expect the sample Markdown on the page you highlighted to render without any modifications on a GitHub Pages site. There may very well be something we can do to make this clearer, but I just want to make sure about expectations here, in case you're seeing another use case I've missed?

[jrzyshr]

@subatoi you wrote: "I wouldn't necessarily expect the sample Markdown on the page you highlighted to render without any modifications on a GitHub Pages site."

I would! Since GH Pages is a feature of GH and its main purpose is to render documentation for repo contents, it would make sense to support this common use case.

I accept that Markdown may render different or need modifications to render on GH Pages. However, this should, at a minimum, be called out in the official GH doc I filed this issue on.

I manage a repo of hackathon content here: What The Hack. We started adopting collapsible sections as it made it easier to document how to use GH Codespaces across all of our hackathons. When I discovered that the <details> & <summary> tags broke our GH Pages website (which is what students use), it took multiple days of searching online to come across the solution, buried deep in the comments of an issue opened in 2014! That was not a good experience.

If the solution I covered above were on the official GH docs page for how to handle collapsible sections, it would have saved much time and aggravation. :)

Let me know if you need more support to make this change.

[subatoi]

@jrzyshr Many thanks for your thoughts and elaborating so clearly: we really appreciate it.

Technically speaking, we don’t disagree with your interpretation, but we need to think about this in terms of how we manage the content, and think about it in terms of which specific GitHub feature each section is dedicated to. We don’t always get the language perfectly correct, but in this case, we specifically think of “GitHub” as “github.com” in the context of what’s under https://docs.github.com/en/get-started/writing-on-github

In order to try to account for the issue you’ve highlighted here, we’d instead add a note with some information to the Pages documentation (that being what lives under https://docs.github.com/en/pages). We’re happy to discuss where best to put that, and you or anyone else is welcome to open a pull request with the changes once that’s agreed.

[CBID2]

Can I work on this once this issue is approved?

[nguyenalex836]

@CBID2 As soon as this issue is ready to be worked on, we'll be sure to put the help wanted label on the issue to notify you and any others who may want to contribute 💛

[CBID2]

Great @nguyenalex836! 😄

[Potherca]

it would have saved much time and aggravation.

Yes, for me too. 😢