githubnpmdocumentationpublishreadme

How to specify different readme files for github and npm


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


Solution

  • 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).