Are full absolute paths in links inside markdown files of GitHub repositories inevitable if we want to publish the package to npm?

user_4818123 0
Viewed 189

Assume that we have the GitHub repository with below 2 Markdown files:

  • README.md
  • Documentation/SampleDocumentationPage.md

From the README.md we can refer to SampleDocumentationPage by relative path or shortened absolute path:

See [sample documentation page](Documentation/SampleDocumentationPage.md)

If we publish the package to NPM, the README.md will displaying on package's main page which has below URL.

https://www.npmjs.com/package/$SCOPE_NAME$/$PACKAGE_ID$

Will link to SampleDocumentationPage.md in README.md work? I suppose no, because correct absolute path of SampleDocumentationPage.md is

https://github.com/$USER_NAME$/$REPOSITORY_NAME$/blob/master/Documentation/SampleDocumentationPage.md

while in relation to npm the computed URL of SampleDocumentationPage.md is

https://www.npmjs.com/package/$SCOPE_NAME$/$PACKAGE_ID$/Documentation/SampleDocumentationPage.md

Something possible to do with it except the usage of absolute paths only? The absolute paths in Markdown could be very long like:

<dl>

  <dt><a href="https://github.com/TokugawaTakeshi/Yamato-Daiwa-ES-Extensions/blob/master/CoreLibrary/Package/Documentation/Arrays/getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne/getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne.md">getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne</a></dt>
  <dd>Returns the element of specified array matching with the predicate if such element is exactly one, otherwise error will be thrown or null will be returned (depending on dedicated option's value).</dd>

  <dt><a href="https://github.com/TokugawaTakeshi/Yamato-Daiwa-ES-Extensions/blob/master/CoreLibrary/Package/Documentation/Arrays/getLastElementOfNonEmptyArray/getLastElementOfNonEmptyArray.md">getLastElementOfNonEmptyArray</a></dt>
  <dd>Returns the last element of array, herewith <b>UnexpectedEventError</b> will be thrown if target array is empty.</dd>

</dl>
npm markdown github
2 Answers

Please check these:

Relative link from readme.md to another file in package, rendered in npmjs

Here it is reported as npm issue and added to backlog

Relative links in markdown are broken

You can find some solutions here, try and see which works for you.

Relative links in markdown README not being rewritten on npmjs.org

Try marky-markdown is a markdown parser, written in NodeJS, that aims for parity with GitHub-style markdown. It is built on top of markdown-it, a CommonMark markdown parser.

remark-relative-links: Rewrites absolute URLs to relative ones with remark

user_191216230

The simple answer is no, you are not restricted to absolute links! I'm not sure at what point it happens, but I believe NPM rewrites your relative links to absolute links to your repository, if the repository info is supplied in the package.json.

I made an example package so you can see it in action:

user_110205150
Related