Multi repo content

support
1

Hi!

We are currently building a documentation for our products using hugo and docsy theme for docs versioning.

Our products have different versions and release strategies.

With this in mind, we planned to have a separate hugo repositories for each product and build each repository then service the public folders in nginx.

AAA ./public → /var/www/html/aaa
BBB ./public → /var/www/html/bbb
CCC ./public → /var/www/html/ccc

Then they are published to the same subdomain (docs.example.com) and do a url path based routing.

docs.example.com/aaa -> /var/www/html/aaa
docs.example.com/bbb -> /var/www/html/bbb
docs.example.com/ccc -> /var/www/html/ccc

The hugo docs is working as expected if they are published directory with our path base routing but if we added the url routing, the pages gets broken.
We tried several configurations and also added --baseURL but still same issue persists.

Are we missing something or is this setup viable?

2

Is the same domain is being used ?

The docs.example.com/aaa And docs.example.com/bbb share the same home page at docs.example.com ? Of did I misread this ?

If this is the case then aaa and bbb and ccc would be sections under docs.example.com

3

I have a similar use case. What I did was to make one repo the “main” one - i.e. the one that is built and to which the domain doc.domain.com is assigned. Within this repo (repo1), in the hugo.toml file, I then pull in the content from the other repositories - in my case I have two additional repositories where the content has its own specific lifecyle and is authored by many different people (I wanted to keep just that doc separate in dedicated repos). This is configured in the [module] section via [module.imports]:

[module]
  # uncomment line below for temporary local development of module
  # replacements = "github.com/google/docsy -> ../../docsy"
  [module.hugoVersion]
    extended = true
    min = "0.119.0"
  [[module.imports]]
    path = "github.com/google/docsy"
    disable = false
  [[module.imports]]
    path="gitlab.com/my_org/repo2"
  [[module.imports.mounts]]
    source = "content/en/technologies"
    target = "content/technologies"
  [[module.imports]]
    path="gitlab.com/my_org/repo3"
  [[module.imports.mounts]]
    source = "."
    target = "static/export"

repo2 contains markdown (approx 1100 .md files), and so this needs to be built by Hugo. The content is placed in doc.domain.com/technologies during the build of repo1.

repo3 contains HTML only (approx 6500 .html files) which does not change very often (it is old legacy doc) and therefore does not need to be transformed into markdown by Hugo. This gets sent to the static/export folder during the build of repo1 resulting in output visible at doc.domain.com/export

This works well and since Hugo builds very fast, there is no issue having to build repo1 (unchanged) and pull in repo3 (unchanged) if a change is made in repo2 (for example).

I use Cloudflare/Gitlab to host/store this and i’ve configured webhooks so that when a merge into the “main” branch on repo1, repo2 or repo3 is actioned, Cloudflare will initiate the repo1 build, pulling in the content from repo2 and repo3.

Note also that repo2 contains a hugo.toml and is structured just like a standard Hugo repo, this is so that I can build repo2 on its own if I want to check changes before they are merged.