Hugo is a great platform to deploy a blog with. Unfortunately and unlike Jekyll, I found it not very handy to setup a multilingual blog with. It has support for multilingual blog, but I think it is kind of hard to follow the guide.
So I decided to simply use git and git branches to build my blog with. And it works really well. If you are interested in building a multilingual blog with Hugo and GitHub Pages, please follow along.
We are going to use the master
branch to manage the english content of a hugo
website, and a french
branch to translate this content to another hugo
website. The static english version of the site will be served by your GitHub
Pages main page, and the static french version will be served by the gh-pages
branch of another repo.
First things first, create your blog
Hugo has a really nice tutorial to
explain how to create your website with it, but I want to explain some steps in
a little more details. Type the following command at the command line to create
a scaffold of a hugo website in the my-website
directory.
hugo new site my-website
Now type this one to go into your hugo website and download a theme to use for
your blog. I chosed ghostwriter
for obvious reasons but there are lots of
other good themes for hugo.
cd my-website
mkdir themes
cd themes
git clone https://github.com/jbub/ghostwriter
cd ..
Now edit config.toml
and add the following lines to it:
themes = "ghostwriter"
Go check this page for explanation on how to setup a ghostwriter-enabled website.
Now type:
hugo serve
It deploys a website on the http://localhost:1313/ port.
Write your first post
Type :
hugo new post/my-first-post-ever.md
to create a new post and edit it with your favorite editor. Of course, at this point your favorite editor should be Emacs, for reasons I’ll explain below, but you may chose another.
Now that you are satisfied with your first post, we are going to use git to manage the building of our website.
Manage your blog with git
Type the following commands at the command line.
git init
echo "public/" > .gitignore
echo "public-fr/" >> .gitignore
echo "themes/" >> .gitignore
git add .
git commit -m "first commit and first post"
Git must not track the themes
and public
directories. The themes directory
is already managed by git, since the themes are on their own git repo. The
public directories are going to be the directory that contains the static
version of our website, and will point to another repo.
Now the master branch is setup to track the “english” version of your blog. We must setup a branch to track the “french” (or german or swahili if you prefer swahili to french) version of our blog.
git branch french
git checkout french
Now edit your first post, and translate everything that need to be translated in french (or swahili).
git add content/post/my-first-post-ever.md
git commit -m "translated first post in english"
We now need to build the website with hugo. We are going to deploy the french
version in public-fr
and the english version in public
.
mkdir public-fr
hugo -d public-fr
If you ls public-fr
, you will see that hugo built the static website. Let us
deploy the english version.
git checkout master
hugo -d public
Host your pages on GitHub Pages
Now follow the instruction here to use GitHub pages to deploy your own website.
cd public
git init
echo "# english version of my personal website" > README.md
git add .
git commit -m "website updated"
git remote add origin https://github.com/username/username.git
git push -u
We are going to use another GitHub repo to publish the french version of the
website. Open a new repo on github, and call it fr
, or sw
if you still
prefer swahili. Now type at the command line:
cd ../public-fr/
git init
echo "# french version of my personal website" > README.md
git add .
git commit -m "site à jour"
git branch gh-pages
git checkout gh-pages
git remote add origin https://github.com/username/fr.git
GitHub will now serve the french version of your website to https://yourusername.github.io/fr/. I really love GitHub Pages.
That’s it, you can now setup a button as a link that points to your english version on the french website if you want.
Use Emacs to manage your Hugo blog
Here I’ll just point to another blog post from Toke Høiland-Jørgensen. He uses some custom elisp to wrap simple Hugo commands and manage his blog from Emacs.