如何为 github 和 npm 指定不同的自述文件

Question

发布时都使用README.md作为描述。一种常见的做法是使用单个共享文件。

但是，如果我需要不同的自述文件并仍然从没有手册的单个本地存储库发布它怎么办editing/replacement

PS

我尝试在 package.json 中使用 "readme": "npm-readme.md" 但它显示的是该字段的值，而不是文件的内容

Answer 1

一种解决方案是使用两个自述文件并在 npm publish 期间使用 npm 脚本重命名它们。

这可以按如下方式完成。

在源代码管理中，我们将有以下文件：

README.md - 这是默认的 git 自述文件，您可以在其中记录您的源代码。
npm.README.md - 这将是在 NPM 上看到的自述文件。

接下来，我们在package.json中会有以下内容（注意省略了一些内容）。

{
  ...    
  "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", 
    ...
  }
}

在 devDependencies 中，npm-run-all package is used. This allows using the run-s 命令运行按顺序指定 npm 脚本。

在 scripts 部分，我们有以下脚本：

重命名 README 文件的脚本

use:npmReadme - 这只是备份当前 git 特定的自述文件，然后将 npm.README.md 重命名为默认值 README.md。
use:gitReadme - 这只是恢复到使用 git 特定自述文件作为默认 README.md。

仅预发布

这在包准备和打包之前执行，并且仅在 npm publish 上执行。（不运行和 npm install）。

到这里，解决方案构建完成，然后我们运行 use:npmReadme。

发布后

这是在包发布到 npm 之后执行的。

在这里，我们运行 use:gitReadme 将自述文件恢复到原来的状态。

可以找到有关 prepublishOnly 和 postPublish 的更多信息 here。

Answer 2

问得好伙计！出于多种原因，我更喜欢 GitHub 而不是 NPM，例如

a) NPM 上的列变窄，所有表格开始滚动 b) 当图像左右对齐时没有填充 c) TOC 导航不起作用，因为在 GitHub 和 npm

上生成的锚链接不同

于是我找到了解决办法：添加一个README文件，由NPM读取，保留README.md文件，由GitHub读取。简单易行，但不能保证它会继续工作。

Answer 3

（最好的那个） 如果我们将 npm 自述文件命名为 README.md 和 GitHub 自述文件至 readme.md。然后我们可以为 npm ignore .npmignore 添加 readme.md 并为 gitignore .gitignore 添加 README.md.
（越差越多）加上npm.README.md和git.README.md。在提交或发布 git 或 npm 时删除 npm. 或 git.。

Answer 4

回答启发我在 GitHub 工作流程中使用类似的方法。

我正在使用它如下：

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

我只是在工作流程期间将 NPM-README.md 移动到 README.md，而不是提交。

其余 workflow yaml file

注意：这适用于 GitHub 工作流程，在您的本地使用没有意义。

Answer 5

出于某种原因，zavr 的回答（使用 README 和 README.md）在我尝试时不起作用（可能 NPM 使用的逻辑已更改）。但是有效的是将 GitHub README 放入 .github 目录（根据他们的 docs 这是允许的），并使用根目录 README.md 作为 NPM 的版本行

<!-- 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.

幸运的是，GitHub .github/README.md 似乎优先于 README.md。

2021-02-06 更新：关于最佳实践的快速说明。 NPM 不会让您在不更改包版本的情况下更新自述文件，而实际上您经常需要对文档进行更新，有时更新很小。所以我建议在 GitHub 自述文件中提供完整的文档，但仍然在 NPM 上给出库的简短描述，结合 package.json 的 keywords 字段将使包更容易被发现。在 NPM 自述文件中包含徽章也是一个好主意，因为这会增加 NPM 显示的质量分数（请参阅此 article 中关于“品牌”分数的讨论）。

如何为 github 和 npm 指定不同的自述文件

How to specify different readme files for github and npm

documentation

publish

github

npm

readme