Support for more README formats

[obilodeau]

It would be nice if npmjs.com supported other markup formats than markdown.

Our project uses AsciiDoc and the npmjs.com entry is ugly: https://www.npmjs.com/package/asciidoctor-reveal.js (as of October 3rd 2016).

We are going to work around it by using the packages.json "readme" field so this is not a high priority thing for us.

I understand why you supported markdown first for npm (most bang for the buck). That said, leaving all the others (including plaintext) behind might hurt you in the end. As an inspiration you can look at GitHub's README parser supports several markups. AsciiDoc, Textile, ReStructured Text, RDoc, Mediawiki, etc. Full list here: https://github.com/github/markup#markups

See npm/npm#14159

Cheers!

[ashleygwilliams]

relevant: https://github.com/github/markup#markups

[aredridel]

Thanks for the suggestion! We've passed this on to our product team.

[whatl3y]

+1

[eshepelyuk]

Many thumbs up for Asciidoctor support

[jirutka]

It’s a shame that npmjs.com still does not support anything but Markdown. 👎

@obilodeau How did you managed to put that text “Please see the project home page for the README …” on asciidoctor-reveal.js npm page? I don’t see any “readme field” in your package.json.

[obilodeau]

I don’t see any “readme field” in your package.json.

It's because it no longer works. See #136.

The trick I used is to add a README.md in addition to our README.adoc: https://github.com/asciidoctor/asciidoctor-reveal.js/blob/master/README.md

I haven't discovered this, this guy did. Not sure what GitHub's heuristic is to know which to display but my guess is that they display the largest one.

@mojavelinux found another way that you might prefer.

[mojavelinux]

I don’t see any “readme field” in your package.json.

It's because it no longer works.

Exactly. We've since abandoned that workaround.

The trick I used is to add a README.md in addition to our README.adoc

I've found this approach to be very unreliable. Sometimes it prefers the README.adoc over the README.md, which gets us back to the initial problem of a blank README on npmjs.com.

I actually think there are two problems here. The first problem is lack of support for README.adoc on npmjs.com. The other problem is that fact that you can't specify which file to use as the README when packaging. I really dislike this guessing logic.

The workaround I came up with is still very tenuous. It assumes a lot about the order of operations when packaging. And I've found that when I use lerna or yarn to publish, I have to use a different sequence. It makes publishing packages way more complicated than it has to be because we can't rely on most of the publishing tools available (or can't use them without applying workarounds that are likely to break).

In the most recent package I published, I ended up just reverting to a bash script because I got tired of wasting time trying to conjure up a solution. See https://gitlab.com/antora/expand-path-helper/blob/master/npm/release.sh.

Can we please start discussing real solutions? I'm willing to help in anyway that I can.

[mojavelinux]

I want to point out that there is an AsciiDoc processor available for Node. It's not a matter of finding the software. It's just a matter of deciding when it should be called.

https://yarnpkg.com/en/package/asciidoctor.js