Documentation from several github repositories into a static site

Question

I need to some help to identify the correct solution that would help me create a seamless documentation for my friends. We have several repositories in which a doc folder with several .MD files are going to be placed

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

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

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

We would like to use something like vuepress to generate a static site. If there is any tool/framework which can easily solve this issue. I would be grateful

Thanks a lot for any response,we will definitely put below what we have done

if the md files are in the project i recommend using [nuxt content](https://content.nuxtjs.org/) — Boussadjra Brahim, Jul 08 '20 at 11:51
Thanks, will look into it. All the MD files are not in the same project — testeurFou, Jul 08 '20 at 12:08
To combine several markdown repositories into one documentation site I would recommend [Foliant](https://foliant-docs.github.io/docs). Check the [include](https://foliant-docs.github.io/docs/preprocessors/includes/) preprocessor to get more info on how to achieve this. — Bandantonio, Jul 08 '20 at 22:36
Tested both nuxt and Foliant. Both are site generator for my documentation. vuepress does the same. I am more looking into something that looks into several github accounts and gets the MD files associated — testeurFou, Jul 09 '20 at 18:10

score 2 · Accepted Answer · answered Jan 10 '22 at 14:13

You can accomplish this using MkDocs as your static site generator and the multirepo plugin. Below are the steps to get it all setup. I assume you have Python installed and you created a Python venv.

python -m pip install git+https://github.com/jdoiro3/mkdocs-multirepo-plugin
mkdocs new my-project
cd my-project
Add the below to your newly created mkdocs.yml. This will configure the plugin.

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

Now, you can run mkdocs serve or mkdocs build, which will build a static site with all the documentation in one site.

how do I set the credentials for the acess to the repositories? it works also for any git repository (e.g. an onpremise gitlab)? — effedici, Aug 24 '22 at 21:05

avimehenwal · Answer 2 · 2020-09-04T16:18:34.650

Here is an idea,

Initialize a repository, lets call it TheRepo
Add all depending repos (in our case Repo1, Repo2, Repo3) as git submodules to TheRepo

Now we have everything from Repo1, Repo2 and Repo3 into TheRepo, which I assume might be undesirable for a documentation website.

Create a bash script (using find, grep, rm or similar bash charm) to retain the desired *.md files and remove the undesirable source files. Here is a sample on how-to:

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

Initialize vuepress at TheRepo's root and let vuepress generate cosolidated documentation.

If you do a good job at step 3. you can have a seperate section/classification for each individual dependency Repo in the resulting documentation.

To refresh the contents, simple use git submodule update to update documentation and then chain it with script created in step3 as to automate the refresh process.

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

Documentation from several github repositories into a static site

2 Answers2