从几个 github 存储库到静态站点的文档答案

【问题标题】：Documentation from several github repositories into a static site从几个 github 存储库到静态站点的文档
【发布时间】：2020-10-28 19:26:05
【问题描述】：

我需要一些帮助来确定可以帮助我为我的朋友创建无缝文档的正确解决方案。我们有几个存储库，其中将放置一个包含多个 .MD 文件的 doc 文件夹

Repo1
|- Readme.MD
|-docs
  |- Installation.MD
  |- Usage.MD

Repo2
|- Readme.MD
|-docs
  |- Installation.MD
  |- Usage.MD

Repo3
|- Readme.MD
|-docs
  |- Installation.MD
  |- Usage.MD

我们想使用像 vuepress 这样的东西来生成一个静态站点。如果有任何工具/框架可以轻松解决此问题。不胜感激

非常感谢您的任何回复，我们一定会把我们所做的事情放在下面

【问题讨论】：

如果 md 文件在项目中，我建议使用nuxt content
谢谢，会调查的。所有的MD文件不在同一个项目中
要将多个 Markdown 存储库合并到一个文档站点中，我建议使用 Foliant。检查include 预处理器以获取有关如何实现此目的的更多信息。
测试了 nuxt 和 Foliant。两者都是我的文档的站点生成器。 vuepress 也是如此。我更多的是研究几个 github 帐户并获取关联的 MD 文件

标签： reactjs vue.js documentation vuepress docsify

【解决方案1】：

这是一个想法，

初始化存储库，我们称之为TheRepo
将所有依赖的存储库（在我们的例子中为Repo1、Repo2、Repo3）添加为git submodules 到TheRepo

现在我们拥有从 Repo1、Repo2 和 Repo3 到 TheRepo 的所有内容，我认为这对于文档网站来说可能是不受欢迎的。

创建一个 bash 脚本（使用 find、grep、rm 或类似的 bash 魅力）以保留所需的 *.md 文件并删除不需要的源文件。以下是有关操作方法的示例：

// remove everything else that is not markdown file
find . -type f ! -name '*.md' -delete

在TheRepo的根处初始化vuepress，让vuepress生成合并文档。

如果您在第 3 步中做得很好。您可以在生成的文档中为每个单独的依赖 Repo 提供一个单独的 section/classification。

要刷新内容，只需使用git submodule update 更新文档，然后将其与步骤3 中创建的脚本链接起来，以自动完成刷新过程。

git submodule update && ./remove-undesirable-files.sh

【讨论】：

【解决方案2】：

您可以使用MkDocs 作为静态站点生成器和multirepo plugin 来完成此操作。以下是所有设置的步骤。我假设你已经安装了 Python，并且你创建了一个 Python venv。

python -m pip install git+https://github.com/jdoiro3/mkdocs-multirepo-plugin
mkdocs new my-project
cd my-project
将以下内容添加到您新创建的mkdocs.yml。这将配置插件。

plugins:
  - multirepo:
      repos:
        - section: Repo1
          import_url: {Repo1 url}
        - section: Repo2
          import_url: {Repo2 url}
        - section: Repo3
          import_url: {Repo3 url}

现在，您可以运行 mkdocs serve 或 mkdocs build，这将在一个站点中构建一个包含所有文档的静态站点。

【讨论】：