126
submitted 2 months ago by juliette@pawb.social to c/technology@lemmy.ml
you are viewing a single comment's thread
view the rest of the comments
[-] savedbythezsh@sh.itjust.works 1 points 2 months ago

Do you mean admonitions? E.g. info, warning, etc? There's precedent for that in commonly-used open source implementations, e.g. obsidian.md (which uses the same syntax, and started before). What semantics does it break? It's designed to read well in plaintext and render nicely even if used in a renderer that doesn't support admonitions, e.g.

[!NOTE] Information the user should notice even if skimming.

As opposed to other common markdownish implementations that use nonsensical plaintext which renders poorly in alternative renderers. Here's a discussion on the topic in the CommonMark forums.

[-] toastal@lemmy.ml 1 points 2 months ago

Read the Markdown spec where it says the > denotes a blockquote. There isn’t room to overload it without breaking that into something not backwards compatible (such as CommonmsMark which will follow the spec & render a blockquote—which, according to the HTML spec, must be text quoting a source). Just because some of the bigger players—namely the proprietary forks, Obsidian & MS GitHub—doesn’t mean it’s not breaking with the original spec. Go ahead & do it, but don’t lie & say it is Markdown or Markdown-compatible. Instead these entities try to push & sway everyone to adopt their syntax rather than working with say CommonMark with RFCs.

CommonMark has the ::: block syntax, but folks using this are relying on stringly-typed, not-well-defined options when they do ::: note as it just becomes a CSS class where anyone could style it.

As callouts are such an everpresent construct in technical writing, documentation, & so on, what you need is first-class support. Docbook as an output has first-class support, but sadly W3 shot down the last attempt at an element proposal (but can be properly by manually constructed with role=note & aria-labelledby). reStructuredText & AsciiDoc are both lightweight markup syntaxes that support first-class callouts & other elements (definition lists, summary/details, figures, etc.) as well as having first-class metadata (like basically every other creative work format for images, audio, documents).

All of this is to say what Microsoft is doing is no longer Markdown & only they hold the keys to the spec (you can complain in their forums, but you can’t submit an RFC or pull request). But also, Markdown / CommonMark are honestly ill-suited for the task of technical writing since it doesn’t support basic features for that task (embedding HTML defeats the purpose & portability)—and instead we have a lot of ad-hoc hacks & bad HTML output due to choosing the wrong tool for the job.

this post was submitted on 11 Apr 2024
126 points (79.2% liked)

Technology

33591 readers
443 users here now

This is the official technology community of Lemmy.ml for all news related to creation and use of technology, and to facilitate civil, meaningful discussion around it.


Ask in DM before posting product reviews or ads. All such posts otherwise are subject to removal.


Rules:

1: All Lemmy rules apply

2: Do not post low effort posts

3: NEVER post naziped*gore stuff

4: Always post article URLs or their archived version URLs as sources, NOT screenshots. Help the blind users.

5: personal rants of Big Tech CEOs like Elon Musk are unwelcome (does not include posts about their companies affecting wide range of people)

6: no advertisement posts unless verified as legitimate and non-exploitative/non-consumerist

7: crypto related posts, unless essential, are disallowed

founded 5 years ago
MODERATORS