💾 Archived View for sylvaindurand.org › using-github-to-serve-jekyll › index.gmi captured on 2022-04-29 at 11:23:44. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2022-04-28)
-=-=-=-=-=-=-
GitHub has created a wonderful ecosystem built around the static websites generator Jekyll. GitHub Pages allows to generate, then to serve automatically Jekyll websites. This service, free and quite effective, brings together the best aspects of static websites – speed, reliability, security, ability to use `git` – while allowing their modification online. This article aims to show how to:
- synchronize your website with `git` on GitHub ;
- generate and serve it on the fly with GitHub Pages ;
- write articles directly on line thanks to Prose ;
- test compilations, HTML validity and links with Travis.
If you haven't already got one, create an account on GitHub by providing an username (beware, the username is important, because it will be used in the repository and the URL used by GitHub Pages), an email address and a password; otherwise, use your usual login informations.
In your profile page, choose Repositories then New in order to create the repository which will host our website. The repository name has to be `username.github.io`, where `username` is the one you provided when you signed up. The website will also be available on this location.
Choose the Initialize this repository with a README option in order to be able to use directly `git clone`.
If you have got a GitHub paid plans, you can create a private repository in order to hide your codes (in the case of a simple Jekyll website, this option may not be really useful).
On your computer, create the folder where the website will be stored, then open a terminal and clone the newly created repository:
git clone https://github.com/username/username.github.io.git cd username.github.io
Let's start by creating a `.gitignore` file which will allow us to ignore the `_site` repository in which the website will be generated (we musn't check this folder, which is only a result of the source code), the `Gemfile.lock` file we will create later, and if you use on macOS the `.DS_Store` folders created by the operating system. The `.gitignore` file will looks like:
_site .jekyll-metadata Gemfile.lock .DS_Store
We can now push this file on GitHub (when you `push` for the first time, you have to provide your username and your password, but they won't be asked again) :
git add .gitignore git commit -m "First commit" git push
Now, you only have to put your Jekyll website in this folder. It may be an existing website, or a newly created one thanks to `jekyll new`. It is then easy to maintain and edit the website with `git` :
- `git add` add the changes for the next commit;
- `git commit` valids thoses changes;
- `git push` sends them on GitHub.
For instance, in order to send our new website, we add every file, then we use `git commit` then `git push` :
git add --all git commit -m "First version" git push
Because the website only use simple text files, you can use git as you would do with any other project.
We will now see how to use GitHub to generate, then host and serve the website. You will just have to use `git push` in order to make GitHub generating and serving the last version of your website.
Each time you will use `git push`, your website will be automatically generated on GitHub.
This is why it is highly important to make sure everything is going to work perfectly, if we don't want to break our website online. In order to ensure your computer most closely matches the GitHub Pages settings, the best way to do is to use `bundler`:
gem install bundler
Then, create on the root a `Gemfile` file which will tells to use the `github-pages` gem, which provide automatically the last versions and dependancies used by GitHub:
source 'https://rubygems.org' gem 'github-pages'
You can then use `bundle install` in order to install the gem(s). The `bundle update` command will ensure you always have an up to date system.
The `bundle exec jekyll serve` command will now generate the website exactly as Github would do, so you can check on `http://localhost:4000` that everything is right before pushing anything.
Back on GitHub, go in the `username.github.io` repository, choose `Settings`, then the `GitHub Pages` section in order to activate the website generation.
Within a few moments (the first time, it can take a dozen of minutes, but then the website will be generated in a couple of seconds each time you push a commit), your website will be available on `https://username.github.io`.
If you have a custom domain name "`domain.tld`", it is of course possible to use it instead of the default URL given by GitHub, which will then redirect to the new domain name. However, it won't be possible to use HTTPS (if you try to go to `https://domain.tld`, you will get a blank page showing `unknown domain: domain.tld`).
If you want to use a subdomain `subdomain.domain.tld`, tell your registar to create a `CNAME` record, with the `subdomain` name and the `username.github.io` value. Then, create a file named `CNAME` on the root of the repository, containing exactly `subdomain.domain.tld`.
GitHub allows you to have a custom 404 error page. When you test your website locally with `bundle exec jekyll serve`, this error page also works: you can try by providing an incorrect URL. Just tell Jekyll to create a `404.html` on the root:
--- title: Page not found permalink: /404.html --- This page must have been removed or had its name changed.
One of the main disadvantages of static websites is the impossibility to edit them online without your computer.
Because your website is hosted on GitHub, it is possible to modify files directly online. Jekyll generates Pages each time you modify a page. You can also use the Prose.io website, which provides a nice interface, a great syntax highlighting and a preview system in order to write your articles.
On the Prose.io website, use your GitHub login information and allow Prose to see and change your repositories. You can then create and edit your articles, or any other file of the website.
Travis allows your to generate the website each time you push something, in order to check nothing is wrong. It is also possible to add some other tests like `htmlproofer` which checks if the HTML code is valid and there are no rotten links. You will get a warning email if something is wrong.
To do so, use your GitHub login informations on Travis, then enable the `username.github.io` repository. Then, add `htmlproofer` in your `Gemfile` file, which now looks like:
source 'https://rubygems.org' gem 'github-pages' gem 'html-proofer'
Finally, create a `.travis.yml` file in order to tell Travis how to build and test the website:
language: ruby rvm: - 2.1.1 script: - bundle exec jekyll build && bundle exec htmlproof ./_site
Now, each time you push something, Travis will send you an email if Jekyll can't generate your website, if the HTML code is not valid or if a link rot remains.