All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

I have read the CLA Document and I hereby sign the CLA

From my work on a different branch, it doesn't look like Coder.com supports the [!NOTE] syntax at all, i.e. I have

> [!NOTE]
> Despite the browser showing an insecure connection without `HTTPS`, the underlying tunnel is encrypted with WireGuard in the same fashion as other Coder workspace connections (e.g. `coder port-forward`).

which is rendering as:

Works on GitHub though

Thanks for the tip @ethanndickson. Updated the PR so that callouts found in documentation located in the docs/ directory use HTML blockquotes instead. I don't think the documentation located in the examples/templates/ directory are rendered on Coder.com, so these are still using the GitHub callout syntax.

@ethanndickson The specific blockquote syntax is actually part of something that GitHub themselves came up – Github-Flavored Markdown. This is the main spec doc, and this is the cheatsheet where they describe how the comments are supposed to work.

I just added support for these to the Coder Registry the other week. We already use them extensively throughout our projects (including a lot of Coder Modules and Templates), so my gut feeling is that it'd be a mistake to switch away from them. So realistically, there's a good chance that we want to update the docs to make sure they render correctly on GitHub, but then also update how we render them, across both the private Coder.com repo, and the public /offlinedocs directory in this repo

@matifali Does that sound right to you? I know we have an issue about adding GFM to Coder.com that's from 2023, but I wasn't sure if it's still something we're actively trying to support. We already have a custom system partly in place because we have code that processes HTML blockquotes that use the admonition class, but my worries are:

1. This is a custom system that isn't really documented
2. Even though GFM is also a custom system, it has much better adoption, and will look more immediately familiar to other open-source devs
3. The HTML semantics from using the admonition class are wrong. GFM alerts look like blockquotes, but the HTML that GitHub translates them into is actually plain paragraph text. Adding quote semantics to non-quoted text definitely feels like a bug
4. All READMEs that currently use the admonition class render properly in the Coder docs, but don't render properly in GitHub itself. Ideally I'd make it so that there's one way of making alerts, and it works everywhere

@lucasmelin Sorry for the confusion – you did absolutely nothing wrong, especially with a lot of this still being undocumented. I'd say to sit back until Atif responds, but you may end up needing to swap back to your previous commit

@Parkreiner, I would be all in for supporting GFM over our custom callouts. The benefit is consistency on our side and GitHub.

If its easy to support, I would love to see us supporting GFM on Coder docs.

@lucasmelin I went ahead and bumped the ticket for updating Coder.com to start rendering GFM alerts properly. My team is still figuring out some sprint priorities, but depending on how things go, I might be able to tackle that issue later this week

In the meantime, could you swap back to the GFM alert syntax? I think there's enough consensus at Coder that we want to treat GFM as the standard, and treat any cases where we don't conform to it as a bug

Switched back to GFM note callouts for the documentation located in the docs/ directory in 225c08b.

Going to be merging this in for you right now. One of other engineers (@aqandrew) was kind enough to open up a PR for updating the Coder.com site to parse GFM properly

The Docs site should hopefully be all fixed up in the next few hours

@EdwardAngert, can you please do a follow-up PR to update all remaining callouts to GFM alerts?
Thanks <3.

Thank you for the PR @lucasmelin! coder.com/docs now renders these GFM alerts correctly.

😮 ❣️

thanks y'all!

I'm starting a PR to find all the other callouts

for me: GitHub docs: alerts