Gatsby: GitHub Organization or User page Best Practices?

[sunglee]

When I tried to publish a Gatsby site to a Github user page, such as .github.io, it pushes the generated content to master branch. What is the best practices to store source code as well as generated output in Github?

Thanks!

[keithgnx]

Check out How Gatsby Works with GitHub Pages.

You’ll need to install the gh-pages package as a dev dependency and add a deploy script to build the site to your gh-pages branch.

[KyleAMathews]

If the docs aren't clear, please let us know so we can improve them!

[sunglee]

@keithgonzalez I understand when you create a GitHub page for a specific repo. My question was for the case of User/Organization page.

In the documentation,

GitHub Organization or User page
First thing is to create a repository which should be named username.github.io.

In this case we don't need to specify pathPrefix, but our website needs to be pushed to master branch.

It is mentioned website needs to be pushed to master branch. My question was what is the recommendation to keep source code tracked while master branch is used for exported files. Do you create two separate repos, one for source and the other for GitHub Page?

[keithgnx]

I found more documentation on this in the Deploying page under Quick Start.

The sites must be published from the master branch of the repository which means the site source files should be kept in a branch named source or something similar.

@KyleAMathews It seems the How Gatsby Works with GitHub Pages guide is not as detailed as the GitHub Pages section of the Deploying page under Quick Start. I found the latter more helpful.

[sunglee]

@keithgonzalez Thanks for the clarification! That makes sense and removes any guess work.

[KyleAMathews]

Hmmm weird we have both pages. We should combine the two somehow.

[ghost]

@sunglee I fixed it by adding the repo parameter to the _build script:_
gatsby build && gh-pages -d public -b master -r https://github.com/githubuser/githubuser.github.io

[lacker]

These docs still don't work for org or user pages; if you follow them exactly for a user site then your repository gets totally overwritten by the generated output!

Adding explanation here for other people. The problem is that for user or org pages, GitHub requires that the static content live at the root directory on the master branch. But that's where you normally would do your development, rather than store your static files, so it's annoying.

The way I did it was to have two repositories set up on GitHub. You have one repo that contains your Gatsby project, just name it "website" or something. And then you have a separate repo, named your-user-name.github.io. That one you will never use manually, it just contains the static content output from Gatsby.

You then need to add a -r parameter in your deploy script like @ghost describes above to tell gh-pages, hey I am running you in the "website" repo, but don't deploy to that one, deploy to the your-user-name.github.io repo.

You could also do it by doing your real development in a branch, and letting master be your autogenerated output, but that seems unusual to me.

[lacker]

Check out How Gatsby Works with GitHub Pages.

You’ll need to install the gh-pages package as a dev dependency and add a deploy script to build the site to your gh-pages branch.

This is incorrect. GitHub doesn't support the gh-pages branch for organization or user pages, only the master branch. See https://help.github.com/en/articles/user-organization-and-project-pages for details