Add GitHub style markdown alerts

[kaste]

Fixes #296

Also adds header anchors for deep linking into the readme.

[kaste]

That seems to work okay, and looks okay too.

@braver for a quick look maybe.

• the links (only in the readme) now have underlines. I think that is actually important but it is on a separate commit so easy to undo.
• in theory, different note types(?) could have different colors; I didn't do that here; I also had no packages at hand where this is used heavily.
• The heading anchors are traditional links but don't have text in it and no aria-* labels; so that's already not so super good; you can tab them but the outline is ugly 🤷

Nothing that can't be improved later as well.

[braver]

I'd prefer https://primer.style/octicons/icon/link-16/, or perhaps ⌘ ("place of interest") or just →..., but the link icon would be ideal.

[kaste]

The ⌘ totally is a Mac thing. It is like a trademark.

[michaelblyons]

The ⌘ totally is a Mac thing. It is like a trademark.

I also have that sense.

• If you want ASCII, # is decent.
• ¶ might imply that any paragraph can be linked, not just headings.
• Or there's any number of fun symbols in Unicode like Kaste already had.
  • "It's a bookmark, and it's here:" ⮱

[kaste]

[kaste]

I do like the simple #.

[braver]

This kind of goes back to our earlier discussion about color contrast: it's the wrong kind of orange. It's not our "brand" color. And because we already set the expectation with a certain kind of orange everywhere else, these links are now obviously different somehow. My first reaction was that maybe they were links I already visited ... it looks wrong to my eye.

I don't mind the underlines by the way, more links should have underlines for various reasons.

[braver]

I do like the darker orange for the notes and IMO doesn't conflict with the links being in the "normal" orange (since they're just really different and unrelated things).

[braver]

I also don't mind our --blue-3 here:

[kaste]

Maybe we just stick to elegant and readable. E.g.

I picked the note color rather quickly, just to have a contrast to the black and white text.

[kaste]

Then we have around the corner ways to colorize,

[braver]

The heading anchors are traditional links but don't have text in it and no aria-* labels; so that's already not so super good; you can tab them but the outline is ugly 🤷

Since the icon is revealed on focus, perhaps the outline is not needed? Alternatively, looks better if you make the element square and center the icon:

(edit: better with the outlines!)

diff --git a/static/style/readme.css b/static/style/readme.css
index 70749ce4..343162c3 100644
--- a/static/style/readme.css
+++ b/static/style/readme.css
@@ -131,13 +131,22 @@
   .markdown-anchor {
     opacity: 0;
     position: absolute;
-    left: -1em;
-    bottom: 0.1em;
+    left: -1.2em;
+    bottom: 0.3em;
     color: var(--foreground-3);
-    width: 1em;
+    width: .9em;
+    height: .9em;
+    line-height: 1;
+    justify-content: center;
+    align-items: center;
+    display: flex;
+
     text-decoration: none;
-  }
-  .markdown-anchor:after {
-    content: "⎆";
+
+    &::after {
+      font-size: .66em;
+      content: "⌘";
+      display: block;
+    }
   }
 }

By the way, the anchors need a label (for accessibility) so perhaps add aria-labelledby pointing to the parent's id.

[braver]

Note that you can probably just nest :root[data-theme='dark'] in the previous selector, instead of repeating all the alerts styles here. Or of course introduce a new color variable in colors.css and set up the dark variant there.

[braver]

in theory, different note types(?) could have different colors

Yeah, I don't see a real need there as long as we avoid obvious signal colors (red/green). It's clear enough to call attention to itself by just existing, I don't think need to make it any more complicated than that. I hardly ever see them in the wild anyway.