Skip to content

Instantly share code, notes, and snippets.

Last active February 7, 2023 11:11
What would you like to do?
Deploy to `gh-pages` from a `dist` folder on the master branch. Useful for use with [yeoman](

Deploying a subfolder to GitHub Pages

Sometimes you want to have a subdirectory on the master branch be the root directory of a repository’s gh-pages branch. This is useful for things like sites developed with Yeoman, or if you have a Jekyll site contained in the master branch alongside the rest of your code.

For the sake of this example, let’s pretend the subfolder containing your site is named dist.

Step 1

Remove the dist directory from the project’s .gitignore file (it’s ignored by default by Yeoman).

Step 2

Make sure git knows about your subtree (the subfolder with your site).

git add dist && git commit -m "Initial dist subtree commit"

Step 3

Use subtree push to send it to the gh-pages branch on GitHub.

git subtree push --prefix dist origin gh-pages

Boom. If your folder isn’t called dist, then you’ll need to change that in each of the commands above.

If you do this on a regular basis, you could also create a script containing the following somewhere in your path:

if [ -z "$1" ]
  echo "Which folder do you want to deploy to GitHub Pages?"
  exit 1
git subtree push --prefix $1 origin gh-pages

Which lets you type commands like:

git gh-deploy path/to/your/site
Copy link

bomszx commented Sep 14, 2022

"scripts": {
      "gh-deploy": "git push origin :gh-pages && git subtree push --prefix dist origin gh-pages"
      "gh-deploy-init": "git push origin && git subtree push --prefix dist origin gh-pages",

In terminal:

npm run gh-deploy
npm run gh-deploy-init

this one worked for me, thanks mate!

Copy link

I want to deploy my website using Jekyll-scholar on Github pages. Since Github pages don't deploy it on their own, I will have to use another way of deploying a pre-built website. Can you please suggest some ways how to do that? I used rakefile, and when I force the built _site subdirectory to be the root of the project, it deletes everything, and therefore, nothing can be pushed. I am using this command git filter-branch --subdirectory-filter _site/ -f" I am using macOS 11.6 and using Jekyll-scholar. I am extremely new to this, so please pardon my naivety.

It's the leading underscore -- see:

Copy link

SookiezBoly commented Sep 26, 2022

If you already have a "gh-pages" branch, use the 1st command below. If you don't have a "gh-pages" branch, initialize it by using the 2nd command below. Make it easier to run by creating scripts like these in your package.json file:

"scripts": {
      "gh-deploy": "git push origin :gh-pages && git subtree push --prefix dist origin gh-pages"
      "gh-deploy-init": "git push origin && git subtree push --prefix dist origin gh-pages",

In terminal:

npm run gh-deploy
npm run gh-deploy-init

We aren't done just yet. Now go to your repository in GitHub. Go to Settings. Go to Pages. Under the Source section you will see a dropdown list of branches. Select the "gh-pages" branch and select the root as your folder. Then click Save.

Give GitHub some time to rebuild and deploy your repository's site. Boom you have your site up and running.

Hopefully this works for you all. Shoutout to @TheOdinProject.


It kinda works, but all the images i have on the website just gone now :(

Copy link

zooks commented Oct 28, 2022

If you got this error:

 ! [rejected]        * -> gh-pages (non-fast-forward)
error: failed to push some refs to '*'
hint: Updates were rejected because a pushed branch tip is behind its remote
hint: counterpart. Check out this branch and integrate the remote changes
hint: (e.g. 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Just delete the branch gh-pages by this command:

git push origin --delete gh-pages

Copy link

marc714 commented Dec 25, 2022

This won't work on github pages:

const myPicture = new Image();
myPicture.src = "./src/assets/image.png" 

You must use:

import myPicture from "./src/assets/image.png"
const banner = new Image();
banner.src = myPicture;

Make changes to your main branch (your gh-pages branch wont see changes):
git push

Make changes to your gh-pages branch:
git subtree push --prefix dist origin gh-pages

To refresh your chrome browser to see changes asap, press F12 to go into developer tools. Then right click on the reload icon next to your URL bar. Click 'Empty Cache and Hard Reload'

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment