New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal: markdown in descriptions #152

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

Comments

Projects
None yet
7 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

This comment has been minimized.

Contributor

rufuspollock commented Nov 26, 2014

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

This comment has been minimized.

Floppy commented Nov 26, 2014

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

@samperd

This comment has been minimized.

samperd commented Nov 26, 2014

+1 Markdown in description

@paulfitz

This comment has been minimized.

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

This comment has been minimized.

samperd commented Dec 2, 2014

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

@rufuspollock

This comment has been minimized.

Contributor

rufuspollock commented Dec 29, 2014

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

This comment has been minimized.

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

This comment has been minimized.

Contributor

rufuspollock commented Sep 24, 2015

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

This comment has been minimized.

Member

pwalsh commented Mar 7, 2016

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

@danfowler

This comment has been minimized.

Contributor

danfowler commented Jul 4, 2017

@paulfitz: 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.

Should the lack of a preferred markdown type be made more explicit?

e.g.:

The description MUST be Markdown formatted -- this also allows for simple plain text as plain text is itself valid Markdown. The specific version (or "flavor") of Markdown is unspecified.

See: https://discuss.okfn.org/t/readme-md-practice-for-data-packages/5555/6?u=danfowler

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