Use of markdown in snap metadata (summary / description)

snapd
17

This is now live on snapcraft.io. Announcement post coming soon!

3 Likes
19

Is the markdown format documented anywhere? I’m starting on implementing in GNOME Software.

1 Like
20

See @pheurton’s post above ^

21

Do we support escaping characters using backslashes?

2 Likes
22

Do we support nesting i.e. bold and italic? Bold/italic links?

2 Likes
23

Can we please remove the support for triple-backticks and titled URLs, until we’ve been able to agree on them?

They both look very ugly on the terminal unless parsed and rendered in some way (links might not have a good way of dealing with them across all supported terminals, so they’d always look ugly).

Gustavo’s original proposal had the enormous advantage of not needing any work for things to look alright on the terminal. We could opportunistically add support for things, but didn’t have to. With the latest additions, unless we do something, it’s going to look ugly.

Please, let’s drop support for things we haven’t agreed to, until we’ve been able to discuss it more?

Thank you.

2 Likes
24

Yes, the original set was very much based on the fact it was properly formatted in the terminal, and it seems to have been lost in translation above without further agreement.

@pheurton @Lukewh Can we please fix that ASAP?

1 Like
25

Sure, we’ll get it updated and released ASAP :+1:

26

One thing, before it’s released, is there an easy way to alert / update descriptions that are already using the features we’re disabling? Maybe advocacy or store teams can help?

1 Like
27

Yeah we’ll be in conversation with them, as we were when we first released the subset

28

Thank you, good to know.

29

@chipaca would it be acceptable to just strip ``` when displayed in the terminal? Code blocks don’t need special formatting in the terminal, but they are particularly helpful in the web description:

1 Like
30

not really :frowning: (I mean, obviously yes, but I think it’s a bad idea, and it’d still take a few months to make it ‘out there’ during which people will be looking at nasty ```s)

However, I’d have 0 issues with us supporting code blocks via indentation.

31

Ah, okay. Can you elaborate on why it’s a bad idea to strip these out, and why it would take months to get that ‘out there’?

32

because it wouldn’t be markdown, and it wouldn’t be plain text, but something in between. We’d have to update documentation to say “it’s going to be markdown but just now we’re just stripping ```s”, which is rather lame.

And because moving to markdown wasn’t resourced, there is no timetable for when the actual thing is going to happen, so it’d easily be 2020+ before it’s done.

if I landed it in master today, it’d be in 2.39 which I don’t expect to be in stable for a couple of months.

33

@niemeyer @chipaca @evan

I know that we just discussed removing support for code blocks and titled URLs but based on the previous replies. Would it be acceptable to…

  • Remove support of titled-URLs [title](link)?
  • Remove support of ``` for code blocks?
  • Remove support of (`) for code in the middle of a sentence?
  • Support code blocks using indentation instead?

So going back to the original list, we will have:

  • Lists (* Foo)
  • Italics (_foo_)
  • Bold (**foo**)
  • Paragraph merging (consecutive lines are joined)
  • Auto-linking of literal URLs
  • Code block by indentation (4 spaces)

Let me know your thoughts.

1 Like
34

From a terminal POV, single `s are ok.

35

Why is snapd CLI attempting to render anything in the description? I humbly suggest that just showing the raw not-really-markdown is just fine.

I stand by my comment above in Use of markdown in snap metadata (summary / description) - we simply need to show publishers how it will look, and let them make their own decisions about what to include or not include.

4 Likes
36

the snapd CLI is not trying to render anything for the description. The last requested changes have been about making sure that that description looks alright unrendered, while still supporting what more rendery frontends need to not scare away their users. That had been the intent all along, but it got a little lost along the way.

I might, at some point, look into rendering what’s possible to render on the terminal. Because it’s fun, and it involves widths of things on the terminal :slight_smile: but that’s a 20% / weekends kind of thing, that I don’t expect to come to fruition this year.

1 Like
37

I still think this is problematic. We have snaps in the Store which make good use [1, 2] of titled URLs. We have snaps which are using ``` code blocks to give usage instructions today [1, 2].

Apologies John, but I find this confusing. Can you please explain how single ` is okay, but ``` is not?

1 Like