search

github / docs

The open-source repo for docs.github.com
https://docs.github.com
Creative Commons Attribution 4.0 International
16.37k stars 59.9k forks source link

Outdated documentation about $$ around math expression #34247

Closed gashtaan closed 3 months ago

gashtaan commented 3 months ago

Code of Conduct

What article on docs.github.com is affected?

https://github.com/github/docs/blob/main/content/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions.md

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

Something has changed recently, $$ symbols around math expression are now ignored and do not force to show the expression as a block. Not sure if it's a feature or a bug, however the documentation doesn't reflect real state anymore, so it either should be fixed or documentation updated.

See paragraph Writing expressions as blocks: On the PNG image the expression is shown as a block centered under the heading, but it doesn't look like it anymore.

Additional information

No response

welcome[bot] commented 3 months ago

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 commented 3 months ago

@gashtaan Thank you for opening an issue! I'll get this triaged for review ✨

github-actions[bot] commented 3 months ago

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

guntrip commented 3 months ago

Hi @gashtaan! Thanks for opening this. Where are you seeing this behaviour? Taking the example from the article, it appears to be working:

The Cauchy-Schwarz Inequality $$\left( \sum_{k=1}^n a_k bk \right)^2 \leq \left( \sum{k=1}^n ak^2 \right) \left( \sum{k=1}^n b_k^2 \right)$$

If this is a bug, the best route would be via GitHub Support so they can escalate it to our engineering team, but let's first figure out what's working and isn't working! 😄

If this is regarding the block being centered or not, let me know.

gashtaan commented 3 months ago

@stevecat Hi, weird, I see the expression ok in your post, but not in README.md in one of my repositories in github viewer. It's not about the block is not centered, equations in my document are not displayed in blocks at all, so it becomes quite unreadable.

Please, see: https://github.com/gashtaan/buderus-rc35-internals/blob/main/Equations/README.md

I've tried the exact example code (you posted here) in github's editor and it's not displayed in block as it should.

guntrip commented 3 months ago

Thanks @gashtaan, I can see that! ✨

I think the issue might be whitespace, many markdown features don't render unless they have some space around them. I added some space around your math expressions in a fork and they're rendering as expected now (I think, please confirm 😄):

https://github.com/stevecat/buderus-rc35-internals/blob/patch-1/Equations/README.md

You can see what I changed in this commit: https://github.com/stevecat/buderus-rc35-internals/commit/98899000c2f80dc73552242c6db1946ac7008874

I think we could still make a change to the docs here as the following isn't very helpful:

To add a math expression as a block, start a new line and delimit the expression with two dollar symbols $$.

Can you let me know if the markdown file in my fork is rendering as you expected? If so, I'll confirm what we can change in the docs to help other folks.

gashtaan commented 3 months ago

@stevecat Yes, hacking another newline between expressions fixes it, but it definitely worked without it until something changed on your side. IMHO markdown features should work the same in the documents and also in the posts... and as you already found out, it does not.

guntrip commented 3 months ago

Thanks @gashtaan, you're right, this is only affecting rendered markdown documents.

If this had always been the case, I'd be in favour of documenting this. As something has actually changed, I think it's worth escalating. I can't find any internal issues open about this so I'd suggest speaking to our support team so they can investigate, work with our engineering team, and look into fixing this.

I'll close this docs issue for now. If the end result of escalating to support is discovering that this can't be fixed, ping me here and I'll re-open the issue and find a way to document this for others ✨

gazab commented 3 months ago

We've also seen some regression regarding math expressions in markdown without us changing anything. In our case they are in Pull Request comments where we, creatively, use them to color text like this:

$\textsf{Plan:{\color{green} 1 to add}, 0 to change, 0 to destroy.}$

What I've noticed:

guntrip commented 3 months ago

Hey @gazab! That's a neat use of math expressions 😮

As there's been a change, and things aren't rendering on first load, I'd suggest speaking to support too. This sounds like something our engineering team might want to look at.

gashtaan commented 3 months ago

@stevecat What does this "speaking to support" mean? It seems the only way to speak is to create a discussion and hope that somebody will care.

nguyenalex836 commented 3 months ago

@gashtaan Hello! 👋 He is referring to this link (https://support.github.com/request) which he included in his last response 💛 After clicking the link, you may a choose a topic and submit a support ticket for the related issue

gashtaan commented 2 months ago

@nguyenalex836 Yes, I already did that a week ago. I created new discussion in community forum referenced from that page under topic "Repositories". https://github.com/orgs/community/discussions/135637 It just seems weird to me that there is no github's way to report an issue (like here).

gashtaan commented 2 months ago

No response at all. Is there really no way how to report a bug?

nguyenalex836 commented 2 months ago

@gashtaan Hi 👋 Like we mentioned previously, this link (https://support.github.com/request) that @guntrip previously provided is a link to our Support team, not to open a discussion. Just wanted to make sure there wasn't any confusion between the two 💛

After clicking the link to contact our Support team (https://support.github.com/request), you may a choose a topic and submit a support ticket for the related issue.

gashtaan commented 2 months ago

No, I don't see any option to create the ticket on provided link.

But I just noticed that according the documentation only paid accounts have option to create support ticket. I have only GitHub Free account, so all I can do is "discuss" about it and that option is useless :(

https://docs.github.com/en/support/contacting-github-support/creating-a-support-ticket "If your account uses GitHub Free, you can speak to GitHub users and staff on the GitHub Community discussions for most issues, and you can contact GitHub Support to report account, security, and abuse issues."

nguyenalex836 commented 2 months ago

@gashtaan Thank you for providing context regarding your account! Rest assured, given the circumstances, raising a discussion is the best course of action to surfacing your feedback 💛

gashtaan commented 1 week ago

I'll close this docs issue for now. If the end result of escalating to support is discovering that this can't be fixed, ping me here and I'll re-open the issue and find a way to document this for others ✨

It seems this bug will never be fixed, so I'm pinging you... I guess if it doesn't work correctly, it should be documented at least.

gashtaan commented 5 days ago

@guntrip Ping

nguyenalex836 commented 3 days ago

@gashtaan Hello! 👋 We've inquired about this internally, and found that the responsible team is aware of this bug. They have opened an issue to investigate this bug further.

While we cannot provide information regarding timeline for next steps, the owning team is aware and will investigate this bug in the future 💛