6

我的问题：是否有任何开箱即用的 docusaurus 功能（除了https://github.com/facebook/docusaurus/pull/764）可以使以下操作更容易？（我在这里问过这个问题，因为他们的 github 问题模板告诉我这种类型的问题将被关闭，而是在这里问他们）。

在我的公司，我们有几个不同的存储库，其中包含 markdown 文档以及从各种不同编码语言的源代码文档生成的 markdown。

我想探索使用 docusaurus 来定义一个中心站点，但从许多不同的存储库中提取文档。

我想这样做：

  • 得到一个集中的搜索索引
    • 帮助可发现性
  • 获得集中拥有的一致主题/UX
  • 继续发布到融合中，以便非技术用户可以找到和浏览内容，如果这成为公司使用的政策（:(）
  • 保留 docs-close-to-code 的所有优点

这是 docusaurus 所期望的结构：

docs/            # all documentation should be placed here
website/
  blog/
  build/         # on yarn run build
  core/
    Footer.js
  package.json
  pages/
  sidebars.json
  siteConfig.js
  static/

这是我想最终得到的已发布网站的结构：

/v1/products/{product}/{version}/{language}/{content as from docs/}
# e.g.
/v1/products/spanner/{version}/en-GB/readme.html

/v1/internal/{gh-org}/{gh-repo}/{language}/{content as from docs/}
#e.g.
/v1/my-org/my-repo/{version}/en-GB/readme.html
/v1/my-org/my-repo/{version}/en-GB/proto-generated.html

（v1是不是因为我预测我会忘记一些东西，它让我可以对冲这一点，并使以后的重大更改重定向更容易）

我认为因此这是我需要将事物聚合成的中间结构：

docs/
  product/
    language/
      prose|generated-lang 
  gh-org/
    repo/
      language/
        prose|generated-lang
website/
  blog/
  product/
    language/
      prose|generated-lang 
  gh-org/
    repo/
      language/
        prose|generated-lang
  core/
    Footer.js
  package.json
  pages/
  product/
    language/
      prose|generated-lang 
  gh-org/
    repo/
      language/
        prose|generated-lang
  sidebars.json
  siteConfig.js
  static/
  product/
    language/
      prose|generated-lang 
  gh-org/
    repo/
      language/
        prose|generated-lang

……这能连在一起吗？

我可以很容易地通过 bash 或子模块 git clone 来安排它；这不是一个特别的问题。我想知道是否已经存在一些东西可以让我避免需要这样做 - 例如文档站点工具的本机功能、bazel 规则等等。

4

2 回答 2

2

您可以使用脚本来提取这些 md 文件，将它们放在正确的位置，然后构建 docusaurus。您可以使用 Github 的操作来自动更改您的源代码库之一

于 2020-08-10T09:06:29.400 回答
1

如果您不需要单页应用程序并且不需要 React（docusaurus在此处提到这一点），则可以使用MkDocs作为静态站点生成器和multirepo插件来完成此操作。以下是进行所有设置的步骤。我假设你已经安装了 Python 并且你创建了一个 Python venv。

  1. python -m pip install git+https://github.com/jdoiro3/mkdocs-multirepo-plugin
  2. mkdocs new my-project
  3. cd my-project
  4. 将以下内容添加到您新创建的mkdocs.yml. 这将配置插件。
plugins:
  - multirepo:
      repos:
        - section: Repo1
          import_url: {Repo1 url}
        - section: Repo2
          import_url: {Repo2 url}
        - section: Repo3
          import_url: {Repo3 url}

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

这将：

  • 获得集中的搜索索引以帮助可发现性
  • 获得一个集中拥有的一致主题/UX（我建议使用 MkDocs 的材料）
  • 保留 docs-close-to-code 的所有优点

可能会为 docusaurus 编写一个类似的插件。

于 2022-02-03T20:48:23.590 回答