-
Notifications
You must be signed in to change notification settings - Fork 59.1k
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
Comments
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. |
@jrzyshr Thanks so much for opening this issue! I'll get this triaged for review ✨ |
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? |
@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 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. |
@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. |
Can I work on this once this issue is approved? |
@CBID2 As soon as this issue is ready to be worked on, we'll be sure to put the |
Great @nguyenalex836! 😄 |
Yes, for me too. 😢 |
This comment was marked as spam.
This comment was marked as spam.
This comment was marked as spam.
This comment was marked as spam.
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. |
@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. |
Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀 |
@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 |
@jrzyshr Thank you for your patience while our team discussed the best path forward!
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 💛 |
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:
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 amarkdown="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.
Additional information
To reproduce the issue:
The text was updated successfully, but these errors were encountered: