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

Question

发布时，两者都使用README.md作为说明。通常的做法是使用单个共享文件。

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

PS

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

Answer 1

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

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

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

Answer 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 上提供库的简短描述，结合 keywords 的 package.json 字段将使包更容易被发现。在 NPM 自述文件中包含徽章也是一个好主意，因为这会提高 NPM 显示的质量得分（请参阅本 article 中关于“品牌”得分的讨论）。

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

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

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

重命名自述文件的脚本

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

prepublishOnly

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

此处构建解决方案，然后运行use:npmReadme。

postPublish

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

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

有关prepublishOnly和postPublish的更多信息，请访问here。

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，而不是提交。

workflow yaml file的其余部分

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

Answer 5

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

2. （最糟糕的一个）添加npm.README.md和git.README.md。提交或发布git或npm时，请删除npm.或git.。