Document Examples of using GitHub Alerts (Obsidian Callouts)

[vburzynski]

• Adds a template example of using the GitHub Alert or Obsidian Callout Syntax
• Documents the discrepancies between the two implementations

[JoelQ]

The PR descriptions explains the what, but I'd love to see a bit more about the why. Can you explain why you think this is needed as part of the guides repo? Are you trying to create some kind of style guide for this repo? For all thoughtbot work on GitHub?

If this is more of a how-to article, maybe it's a better fit for something like the blog?

[JoelQ]

This file should not be committed

[vburzynski]

Doh, I always expect those to be git ignore. I'll add that

[vburzynski]

@JoelQ Oh, good point. I didn't fully share all my thinking. I'm now realizing I didn't have a fully formed one yet.

My process on Friday largely went like this:

• audit all the Markdown pages
  • to get a sense of the page types we have throughout all of the guides
  • wanted to get a sense of what patterns we have in play
  • also what divergences and differences there are between pages that could be normalized to make the guides more cohesive.
  • this was also a precursor to identifying patterns to present as a proposal for standardizing how we format and layout pages. but this is getting off-topic from this pull-request...
• I noticed that a number of pages use <details> which is non-standard
  • many Markdown linters disallow HTML inside of markdown
  • when many Markdown parsers read HTML, they don't parse markdown embedded inside an HTML tag
  • GitHub is an outlier here
  • The GitHub <details> syntax is not documented in the GitHub Flavored Markdown (GFM) Spec (https://github.github.com/gfm/) and it's not part of CommonMark. It's specific to only GitHub's implementation. (Though visual studio code seems to render it so it's possible to have a JS parser read it).
  • Markdown syntax inside HTML elements is not consistently implemented
    • the original syntax from John Gruber disallows it
    • GFM and CommonMark seem to allow markdown inside HTML.
    • the more common JS markdown parsers like remark/rehype, markdown-it, marked for example don't parse markdown embedded inside of HTML
  • So I was curious about finding an alternative that is more common amongst the flavors of Markdown
• I thought of Obsidian Callouts and remembered Github had a nearly identical Alerts syntax
• I was hoping that the collapsible callouts from obsidian would be compatible with Github, they are not
• In this PR I explored what syntax was compatible between the two

The main thing is that I think the Alert/Callout syntax would:

• exhibit better support by a wider selection of markdown parsers
• be useful for adding more semantics and different formatting to "detail" sections.