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

Question

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

但是,如果我需要使用不同的自述文件并仍然从单个本地仓库发布它而无需手动编辑/替换,该怎么办？

PS

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

Answer 1

由于某种原因，当我尝试时，zavr 的答案（使用README和README.md）不起作用（可能 NPM 使用的逻辑已经改变）。但是有效的是将 GitHub README 放入.github目录中（根据他们的文档这是允许的），并使用根目录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 年 2 月 6 日更新：有关最佳实践的快速说明。NPM 不允许您在不更改软件包版本的情况下更新自述文件，实际上您经常需要对文档进行更新（有时是较小的更新）。因此，我建议在 GitHub 自述文件中提供完整的文档，但仍然在 NPM 上提供该库的简短描述，这与keywords字段结合package.json将使包更容易被发现。在 NPM 自述文件中包含徽章也是一个好主意，因为这将提高 NPM 显示的质量分数（请参阅本文中对“品牌”分数的讨论）。

Answer 2

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

这可以按如下方式完成。

在源代码控制上，我们将拥有以下文件：

• 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包。这允许使用run-s命令按顺序运行指定的 npm 脚本。

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

重命名自述文件的脚本

• 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 3

好朋友！由于许多原因，我更喜欢GitHub而不是NPM，例如

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

因此，我找到了一个解决方案：添加一个README文件，该文件将被NPM读取，并保留该README.md文件将被GitHub读取。轻而易举，但不能保证它将继续工作。