Cross-repo documentation

[ptrhck]

I am considering to use nextra for documenting multiple repos and been thinking about two different strategies to achieve this. I have different teams with different repos and each should document allongside their code but maintain one docs site.

First idea, create a docs repo that pulls the mardown files from alle repos with some script (or is there a built in solution?). I see a few drawbacks here:

• If the content changes in one repo, I have to trigger the build of the docs repo. As I will deploy to vercel, I will not have the preview deployment commented to the source content repo.
• A rebuild of the whole site will be triggered if only one repo changes.
• I would like to generate markdown from repository specific resources like a GraphQL schema. In that case, I would need to cross copy all those source files to the build environment.

Second idea to adress all the above issues, is to deploy one nextra instance for each repository (should be possible with Next.js basePath, e.g. mydomain.com/docs1, mydomain.com/docs2 ). Here, a few questions that come up for this solution:

• Can I adjust the nextra header to display a navbar to link between the single docs pages?
• I would like to add algolia for a full text search, but I am wondering if it will be able to search through all individual doc sites if deployed this way?
• I would like to add some basic auth, e.g. using middleware. How can this be used in such multi deploys?

I am looking forward get some ideas!

Cheers!

[sibelius]

have you figure it out how to handle authentication with nextra?

[ptrhck]

I have not as I have decided to use docusaurus facebook/docusaurus#6086, but I think it should be possible with the linked middleware example as it is a next.js project anyway.