Proposal: markdown in descriptions #152

Closed
Floppy opened this Issue Nov 26, 2014 · 9 comments

Projects

None yet

6 participants

@Floppy
Floppy commented Nov 26, 2014

It would be nice to say that descriptions can be in Markdown format, allowing embedded links into human-readable descriptions. I guess it puts a burden on anyone rendering it though to run it through markdown, which I'd like to do, but perhaps not everyone. Any thoughts?

@rufuspollock
Contributor

Good thought - and I would incline to saying that by default processors should treat this as markdown (and those that treat it as plain text can do so - and you'll just get some formatting). However, this blithe statement may need some examination.

@Floppy
Floppy commented Nov 26, 2014

Yeah, I think it's probably fine - Markdown is designed to be human-readable, after all.

@samperd
samperd commented Nov 26, 2014

+1 Markdown in description

@paulfitz
Contributor
paulfitz commented Dec 2, 2014

Also +1 for specifying markdown. I'd suggest leaving the type of markdown allowed as unspecified. Hopefully the CommonMark standard will have fully materialized before anyone needs this nailed down.

@samperd
samperd commented Dec 2, 2014

Ditto, +1 markdown or plain text option for description.

@rufuspollock
Contributor

I guess my one concern is increased burden for consumers. Should consumers automatically assume that the description is markdown or do we need to an option to indicate it

I also wonder about explicitly introducing a "readme" field in datapackage.json - i use this a lot on http://data.okfn.org

@samperd
samperd commented Mar 9, 2015

I think an option for either case would be good. If there is a flag, then assume if the flag is missing then it is simple text, if the flag exists then check it for format type. What if all descriptions using markdown were prefixed with or something similar in a JSON way.

I am also encouraging the use of README in MD formats that are listed in the datapackage.json document.

@rufuspollock
Contributor

OK, i think we have consensus here on people assuming the description field is in markdown. We'll look to mention this in next iteration of the spec.

@pwalsh
Member
pwalsh commented Mar 7, 2016

@rgrp @danfowler an easy thing to introduce. @danfowler I suggest you make a PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment