Integrating several Vitepress instances in one website using Gitlab Pages on a single subdomain

[rriemann]

Dear all,

For one project, we have documentation in several repositories that should lead to a website perceived as one.

Current idea:

gitlab.com/project/gitlab-profile -> web at project.gitlab.io
gitlab.com/project/repoA -> web at project.gitlab.io/repoA
gitlab.com/project/repoB -> web at project.gitlab.io/repoB

I keep the same navigation in all 3 repositories (could be via a submodule) so that people can seamlessly switch between the 3 parts of the website.

My questions are now:

1. I need to configure 3 different base paths for this. Does it break the single page app in 3 different apps or will it just work?
2. If I "outsource" search to e.g. Algolia, will search work across the 3 pages?
3. Any other things that I may overlook, but that may break with such a setup?

This is a bit similar to issue #2386, but different as the build would indeed happen in independent pipelines.

[brc-dd]

1. They will become 3 separate SPAs. Changing from one SPA to another (like going from repoA/foo to repoA/bar) will trigger a full page navigation. Other stuff should work fine. If there are markdown links between the repos, you might need to use ignoreDeadLinks in vitepress config.

2. It can work if Algolia's crawler is able to discover all pages from your project.gitlab.io. You'll need to create single index and use the same settings for all three apps. Navbar should also probably be same across all apps. Find some way to share parts of config and any theme customization between the apps.

3. Not sure, sitemaps will break if you've enabled their generation. You can however fix that quite easily. In your gitlab-profile project, use the buildEnd hook to rename the generated sitemap.xml and create a new sitemap.xml that uses sitemapindex. I think this would fix any issues if Algolia is not able to discover all pages, though I'm not sure if Algolia properly supports sitemapindex, but its crawler config accepts sitemaps as array of strings, so you can use that if it doesn't work.

[rriemann]

I understand it would be better than to have a main pipeline that copies files from several repos together in one place to render a single vitepress site and trigger that pipeline from pipelines of that other repos.

[brc-dd]

Yeah I think this should work fine for most cases. In #2386 too I think the author finally decided to build separately then upload output. It should be easier in your case as gitlab would handle the subpath routing and stuff. For sharing the config/theme, I think you can publish some npm package with config/theme.