Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consider using markdown containers instead of blockquotes #50

Open
apyrgio opened this issue Sep 23, 2024 · 1 comment
Open

Consider using markdown containers instead of blockquotes #50

apyrgio opened this issue Sep 23, 2024 · 1 comment

Comments

@apyrgio
Copy link
Contributor

apyrgio commented Sep 23, 2024

@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: #48 (comment))

@harrislapiroff
Copy link
Contributor

harrislapiroff commented Sep 23, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants