I had some security issues with WordPress so I decided to changed my blog to something static and served from GitHub Pages. But the new site had to meet some minimum requirements:
- Good looking
- Multi-language support (Spanish and English)
- Static, no scripts or databases
I had heard about this solution so I had it as a reference, like Hugo, but I saw it’s supported by GitHub Pages therefore I decided to give it a try.
From WordPress to Jekyll
To recover the already published posts I set an isolated Docker environment using a database dump of the site and the latest WordPress version with the needed plugins to made it work.
Then to export all posts I used the WordPress to Jekyll Exporter plugin.
To use this plugin I had to disable the qTranslate plugin, which was outdated and without support. Anyway I needed to migrate it to another solution, but with this change it was not the case anymore.
Jekyll theme: Minimal Mistakes
I tried some options but the Minimal Mistakes theme suit better to what I was looking for regarding looking and functionality.
Jekyll multi-language: _i18n
For this I also tried a couple of plugins, but the one that worked better was jekyll-multiple-languages-plugin.
GitHub pages’ plugin support
GitHub Pages supports a really limited number of plugins, therefore if you need to use any custom plugin you must generate the site’s static files using Jekyll and then push them to GitHub. This way you can use any plugin regardless GitHub Pages’s support.
Automating the generation and publishing of the static files
There are several examples of how to automate the building and publishing of the static files, as described in the polyglot plugin wiki page:
# publi.sh # change the branch names appropriately git checkout site rm -rf _site/ jekyll build git add --all git commit -m "`date`" git push origin site git subtree push --prefix _site/ origin gh-pages
I came up with with the idea of using Bitbucket’s Pipeline to automate the publishing, so I did a research and found this very explained article Continuous Deployment for Jekyll using Bitbucket Pipeline to deploy in Github, which you can check to see the details steps.
Almost everything I did was based on the two former articles, but it was not straightforward, I had to adapt the script because I couldn’t push to my GitHub personal account’s gh-pages branch, so I defined my Pipeline this way:
This is a sample build configuration for Ruby. # Check our guides at https://confluence.atlassian.com/x/8r-5Mw for more examples. # Only use spaces to indent your .yml configuration. # ----- # You can specify a custom docker image from Docker Hub as your build environment. image: ruby:2.3.3 pipelines: default: - step: script: # Modify the commands below to build your repository. - bundler --version - bundle install - bundle exec jekyll build -t branches: master: - step: script: - bundler --version - bundle install - bundle exec jekyll build -t - git clone https://github.com/lgallard/lgallard.github.io.git - cp -r /opt/atlassian/pipelines/agent/build/_site/* lgallard.github.io/ - cd lgallard.github.io - git config --global user.email "firstname.lastname@example.org" - git config --global user.name "Luis Gallardo" - git config --global push.default simple - git add --all - git commit -m "`date`" - git push https://$email@example.com/lgallard/lgallard.github.io.git
Where $githubtoken is a environment variable passed to the container, which has the token previously generated at GitHub.
Pipeline building issues
Building the site on my local machine had no issues, but building it in the Pipeline brought this error:
bundle exec jekyll build + bundle exec jekyll build Configuration file: /opt/atlassian/pipelines/agent/build/_config.yml Source: /opt/atlassian/pipelines/agent/build Destination: /opt/atlassian/pipelines/agent/build/_site Incremental build: disabled. Enable with --incremental Generating... Building site for default language: "en" to: /opt/atlassian/pipelines/agent/build/_site Loading translation from file /opt/atlassian/pipelines/agent/build/_i18n/en.yml Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/main.scss': Invalid US-ASCII character "\xE2" on line 54 jekyll 3.6.0 | Error: Invalid US-ASCII character "\xE2" on line 54
Because it was an encoding issue I supposed there was something different in the Pipeline and my PC. I thought the Ruby Pipeline is just a Docker image of Ruby, then I checked the image’s documentation and it turns out that it can be fixed by setting the encoding via an environment variable in Settings > Pipelines > Environment variables:
Now just by pushing the posts to the Bitbucket repo it runs the Pipeline and it publishes everything on GitHub Pages!