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. 😢

[janbrasna]

FYI @subatoi from previous PRs this stance is not consistent as I recall a Pages/Jekyll-specific (pages-gem dependency-specific bug-related to be exact) content being included before: #31639

I have used similar distinction as you point out #31639 (review) — not that I'm against, or necessarily for documenting exceptions to downstream behaviour, it's just it should be clear and consistent, i.) for docs consumers generally, but in this case ii.) for contributors too, in a way style guide sets the level of consistency — the line between GFM/commonmark and their parsers (even when provided by GitHub Inc.), and the actual syntax used by GitHub.com (and GHES) should be clearly articulated: as the feature support differs. (Think mermaidJS or callouts, also mentioned in the linked PR review.)

I'm not upset, as some others are, about the (lack of) updates & features classic GH Pages generally receive in this decade, as I'm more than happy with the way the new Pages in Actions enable us to do what we like — it just feels everyone tiptoes around the fact. I believe once that's honestly stated somewhere, that the Pages dependencies are not receiving any new feature work and are only kept running for the millions already using it and secure in the state from its heyday couple years ago, there won't be as much confusion about the feature parity one would expect from seeing the rendered markdown on GitHub.com vs. deployed on GitHub.io by pages-gems.

[nguyenalex836]

@janbrasna Thank you very much for the thoughtful feedback 💛 We apologize for any issues the inconsistencies you outlined have caused. Our team will review your feedback, and discuss avenues to remedy this in the future.

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[janbrasna]

@nguyenalex836 Oh there's no need to apologise, I believe everyone came here to try to share their onboarding experience to help improving it for others that may come across the same disparity, or to document their path taken to give the idea what might have been missing in the docs for them to succeed right away.

(The louder community/community discussions about the limitations were linked from e.g. #31639 (comment) for reference, but they hopefully stay there;)…)

[nguyenalex836]

@jrzyshr Thank you for your patience while our team discussed the best path forward!

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.

Our team supports this idea, and will be handling this internally via a product callout for all the markdown docs.

Thank you again for raising a flag on this issue and your willingness to discuss this directly with us! I'll go ahead and close this issue 💛