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

Posted 2023-03-30

【中文标题】如何为 github 和 npm 指定不同的自述文件

【英文标题】：How to specify different readme files for github and npm

【发布时间】：2016-12-23 07:34:20

【问题描述】：

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

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

PS

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

【参考方案1】：

好问题伙伴！我更喜欢 GitHub 而不是 NPM 有很多原因，比如

a) NPM 上的列正在缩小，所有表都开始滚动 b）当图像从左到右对齐时没有填充 c) TOC 导航不起作用，因为在 GitHub 和 npm 上生成的锚链接不同

因此我找到了一个解决方案：添加一个README文件，NPM会读取这个文件，并保留GitHub会读取的README.md文件。 Easy-peasy，但不保证它会继续工作。

【讨论】：

所以 npm 将使用 README 而不是 README.md？

是的，这是一个 npm 页面 npmjs.com/package/@rqt/namecheap 这是它的 github github.com/rqt/namecheap。您可以通过使用 beta 标签发布来在您的包上试用它，例如 yarn publish --tag beta

很好的解决方案，伙计！而且该死的简单！ :)

@zavr — 指出这一点的好眼光！你能解释一下jQuery是如何做到的吗？他们在 npm 上的自述文件与 github 上的不同，但我在 repo 或 gitignore 中找不到 npm 自述文件。 npm：npmjs.com/package/jquery/v/3.3.1github：github.com/jquery/jquery/tree/3.3.1

【参考方案2】：

由于某种原因，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 中关于“品牌”分数的讨论）。

【讨论】：

太棒了，这是最终的解决方案！确实有效，证明npmjs.com/package/@usulpro/readme-pro

【参考方案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", 
    ...
  

在 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 的信息可以在here找到。

【讨论】：

谢谢。此解决方案是显而易见且直接的解决方案之一，但与手动重命名相距不远。我询问了更多关于通过设置进行设置的可能性。所以我不能接受这个答案，但可以肯定它可以在某些特定情况下用作解决方案。

【参考方案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，而不是提交。

workflow yaml file的其余部分

注意：这适用于 GitHub 工作流程，不适用于本地。

【参考方案5】：

（更好的） 如果我们将npm 自述文件命名为README.md，将GitHub 自述文件命名为readme.md。然后我们可以添加 readme.md 为 npm 忽略 .npmignore 并添加 README.md 为 gitignore .gitignore。

（更坏的那个）添加npm.README.md和git.README.md。在提交或发布 git 或 npm 时删除 npm. 或 git.。

【讨论】：

但我们希望将两者都保留在 repo 中。所以 .gitignore 不会去这里

如果你想将它们都保存在 repo 中，请选择 2