18

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

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

附言

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

4

5 回答 5

11

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

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

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

于 2018-10-06T20:28:43.773 回答
7

一种解决方案是使用两个自述文件并在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 脚本。

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

重命名 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 的信息可以在这里找到。

于 2018-04-23T18:30:29.330 回答
7

由于某种原因，当我尝试时，zavr 的答案（使用READMEand README.md）不起作用（可能 NPM 使用的逻辑已经改变）。但是起作用的是将 GitHub README 放入.github目录（根据他们的文档允许这样做），并使用 rootREADME.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 上的库进行简短描述，结合keywordsfield ofpackage.json将使包更容易被发现。在 NPM 自述文件中包含徽章也是一个好主意，因为这会提高 NPM 显示的质量分数（请参阅本文中关于“品牌”分数的讨论）。

于 2021-01-12T00:26:38.433 回答
2

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

我使用它如下：

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

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

工作流 yaml 文件的其余部分

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

于 2020-06-21T00:13:13.647 回答
1

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

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

于 2019-06-13T11:02:16.453 回答