Correct Alerts syntax or clarify context where they are expected to work

[SerratedSharp]

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?

I have tried all of the syntax under the Alerts section and none of them seem to work. The note says a prior syntax is deprecated and you should "use the syntax as described in this section" implying what follows currently works. It mentions this is an extension of markdown, but doesn't clarify in what contexts it should work. At least it doesn't work in github project readme.md files.

Additionally I would say screenshots shouldn't be used as the rendering example. Just repeat the syntax itself without code ticks to demonstrate what it renders as-is since you are already in a github md file.

https://github.com/github/docs/blob/e77f16ab2c0fa2603239f8ef5fe51cae7f27dbcf/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

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

The Alerts section

Additional information

My attempts to follow the instructions as well as variations I saw suggested when discussion Alerts not working:

Compared to the screenshot from within the article:

---

Update by a maintainer

Content change suggested to fix this issue

We need to make it clear which markdown content this syntax is supported in. When you edit an existing markdown file, the preview may not display the alert correctly. It would also be helpful to update the note about syntax to include a short example of what the deprecated syntax is (> **Note** from https://github.com/orgs/community/discussions/16925).

We can do this by editing the "Alerts" section of the basic writing article.

1. Update the note about the change in syntax to include a brief example of the old syntax (see https://github.com/orgs/community/discussions/16925 "Initial - 10 May 2022".
2. Update the introduction to mention that the syntax is supported in Issues, Pull requests, Discussions, Gists, Releases, and Markdown files.
3. Add a brief mention that when you edit an existing Markdown file, the preview may display the raw syntax, but that the alert will be displayed correctly when the changes are committed.

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

[cmwilson21]

@SerratedSharp Thanks for opening an issue and providing such great detail and screenshots!

I'll get this triaged for review! ⚡

[felicitymay]

Many thanks for raising this issue @SerratedSharp ✨

You're right. The documentation here could be clearer. Based on my local testing, the new alert syntax works in:

• Discussions
• Pull request bodies and comments
• Issue bodies and comments
• Markdown articles added to a repository⭐

⭐ It looks as if the new alert syntax does work in markdown files in a repository, but that the preview doesn't always show the new formatting (this happened to me too in a README file). I'll ask about this internally as I found this very confusing.

Once we know the full details of where the new syntax is supported and expected behavior in previews, I'll update this issue with the changes needed to clarify the article.

[github-actions]

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

[felicitymay]

Additionally I would say screenshots shouldn't be used as the rendering example. Just repeat the syntax itself without code ticks to demonstrate what it renders as-is since you are already in a github md file.

That's a great point and generally we do avoid using screenshots unless they are needed to clarify behavior. Screenshots reduce accessibility and increase maintenance needs of the docs. In this case, the only option is to use an image.

For reference, the docs.github.com website uses markdown files to store content, but they are not rendered using the same process as markdown files in GitHub.com. This allows us to include conditions to control what content is displayed to users of different versions of the product, and allowed us to add styling for notes long before this functionality was added to GitHub.

[felicitymay]

Hi. I heard back from a subject matter expert.

The new alert syntax is expected to work in:

• Discussions
• Pull request bodies and comments
• Issue bodies and comments
• Gists
• Releases
• Markdown articles in a repository

Known limitations:

• The syntax does not work for Wikis
• The preview when you edit an existing markdown file in a repository does not show the alerts. However, if you save the file the alerts should be displayed as expected.

[felicitymay]

I've updated the issue summary to contain suggested updates to the documentation to make the article clearer.

I'm going to add the Help wanted label to let everyone know we'd love them to fix this issue.