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

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

Closed
1 task done
jrzyshr opened this issue May 16, 2024 · 16 comments
Closed
1 task done
Labels
content This issue or pull request belongs to the Docs Content team get started Content related to "Getting Started" doc set SME reviewed An SME has reviewed this issue/PR

Comments

@jrzyshr
Copy link

jrzyshr commented May 16, 2024

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.
@jrzyshr jrzyshr added the content This issue or pull request belongs to the Docs Content team label May 16, 2024
Copy link

welcome bot commented May 16, 2024

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.

@github-actions github-actions bot added the triage Do not begin working on this issue until triaged by the team label May 16, 2024
@nguyenalex836 nguyenalex836 added get started Content related to "Getting Started" doc set waiting for review Issue/PR is waiting for a writer's review and removed triage Do not begin working on this issue until triaged by the team labels May 16, 2024
@nguyenalex836
Copy link
Contributor

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

@subatoi
Copy link
Contributor

subatoi commented May 17, 2024

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
Copy link
Author

jrzyshr commented May 17, 2024

@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
Copy link
Contributor

subatoi commented May 20, 2024

@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
Copy link
Contributor

CBID2 commented May 20, 2024

Can I work on this once this issue is approved?

@nguyenalex836
Copy link
Contributor

@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
Copy link
Contributor

CBID2 commented May 20, 2024

Great @nguyenalex836! 😄

@Potherca
Copy link

it would have saved much time and aggravation.

Yes, for me too. 😢

@h3610124

This comment was marked as spam.

@h3610124

This comment was marked as spam.

@janbrasna
Copy link
Contributor

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
Copy link
Contributor

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

@subatoi subatoi added the needs SME This proposal needs review from a subject matter expert label Jul 31, 2024
Copy link
Contributor

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

@janbrasna
Copy link
Contributor

@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 nguyenalex836 added SME reviewed An SME has reviewed this issue/PR and removed waiting for review Issue/PR is waiting for a writer's review needs SME This proposal needs review from a subject matter expert labels Aug 1, 2024
@nguyenalex836
Copy link
Contributor

@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 💛

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
content This issue or pull request belongs to the Docs Content team get started Content related to "Getting Started" doc set SME reviewed An SME has reviewed this issue/PR
Projects
None yet
Development

No branches or pull requests

7 participants