logo标签列表

如何为Github和NPM指定不同的readme文件

githubnpmdocumentationpublishreadme
23

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

但如果我需要不同的Readme，并且仍然要从单个本地仓库发布，而不进行手动编辑/替换怎么办？

PS

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

虽然这并没有直接回答这个问题，但值得一提的是，有些仓库也是单体仓库（例如 Jest），它们使用 package.json 文件中的 "repository.directory" 字段将仓库分成多个包，然后每个包都可以有自己的 README.md 文件。 - aderchox
在这种情况下，问题可能是相同的 - GitHub 在一个包文件夹中显示的内容与该包的 NPM 页面上显示的内容不一致。 - Oleg Pro
6个回答
10

好问题，伙计！我更喜欢GitHub而不是NPM，原因如下：

a) NPM上的列太窄了，所有表格都开始滚动 b) 当图片对齐到左侧或右侧时，没有填充 c) TOC导航无法工作，因为在GitHub和npm上生成的锚链接不同

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

3
所以，npm将采用README而不是README.md？ - Oleg Pro
2
是的，这是一个npm页面 https://www.npmjs.com/package/@rqt/namecheap 这是它的GitHub https://github.com/rqt/namecheap。您可以尝试在包中使用beta标签发布，例如：yarn publish --tag beta - zavr
2
太棒了，伙计！而且非常简单！ :) - Oleg Pro
@zavr — 很好的发现！你能解释一下jQuery是如何做到的吗？他们在npm上的自述文件与github上的不同，但我在存储库或gitignore中找不到npm自述文件。 npm：https://www.npmjs.com/package/jquery/v/3.3.1 github：https://github.com/jquery/jquery/tree/3.3.1 - chharvey
10

由于某些原因，当我尝试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-02-06更新：关于最佳实践的一些快速说明。如果不提升软件包版本，NPM将不允许您更新自述文件，在实际情况下，您经常需要对文档进行某些更新，有时是小更新。因此，我建议在GitHub自述文件中提供完整的文档，同时在NPM上给出库的简短描述，结合package.json的keywords字段，可以使软件包更易于发现。在NPM readme中包括徽章也是一个好主意，因为这将增加NPM显示的质量分数（请参见这篇文章中“品牌”得分的讨论）。

1
太棒了，伙计，这是最终解决方案！真的有效，证明请见 https://www.npmjs.com/package/@usulpro/readme-pro - Oleg Pro
7

一种解决方案是在 npm publish期间使用两个 readme 文件并通过 npm 脚本重命名它们。

操作步骤如下：

在源代码管理中，我们将有以下文件：

  • README.md - 这是默认的 git readme，您可以在其中记录源代码。
  • npm.README.md - 这将是在 NPM 上看到的 readme。

接下来，在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 脚本。
在scripts 部分，我们有以下脚本： 更改 README 文件的脚本
  • use:npmReadme - 这只是备份当前 git 特定的 readme，然后将 npm.README.md 重命名为默认的 README.md。
  • use:gitReadme - 这只是将 git 特定的 readme 恢复为默认的 README.md。
prepublishOnly 该脚本在准备和打包软件包之前执行，仅在 npm publish 时运行（不会随 npm install 运行）。
在此处，构建解决方案，然后运行 use:npmReadme。 postPublish 该脚本在软件包发布到 npm 后执行。
在此处，我们运行 use:gitReadme，将 readme 文件恢复到其原始状态。
更多有关 prepublishOnly 和 postPublish 的信息可以在此处找到。
谢谢。这个解决方案很明显和直接，但它与手动重命名并没有太大的区别。我更多地询问了通过设置来实现这一点的可能性。所以我不能接受这个答案，但在某些特定情况下，它肯定可以作为一个解决方案。 - Oleg Pro
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工作流，不建议在本地使用。
0

  1. (更好的方案) 如果我们将 npm 的自述文件命名为 README.md，将 GitHub 的自述文件命名为 readme.md。那么我们可以将 readme.md 添加到 npm 的忽略文件 .npmignore 中，并将 README.md 添加到 gitignore 的忽略文件 .gitignore 中。

  2. (不太好的方案) 添加 npm.README.md 和 git.README.md。在提交或发布 git 或 npm 时删除 npm. 或 git.。

1
但我们希望将两者都保留在仓库中，因此.gitignore不应该放在这里。 - Oleg Pro
如果您想将它们都保存在存储库中，请选择第二个选项。 - tscpp
0
这有点取决于你为什么想这样做。像libsquoosh这样的项目将子目录作为自己的库暴露出来，同时正常导入它们，从而产生这种结构。
├── cli
│   ├── index.js
│   ├── package.json
│   └── README.md
│
├── libsquoosh
│   ├── index.js
│   ├── .npmignore
│   ├── package.json
│   └── README.md
│
├── src
│   └── index.js
│
├── package.json
└── README.md

从主应用程序中的src目录中，您可以通过以下方式正常导入库：
import x from ../mySubdir/index.js
但是在外部项目中，您需要这样导入：
import x from @namespace/mySubdir
然后，src目录不会被发送到NPM，只有这两个子目录会被发送，它们都有自己完全不同的README文件。与此同时，git根目录还有第三个README文件。

请注意，尽管这些子目录是一个较大项目的一部分，但它们各自都有自己的package.json和.npmignore文件。

这样做可以实现与在NPM上上传与git项目根目录中所见不同的内容相同的效果，同时还可以免费提供清晰的分层组织。

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接