Part I: Create your GitHub Pages site
Step 1: Create a new GitHub repository
Create a new GitHub repository. This will normally leave you with a
main branch. Rename this to
master and clone it to your computer (or keep it, but then replace all the
master instructions below with
Alternatively, if you want to add the site to an existing repository, it recommended to host the source files on a separate empty, unrelated branch, a so-called orphan branch. We might call it
git checkout --orphan site-sources git rm -rf .
If you choose to go this way, please replace all the commands in this tutorial running on the
master branch with the
site-sources branch (or whatever you called it).
Step 2: Create a folder for your sources
Navigate to your local repository (you’re in the master branch) and create the
cd /path/to/your/repository mkdir docs cd docs
Step 3: Create a new Jekyll site
We will use the created folder as publishing source and create a new Jekyll site there.
jekyll new --skip-bundle .
Open the gemfile that Jekyll created and add “#” to the beginning of the line that starts with
gem "jekyll" to comment out this line. Then add the github-pages gem by editing the line starting with
# gem "github-pages". Change this line to:
gem "github-pages", "~> GITHUB-PAGES-VERSION", group: :jekyll_plugins
Replace GITHUB-PAGES-VERSION with the latest supported version of the
github-pages gem. You can find this version here: “Dependency versions.”
Save and close the gemfile and run
As your GitHub Page will be hosted in a subdirectory (e.g. for this specific site: ulricusr.github.io/multilingual-github-pages/), you need to add the
baseurl to the Jekyll
_config.yml file in your
baseurl: <your repository name>.
You can optionally preview your site on http://localhost:4000/multilingual-github-pages after having run
bundle exec jekyll serve.
Finally build your site using
bundle exec jekyll build. This will create a
_site folder, which should already be listed in your
.gitignore file. If not, do so.
Step 4: Commit your sources to your GitHub repository
To do so, move to the root directory of your local git repository, add and commit the newly created files (including the
/docs folder and ignoring the
/docs/_site folder), and push everything to your remote repository on GitHub.
cd .. git add -A git commit -m "Initial commit" git push
Your source files should now be in your GitHub repository. It’s time to take care of the generated site files.
Step 5: Create a new local repository for your site files
Navigate to your
/docs/_site folder and initialize a new repository with the same remote as above.
cd docs/_site/ git init . git remote add origin https://github.com/<your-username>/<your-repo-name>
As we want our files to be pushed to a separate branch
site, we need to create this branch using
git branch site.
Step 6: Prepare your site files and push them to your remote repository
Before we push our site files, we need to create one new, empty file named
.nojekyll. It makes sure that GitHub Pages does not process the site files, but deploys them as they come.
Now add, commit and push all site files to your remote repository. As the branch does not exist yet remotely, we need to set the upstream, using the
git add -A git commit -m "Initial commit" git push -u origin site
Your site files should now reside in the
site branch in your GitHub repository.
Step 7: Configure GitHub to the right publishing source
The final step is to configure GitHub Pages to deploy your site. Go to the settings of your repository, choose Pages from the menu, and set the build and deployment source to Deploy from a branch, then select your
site branch and keep the
/(root) folder. Hit save, wait a minute or so (you can always check the deployment progress in the “Actions” tab of your repository), and then check your online site by hitting the “Visit site” button.