Relative links in npm README markdown not functional


(John Gee) #1

What I Wanted to Do

Use a relative link in my package README to another markdown file. Note: the other markdown file is not included in the published npm package.

In my raw README I have

See [Proxy Server](docs/ for variables and advice for using a proxy server.

I assumed it would Just Work on both GitHub and npm, without thinking about the complications for npm hosting.

What Happened Instead

On npmjs the link does not work. The README page source has the relative link and has not been rewritten, and the page is not found:

<p>See <a href="docs/" rel="nofollow">Proxy Server</a> for variables and advice for using a proxy server.</p>

On GitHub the README page source has:

<p>See <a href="/JohnRGee/nvh/blob/master/docs/">Proxy Server</a> for variables and advice for using a proxy server.</p>

Reproduction Steps

Search for Proxy Server in the README link above. (Sorry, limited linked as a new user.)


When I did some digging into the problem I found that marky-markdown has support for rewriting relative links and images using the github package.repository if that is available. Sounds good! But this does not appear to be happening.

I checked that github-url-to-object used by marky-markdown could resolve the repository as specified in my package.json and it could.

I didn’t find the code that npm uses to invoke marky-markdown, so have not looked at what options are being pass in.

I found another person talking about various problems with linked images, and they have a sample package with lots of types of links. None of the relative images render on npmjs:

Platform Info

$ npm --versions
{ try: '1.0.0',
  npm: '5.6.0',
  ares: '1.10.1-DEV',
  cldr: '32.0',
  http_parser: '2.8.0',
  icu: '60.1',
  modules: '57',
  napi: '3',
  nghttp2: '1.32.0',
  node: '8.11.3',
  openssl: '1.0.2o',
  tz: '2017c',
  unicode: '10.0',
  uv: '1.19.1',
  v8: '6.2.414.54',
  zlib: '1.2.11' }
$ node -p process.platform

(John Gee) #2

I have opened an issue on marky-markdown.

(John Gee) #3

I saw links working in yargs using a technically still relative link starting with a slash, which I had not considered.

I changed docs/foo to /docs/foo. Thought it was working but nope, still not working for my project.

(John Gee) #4

Filling in some details of setups.

Working link on npmjs for yargs:

Broken link on npmjs for me:

(Katie Fenn) #5

Hello there! This was caused by a bug in the npm registry for scoped packages. This is why it affected some packages, but not others.

We deployed a patch to fix the issue today. Thank you for bearing with us while we fixed it! If you publish an update to your package, the links in your README should be fixed.

(John Gee) #6

Hurrah! Thanks for reply.

I published a fresh minor version and can confirm relative README links now working on for my scoped package.

(maple) #7

I encounter the same problem too, but my package is not scoped.

At the bottom of pixiv-client , the links doesn’t link to my github repo.

(Katie Fenn) #8

Hi there.

Links will become relative to GitHub when you link your package to your repository using the repository property of package.json.