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

Question

发布时两者都使用

README.md

作为描述。常见的做法是使用单个共享文件。

但是如果我需要不同的自述文件并且仍然从单个本地存储库发布它而不需要手动编辑/替换怎么办

PS

我尝试在 package.json 中使用

"readme": "npm-readme.md"

，但它显示此字段的值，而不是文件的内容

Answer 1

由于某种原因，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 上提供该库的简短描述，这与

keywords

的

package.json

字段相结合将使包更容易被发现。在 NPM 自述文件中包含徽章也是一个好主意，因为这将提高 NPM 显示的质量分数（请参阅本文章中对“品牌”分数的讨论）。

Answer 2

问得好！与 NPM 相比，我更喜欢 GitHub，原因有很多，例如

a) NPM 上的列变窄并且所有表格开始滚动 b) 当图像左右对齐时没有填充 c) TOC 导航不起作用，因为 GitHub 和 npm 上的锚链接生成方式不同

因此我找到了解决方案：添加一个

README

文件，该文件将由 NPM 读取，并保留

README.md

文件，该文件将由 GitHub 读取。很简单，但不能保证它会继续有效。

Answer 3

一种解决方案是使用两个自述文件，并在

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

在 devDependency 中，使用了 npm-run-all 包。这允许使用 run-s 命令顺序运行指定的 npm 脚本。

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

重命名自述文件的脚本

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

仅预发布

这是在准备和包装包裹之前执行的，并且仅在

npm publish

上执行。（不与

npm install

一起运行）。

这里，解决方案已构建，然后我们运行

use:npmReadme

。

发布发布

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

在这里，我们运行

use:gitReadme

将自述文件恢复到原始状态。

有关 prepublishOnly 和 postPublish 的更多信息可以在此处找到。

Answer 4

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

我的使用方式如下：

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

我仅在工作流程期间将

NPM-README.md

移动到

README.md

，而不是提交。

工作流程 yaml 文件的其余部分

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

Answer 5

（更好的） 如果我们将 npm

 自述文件命名为

README.md

，将

GitHub

 自述文件命名为

readme.md

。然后我们可以为 npmignore 添加

readme.md

.npmignore

 并为 gitignore 添加

README.md

.gitignore

。

（更糟糕的）添加npm.README.md
```
和
```
git.README.md
```
。提交或发布 git 或 npm 时删除 
```
npm.
```
 或 
```
git.
```
。
```

Answer 6

这取决于您想要这样做的

原因。诸如 libsquoosh 之类的项目将子目录公开为自己的库，同时仍然正常导入它们，从而导致这种结构： ├── cli │ ├── index.js │ ├── package.json │ └── README.md │ ├── libsquoosh │ ├── index.js │ ├── package.json │ └── README.md │ ├── src │ └── index.js │ ├── package.json └── README.md

从

src

的主应用程序中，您可以通过以下方式正常导入库：

import x from ../mySubdir/index.js
。

但从外部项目中，您将其导入为：

import x from @namespace/mySubdir
。

这与上传与 git 项目根目录中不同的内容到 NPM 具有相同的效果，但免费添加了清晰的层次结构。

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

问题描述投票：0回答：6

6个回答

最新问题

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

问题描述 投票：0回答：6

6个回答

最新问题

问题描述投票：0回答：6