package.json's readme entry is not displayed on the package pages

[obilodeau]

I have a "readme" entry in my project's package.json: https://github.com/asciidoctor/asciidoctor-reveal.js/blob/master/package.json#L52

However on npmjs it is not visible: https://www.npmjs.com/package/asciidoctor-reveal.js. It used to work (like in December 2016).

Doing a npm install asciidoctor-reveal.js and looking at the installed files, I see this in the package.json:

  "readme": "ERROR: No README data found!",

However, doing an npm pack and looking at the package.json in the tarball my custom "readme" is present.

Something is happening between my npm publish and the display on your website.

I'm not using a markdown file for my project's README. This is why I specify a string in my package.json.

[mojavelinux]

This is a pretty major issue. As a result, many READMEs from npmjs.com have just disappeared. The same is true for Asciidoctor.js. See https://www.npmjs.com/package/asciidoctor.js.

Of course, if npmjs.com would just support AsciiDoc, then at least those of us using the readme field in the package to inject a Markdown placeholder README wouldn't need to.

[bcoe]

@mojavelinux @obilodeau npm now renders the README.md directly from the tarball at publish time.

Unfortunately, there was a historical bug that resulted in the README not being included in a tarball at publish time (this has frequently been the root cause of a missing README) -- try updating to the newest version of npm, and publishing a patch release of your module, I think you will find this corrects the missing README.

[bcoe]

@mojavelinux @obilodeau I apologize, I understand your specific use-case now -- I didn't realize people were using the README field programmatically like this; at some point we started applying schema validation which populates this error message.

I will discuss this with folks Monday; I'm sure we can figure out a fix for this use case.

[ggrossetie]

@bcoe do not forget that some of us are using Markdown compatible syntax in a AsciiDoc README file. That's what we are doing on the Asciidoctor.js repository to avoid content duplication.

[ggrossetie]

And again if you need any help on #42 to support AsciiDoc README we will gladly help! 😄😊

[mojavelinux]

The root problem here is that npm assumes the README is in Markdown format. Version control and packaging systems across the board support README files in different markup languages. That list includes GitHub, GitLab, libraries.io and rubydoc.info. It would be really nice if the npm website would do the same. Asciidoctor.js, which is available on npm, can be used to convert AsciiDoc to HTML.

The way we've been working around lack of support for AsciiDoc is to include in the package we publish to npm a simplified Markdown version of the README in the package.json readme field. I can't remember exactly why we started using the readme field in package.json instead of using a README.md file. I think the reason was because the npm site was using the first README file in the package, which was README.adoc, and trying to render it as Markdown. So there's just a lot of confusion in this area.

I don't really want to use the readme field in package.json. What I'm looking for is one of the following:

• pick the README.md file to render if there is more than one README file in the package
• render README.adoc, if present, using an AsciiDoc converter (Asciidoctor.js)

I prefer the second, of course. It doesn't seem completely reasonable to implement. And there are plenty of people to help if you need it.

[bcoe]

@mojavelinux hey, we're just doing our weekly ticket triage.

Hear you load and clear, supporting a wider variety of renderers -- and getting our rendering as close as possible to GitHub's -- is something we care about.

We will make an effort to keep this ticket updated as we move forward with this work, and I will let you know any open-source tools we're considering using, so that we can keep the community involved.

[ggrossetie]

That's a excellent news! Thanks @bcoe

[mojavelinux]

Excellent news! Thanks for the update. I think you'll be hard pressed to find a more willing group to help, so please don't hesitate to reach for it.

[mojavelinux]

I have employed a workaround for this problem using prepublishOnly and postpublish scripts.

See https://github.com/opendevise/bespoke-overview/blob/5f0959c743de0f3904fceb0b59a790faab1bb5a6/package.json#L22-L23