How to specify different readme files for github and npm

Question

Both use the README.md as the description when you publish. A common practice is to use a single shared file.

But what if I need to have the different Readme and still publish it from a single local repo with no manual editing/replacement

PS

I tried to use "readme": "npm-readme.md" in package.json but it displays a value of this field, not the content of а file

Answer 1

For some reason zavr's answer (using README and README.md) didn't work when I tried it (probably the logic used by NPM has changed). But what did work is putting the GitHub README into .github directory (this is allowed according to their docs), and using the root README.md as the version for NPM along the lines of

<!-- README for NPM; the one for GitHub is in .github directory. -->

<badges>

<a brief description>

Please refer to the [GitHub README](https://github.com/<your repo>#readme) for full documentation.

Luckily, for GitHub .github/README.md seems to take priority over README.md.

Update 2021-02-06: a quick note about best practice. NPM wouldn't let you update the readme without bumping the package version, and in reality you often need to make updates, sometimes minor, to the docs. So I'd recommend to provide full docs in the GitHub readme, but still give a short description of the library on NPM, which in combination with keywords field of package.json will make the package more discoverable. It's also a good idea to include badges in the NPM readme because that will increase the quality score displayed by NPM (see discussion of "branding" score in this article).

Answer 2

Good question mate! I prefer GitHub to NPM for a number of reasons, such as

a) the column on NPM is to narrow and all tables start to scroll b) there is no padding when images are aligned to left of right c) the TOC navigation does not work because anchor links are generated differently on GitHub and npm

Therefore I found a solution: add a README file, which will be read by NPM, and keep README.md file which will be read by GitHub. Easy-peasy but no guarantee it will continue to work.

Answer 3

One solution can be to use two readme files and rename them using npm scripting during npm publish.

This can be done as follows.

On source control, we would have the following files:

• README.md - This is the default git readme where you would document your source.
• npm.README.md - This would be the readme that would be seen on NPM.

Next, we would have the following in package.json (note that some contents are omitted).

{
  ...    
  "scripts": {
    ... 
    "build": "...",
    "use:npmReadme": "mv 'README.md' 'git.README.md' && mv 'npm.README.md' 'README.md'",
    "use:gitReadme": "mv 'README.md' 'npm.README.md' && mv 'git.README.md' 'README.md'",
    "prepublishOnly": "run-s build use:npmReadme",
    "postpublish": "npm run use:gitReadme"
  }, 
  "dependencies": {
    ... 
  },
  "devDependencies": { 
    ... 
    "npm-run-all": "^4.1.2", 
    ...
  }
}

In devDependencies, the npm-run-all package is used. This allows using the run-s command to run specified npm scripts sequentially.

in the scripts section, we have the following scripts:

Scripts to Rename README files

• use:npmReadme - This simply backs up the current git specific readme, and then renames npm.README.md to be the default README.md.
• use:gitReadme - This simply reverts back to using the git specific readme as the default README.md.

prepublishOnly

This is executed BEFORE the package is prepared and packed, and ONLY on npm publish. (Does not run with npm install).

Here, the solution is built, and then we run use:npmReadme.

postPublish

This is executed AFTER the package is published on npm.

Here, we run use:gitReadme to revert the readme files back to their original state.

More information on prepublishOnly and postPublish can be found here.

Answer 4

It kind of depends on why you want to do this. Projects such as libsquoosh expose subdirectories as their own libraries while still importing them normally, resulting in this kind of structure:

├── cli
│   ├── index.js
│   ├── package.json
│   └── README.md
│
├── libsquoosh
│   ├── index.js
│   ├── .npmignore
│   ├── package.json
│   └── README.md
│
├── src
│   └── index.js
│
├── package.json
└── README.md

From within the main application in src you then import the lib normally via:
import x from ../mySubdir/index.js
But from external projects you import it as:
import x from @namespace/mySubdir
The src dir then isn't sent to NPM, only the two subdirs are, both with their own completely different README files. Meanwhile, the git root has yet a third README.

Note that each subdir has its own package.json and .npmignore files despite being part of a larger project.

This achieves the same effect as uploading something different to NPM than what you see in the git project's root, but adds clear hierarchical organisation for free.

Answer 5

keshav.bahadoor's answer inspired me to use similar approach in GitHub workflows.

I'm using it as following:

  - uses: actions/checkout@v2
  ...
  - run: mv NPM-README.md README.md
  ...
  - run: npm publish --access public

I'm moving NPM-README.md to README.md only during workflow and not committing.

rest of the workflow yaml file

Note: This is working for GitHub workflows, not makes sense to use in your local.

Answer 6

1. (the more good one) If we named the npm readme to README.md and the GitHub readme to readme.md. Then we can add readme.md for the npm ignore .npmignore and add the README.md for gitignore .gitignore.

2. (the more bad one) Add npm.README.md and git.README.md. Remove the npm. or git. when commiting or publishing the git or npm.