Outdated documentation about $$ around math expression

[gashtaan]

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://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]

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]

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

[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: guntrip/buderus-rc35-internals@9889900

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 ✨