Create Landing Pages For Your Projects With GitHub Pages | by Naveen Venkatesan | Towards Data Science

I come from an experimental science background where we deal with a ton of home-built experiment setups and data analysis scripts. Often, the result of this can be poorly documented and difficult-to-use code, especially after the original graduate student (who wrote it) has graduated and left. For this reason, when I developed some data analysis scripts during my grad school research, I decided I wanted to try and document/demonstrate it as well as I could so that any future users could use it intuitively. The result of my efforts is this landing page.
I was able to generate this website with GitHub Pages, which is a service that allows you to easily host a static website for your repository. Doing this is extremely simple, and your website will be at the URL:
https://<username>.github.io/<repository_name>
For simplicity, we don’t want a user that clones our master branch to also see all the of the HTML/CSS/JS files that will be associated with our project website. To get around this issue, we can use something called an orphan branch — essentially a branch that sits at the root of the tree with no previous commits. Then, by having all of our website files live in the orphan branch, when the repository is cloned, only the files on master will be shown by default (though anyone can still go to the website branch if they wish).
We create our orphan branch, which we will call gh-pages with the following command:
git checkout --orphan gh-pages
This is the part that I found the scariest when I first did this. You are going to remove everything from your folder in order to clear the gh-pages branch. Don’t worry, your master branch files are not gone! Use the following command:
git rm -rf .
You will notice that all the files will vanish from your local working directory, which is what freaked me out the first time I did this. Again, do not worry, everything will be fine!
Now, add your index.html file, along with any CSS stylesheets, Javascript, and other resources your website would need to run into your local working directory. Now stage and commit your changes:
git add *git commit -m "Commit Message"
Finally, we want to make sure we are pushing our changes to the appropriate branch (gh-pages).
git push origin gh-pages
Navigate online to your GitHub repository and go to the settings. As you scroll down, you will notice a section titled “GitHub Pages”. Under the area titled “Source”, you will see a drop-down menu, which you can use to select the branch from which to build your website. We will go ahead and select gh-pages.
Wait a couple minutes, and BAM! Your site should be live! Navigate your browser to https://<username>.github.io/<repo_name> to see your wonderful creation.
As you continue to edit your website and source code, you will quickly notice that you will have to keep switching between your two branches:
# Switch to master branchgit checkout master# Switch to gh-pages branchgit checkout gh-pages
Although simple, this may become cumbersome after a while — fortunately, we can use feature called worktree to create separate directories for each of these branches.
First, let’s either create a separate, new directory with the same name as our repository, or clear out our local working directory. If we clear out the current directory, we want to remove all the git tracking info, which we can do with the following:
# Remove git trackingrm -rf .git*
Now, let’s re-clone our repository into a subdirectory. We’ll call this directory source and it will be where we keep all our source code.
git clone https://github.com/<username>/<reponame> source
You will notice that you now have a folder called source with all the files from the master branch. Now let’s create a new directory called gh-pages that will house all our website files:
mkdir gh-pages
Navigate into the source folder:
cd source/
Now, we use worktree and make our gh-pages directory correspond to the remote gh-pages branch.
git worktree add ../gh-pages gh-pages
And you’re done! Now, you will notice that when you go to the gh-pages directory, you will only see the files on the gh-pages branch, and if you run a git branch command, you will see that you are on the master when in the source directory, and gh-pages when in the gh-pages directory.
You can now freely edit both your repository website and source code at the same time, and you have an awesome landing page for your project on GitHub!
Thank you for reading! You can see some of my work at my personal GitHub page. I appreciate any feedback, and you can find me on Twitter and connect with me on LinkedIn for more updates and articles.