freedomofpress / dangerzone.rocks

Contents of the dangerzone.rocks website
5 stars 2 forks source link

Consider using markdown containers instead of blockquotes #50

Open apyrgio opened 1 week ago

apyrgio commented 1 week ago

@harrislapiroff suggested using Markdown containers, instead of blockquotes, via the markdown-it-container project. Let's weigh the pros and cons, and go with a solution for our future projects.

_(original discussion here: https://github.com/freedomofpress/dangerzone.rocks/pull/48#discussion_r1767248174)_

harrislapiroff commented 1 week ago

I'll elaborate a little on my discomfort with using blockquotes here:

  1. Semantically blockquote just doesn't mean what we're using it for in this case. A blockquote is a bit of text that is set off from a main text to indicate that it is quoting another source. This is primarily a theoretical concern, but it can become practical in ways that are hard to predict, for example: How do screen readers format block quotes when they read them aloud to users? How does a browser's "reader view" format them? I don't actually know offhand the answer to these questions and in both those cases they're systems that are designed knowing web authors often abuse the semantics of the web, so they probably do something acceptable, but they can probably do even better if we use elements correctly.
  2. If someday in the future we find we do want to use a blockquote for the intended purpose of quoting another text—as our blog currently is—we'll have to use the same design we're currently using for informational notes. Again, this is probably acceptable—I imagine it will be clear from context whether a note is informational or whether we're quoting someone, but I don't think it's ideal. It would be better to have separate designs for the different meanings.

In general my rule of portability for markdown extensions is not so much "will any markdown system I try to use in the future be able to render this exactly as my current one does?"—which is a pretty limiting rule since Markdown at its core was really only designed to capture the sort of rich formatting one might use in the text of an email, not documentation or blog posts—but "Will any human looking at this in the future understand what the intention was of this syntax?" Extensions can always be recreated if the intention is understood and if the future escape hatch is just rendering something as plain text, that's often fine as well.

I do prefer markdown-it-container for my own projects, but I think there's a good argument for using the GitHub-flavored admonition syntax instead since GitHub-flavored Markdown is very common. This markdown-it plugin implements that.