molomby / package-doc-url-testing

Probing the intersection of monorepo packages, Markdown, Github and doc URLs

Package Doc URL Testing Monorepo

Probing the intersection of monorepo packages, Markdown, Github and doc URLs.

Huh?

When Markdown files are added to a monorepo, the links need to make sense on the local fs, to Github and when the packages are published to NPM. Getting this all working at the same time isn't trivial.

This repo sets up a super-simple package with links using different URL formulations. Look at the code, then see what the package looks like when it's published on NPM.

TL;DR

Configure your package.json correctly

• Your repository.url should point to the root of your repo
• Use the repository.directory prop to specify the path to the package

Eg..

"repository": {
  "type" : "git",
  "url" : "https://github.com/molomby/package-doc-url-testing.git",
  "directory": "packages/not-a-real-package"
}

When linking to other docs, use URLs relative to the repo root

Ie. starting with a slash: /. These work reliably on GitHub and NPM.

Related Info

• The @molomby/not-a-real-package package on NPM
• How we handle doc links in the Keystone Monorepo
• Also the Keystone Style Guile on Links
• NPM package.json repo section docs

Test Links

You're currently reading the Repo README, available at:

• Relative to this file
• Relative to the repo root

We have a package you should check out at either:

• Relative to this file
• Relative to the repo root

See also the the other doc at:

• Relative to this file
• Relative to the repo root