[Proposal] Cross repo publishing

[gustavohenke]

Is this a bug report?

No

Have you read the Contributing Guidelines on issues?

Skimmed through it, expect it to be the same as most other OSS projects

Environment

Docusaurus ^1.0.15

Steps to Reproduce + current behaviour

1. Have your docs code in a project repo. Make sure to have master checked out.
2. Point your deployment to an user/org repo (.github.io) that has no commits (important)
3. Try publishing your docs, check that it works (it won't after Fail properly when current branch is the same as the deployment one #716 is merged)
4. Do some changes, then try publishing again.

After this, you'll get #406 thrown at your face.

The reason is that the publish script is not ready to deal with cross repo publishings.
It only knows how to deal within user sites (master publish target, source as source branch) or project sites (gh-pages publish target, master as source branch).

Expected Behaviour Feature

Have some way of letting docusaurus-publish know we're doing a cross repo publishing.

Reproducible Demo

express-validator org is such a setup.

Here's the siteConfig.js, it has projectName set to express-validator.github.io, but the code is not in the org site repo.
When you go there, all you will see is the built HTML/CSS/etc.

[gustavohenke]

I'm willing to tackle this one if we agree on some way of implementing it.

I'm happy with having an env flag like CROSS_REPO_PUBLISHING=true docusaurus-publish for now, even though I know this is not very nice.

[endiliey]

@gustavohenke
Could you tell us more on how do you plan to implement this ?

[gustavohenke]

A few ideas:

• A naive env flag that simply bypasses the branch check here 🤢
• An elaborate git remote check.
  If the target is .github.io, but the repo that contains the docs sources isn't tracking a .github.io remote, then you can proceed publishing it.

[endiliey]

Tbh i think having to set an env flag and having to type CROSS_REPO_PUBLISHING=true docusaurus-publish is quite unnatural to do.

My understanding is that you want separate code repository. One is the one that contains docs while another one is the published code (just the built html/css file).

I think it's better to make it such that whether it's in the same repo / different repo, if I set my 'projectName' & 'organizationName` to something, I want my published codes (built HTML/CSS) to be there.

What do you think ?

[bhouser]

As a developer, I find it valuable to have the docs in the same repository. The docs changes are then in the same commits/branches as the corresponding code changes. The ability the generate the documentation website from more than one repository wozld he very useful at my company, where we are not using a monorepo.

…

On Thu, Jun 7, 2018, 10:50 Endilie Yacop Sucipto ***@***.***> wrote: Tbh i think having to set an env flag and having to type CROSS_REPO_PUBLISHING=true docusaurus-publish is quite unnatural to do. My understanding is that you want separate code repository. One is the one that contains docs while another one is the published code (just the built html/css file). I think it's better to make it such that whether it's in the same repo / different repo, if I set my 'projectName' & 'organizationName` to something, I want my published codes (built HTML/CSS) to be there. What do you think ? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#717 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAaetIKeNNRIicx3UsYX6zXAYCB-brxdks5t6OlTgaJpZM4UVXLc> .

[JoelMarcey]

Do you think that this would be a super common use-case? If not, then I don't mind an environment variable that can be used and is documented (e.g., @gustavohenke naive flag idea). Otherwise, we should consider this some more -- maybe we still use the flag, but having something in the core code that works could be better.

[gustavohenke]

if I set my 'projectName' & 'organizationName` to something, I want my published codes (built HTML/CSS) to be there.

So this would mean simply removing the branch check, I guess?

Do you think that this would be a super common use-case?

I'm not sure. Perhaps?
I failed finding many projects that represent this, but a very popular one is Jasmine. Same setup:
Source is here and docs are here.

My points in favour of this cross repo publishing is

• the coolest URL some folks can get is the .github.io one (without 💰)
• as a good practise, mindful OSS maintainers will keep docs close to sources, so a single PR can update all around the change.

[azu]

I've used cross repo publishing pattern.
Source repository and Website repository are in a different place.

• Almin – Source almin/website/, WebSite: almin.github.io
  • Source repo includes website(Docusaurus). because I want to update API document from source code
• textlint – Source: textlint/website/, WebSIte: textlint.github.io
  

Currently, I use shell script to deploy.

• https://github.com/almin/almin/blob/master/tools/push-to-github-io.sh
• https://github.com/azu/travis-scripts is a fork of alrra/travis-scripts
  for some reason

[JoelMarcey]

I definitely think the most common case if having the raw docs and site close to the source code, but the built rendered HTML on gh-pages.

We are definitely willing to consider a pull request that makes your use case easier for anyone who needs it, whether through a environment variable or a more substantial code change.

[endiliey]

Closed by #764