Use of markdown in snap metadata (summary / description)

snapd
40

you can be technical enough for a lot of things, and yet not want to see ugly…

However, there are several developers that have already started using this, and I can see how it could be inconvenient and a hassle (and losing cred) to go back to them and say “akshully, herp derp”. On the other hand, I hope you appreciate how ugly descriptions have become when unrendered thanks to this work.

While I’ve gone on about ```s being ugly, the real problem is with links making paragraphs unreadable. I think if we absolutely need titled links, as opposed to autolinks, and the feedback I’ve heard is that we do (but I don’t get to decide this), then I propose we support shortcut reference links instead:

Rather than

ElectronMail is an [Electron](https://electronjs.org)-based unofficial
desktop client for [ProtonMail](https://protonmail.com/) and
[Tutanota](https://tutanota.com/) end-to-end encrypted email providers. The
app aims to provide enhanced desktop user experience enabling features that
are not supported by the official in-browser web clients.  It is written in
[TypeScript](http://www.typescriptlang.org) and uses
[Angular](https://angular.io).

it would be

ElectronMail is an [Electron]-based unofficial desktop client for [ProtonMail]
and [Tutanota] end-to-end encrypted email providers. The app aims to provide
enhanced desktop user experience enabling features that are not supported by
the official in-browser web clients.  It is written in [TypeScript] and uses
[Angular].

[Electron]: https://electronjs.org
[ProtonMail]: https://protonmail.com/
[Tutanota]: https://tutanota.com/
[TypeScript]: http://www.typescriptlang.org
[Angular]: https://angular.io

As you can see, it degrades a lot better.

@niemeyer would you agree to have indented blocks for literals, and shortcut reference links, supported in the web (and eventually our GUI clients)?

If we do agree on this, we could

  • make the web editor stop talking about ``` pairs, and [foo](bar) links, and instead talks about indented blocks and shortcut reference links.
  • continue to support ``` blocks and [foo](bar) links on the web, for rendering only
  • reach out to people using the old features, explain that because they render so poorly on the terminal and offer assistance
  • in a couple of months, drop support for the old

WDYT?

1 Like