Use of markdown in snap metadata (summary / description)

snapd
#1

Currently the package summary/description is done using plain text, e.g.

Hiri is an email client for Office 365 / Exchange / outlook.com / msn.com / hotmail.com / live.com. Basically all the Microsoft Email services :)
Hiri has full email, calendar and tasks functionality.

Hiri is a subscription service but you do have 14 days free to try it to see if you like it. 
  
Visit www.hiri.com for more information.

Perhaps we could consider using markdown to allow nicer formatted text (e.g. bold, italics, lists, links, images etc). Markdown seems to be quite widely used (e.g. github).

Some issues if we do use markdown:

  • Are we worried if we use hyperlinks that could be used to trick users? Note that a lot of software already makes valid URLs clickable (e.g. gnome-terminal).
  • For backwards compatibility and for developers that don’t want to use it we probably should have a flag description_format or similar to opt-in to using markdown.
  • Use of images could be used to track people browsing the store - is that a problem?
  • For clients that don’t / can’t display formatted text (e.g. command line) do we need an easy method of stripping the markdown out?
2 Likes
Feature Requestion: Markdown support in Snap Store
#2

I guess the first question to ask is how much control do we want to give developers over how their app is presented in the store. We want to give them enough control to describe their app well, but we also want some level of consistency so that we can present the information in a useful way in multiple contexts (command line, graphical package manager, web, etc).

Looking at Android, it seems that it has support for bold text and linkifies things that look like domain names or urls. Apps seem to use various unicode characters to simulate bulleted lists. Images are restricted to the app icon, and a set of screenshots and videos: all of which are displayed in the same location for each listing. The iTunes store seems similar, although I haven’t really looked at it in detail.

As far as links go, it would be good if we could avoid things like the following:

Visit [www.trusted.com](http://www.malware.com) for more information.

So maybe we don’t want full markdown-style links?

#3

And as a followup, this post details some of the supported text formatting for the Google Play store:

https://stackoverflow.com/questions/11071127/google-play-app-description-formatting

It sounds like it isn’t properly documented, and is handled inconsistently between web and the app. If we do support some form of rich text, it would be good to document exactly what is allowed so that app developers don’t have to guess.

#4

Having some form of basic formatting sounds reasonable, but I’m not sure about how far we want to go with it.

The problem isn’t malware links. Those can happen anyway via shorteners. My actual concern would be what sort of practice we’re encouraging by having a full markdown description. Do we really want code examples, section headers, long URLs, etc? Gut feeling is that this will decrease the quality of descriptions instead of improving it.

Lists is pretty much the only thing I can think of that would be really nice to have a proper convention for. Is there anything else we’d want?

#5

A better list:

  • Lists (* Foo)
  • Italics (_foo_)
  • Bold (**foo**)
  • Paragraph merging (consecutive lines are joined)
  • Auto-linking of literal URLs

What else? Will update the list as we go.

1 Like
#6

I think restricting to a subset of Markdown is likely to cause problems. It will mean writing custom parsers/renderers in all the places that need to show this information.

By allowing Markdown and exposing developers to how it will look in snap info and on the store front we can allow developers to self-censor if they find that the description gets out of hand with long explanations.

#7

No it doesn’t. It only requires constrictors at the store and in snapcraft. The regular Markdown parsers can certainly be used, but a sanitizer is definitely needed.

#8

At the New York sprint (July 2017) it was decided to use CommonMark in Snap descriptions:

1 Like
#9

@robert.ancell This thread we’re talking in happened after that. See details above for rationale on suggested changes.

We’re still discussing details, though, and there are multiple proposals in flight right now. Let’s catch up before any of these is final.

#10

June 2017 was London, and the New York sprint was in September 2017, not July. :wink:

#11

Following a conversation in Salt Lake City and catching up on this thread. We have planned limiting Markdown in a given Snap description on snapcraft.io this cycle.

Any comments from anyone if we go with the following list suggested in an earlier post by @niemeyer?

  • Lists (* Foo)
  • Italics (_foo_)
  • Bold (**foo**)
  • Paragraph merging (consecutive lines are joined)
  • Literal URLs auto-link
#12

What about allowing headings?

For consistency with document hierarchies, I expect that the app name will be the “top level document heading” when displaying the information, so headings in the snapcraft.yaml should be limited to second-level and below.

#13

At a snapcraft.io level, we ask publishers for Summary and Description and we can easily include some information for publishers about the allowed Markdown tags. Snap name is already the top level document heading on a snap public page in snapcraft.io.

If we allow users to include headings within the description, that means the layout can easily get compromised from a design standpoint. I am not 100% sure if we would like to explore this. Allowing headings will mean that we need to handle headings within the layout gracefully. This could feel strange for a publisher that they need to adapt to some rules we define on the layout for one specific area whereas I can sense the origin of this topic is to provide a consistent presentation of content across the many platforms a user can interact with a given snap.

#14

Links would be both more elegant, and more accessible, if publishers could give them link text. Why would we link raw URLs, but not allow normal links?

(I’d actually prefer the opposite — don’t link raw URLs, to encourage publishers to make proper links instead.)

#15

This makes sense as it can give publishers the ability to shorten URLs and/or provide more relevant content within the description of a given snap.

This cycle we discussed adding the ability to report a Snap in the Snap Store. Including a malicious link should be one of the reasons for anyone to report. We will share more details about this piece of work once we start defining it.

So what about the following recommended Markdown subset?

  • Lists (* Foo)
  • Italics (_foo_)
  • Bold (**foo**)
  • Paragraph merging (consecutive lines are joined)
  • Literal URLs auto-link https://foo.bar
  • URLs with title [title for the link](https://foo.bar)
1 Like
#16

There are some cases where publishers use the description field to refer to installation or usage instructions for a given snap (i.e. htop, ). Perhaps something to include is the ability to format code within a description field:

  • Code (text blocks inside ` or ``` pairs)
  • Lists (* Foo)
  • Italics (_foo_)
  • Bold (**foo**)
  • Paragraph merging (consecutive lines are joined)
  • Literal URLs auto-link https://foo.bar
  • URLs with title [title for the link](https://foo.bar)
3 Likes
#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