Outdated documentation about $$ around math expression

[gashtaan]

Code of Conduct

• [X] I have read and agree to the GitHub Docs project's 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]]

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]

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

[github-actions[bot]]

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

[guntrip]

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 b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^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]

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

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]

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

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]

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:

• The font has changed
• Sometimes whitespace and colors are missing on first render and needs a refresh of the site

[guntrip]

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]

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

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

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

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

[nguyenalex836]

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

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]

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

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]

@guntrip Ping

[nguyenalex836]

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

[gashtaan]

@nguyenalex836 Any news about this issue that the responsible team is already aware of?

[nguyenalex836]

@gashtaan No news from the responsible team, but the Basic writing and formatting syntax doc has been updated with a section on line breaks. Mathematical expressions in the Writing mathematical expressions have been updated as well.