💾 Archived View for sylvaindurand.org › static-website-with-jekyll › index.gmi captured on 2022-04-29 at 11:23:48. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2022-04-28)
-=-=-=-=-=-=-
At the beginning of the Internet, there were static sites: each web page was written "by hand" using a text editor, and then put online. The disadvantages are many, especially the need to duplicate the same changes on some pages (this is why it was sometimes really hard to maintain a website), to know HTML and to have his computer available to edit pages. The advent of CSS, which allows to separate actual content from its presentation format and to share it between the pages has not changed this fact (moreover, the inexistant interoperability between browsers and the poor support of CSS with Microsoft Internet Explorer, have delayed its use).
It was then that appeared dynamic sites: the different programming languages, running on the server side, such as PHP, helped the rise of CMS, which made possible to create sites and change their content directly from a browser, thus allowing the emergence of sites, blogs, forums accessible to the greatest number. This is for example the case of Spip, Dotclear or WordPress. However, these systems are not without disadvantages:
- they are very sensitive to security gaps, which implies that you need to monitor carefully updates and logs;
- they are server ressource intensive, and need specific hostings for large volume of visitors;
- they badly handle significant increases in workload, so they are very sensitive to DDoS attacks or huge influx of visitors (it is not uncommon that a website become unavailable because of an important event or a link from a news website);
- they tend to be a labyrinthine system, largely overkill for their use and needing databases.
For a couple of years, static websites has come back into favor with the emergence of the static website generators. With simple text files, a program generates a website made entirely from static pages you just have to host. Security problems are thus virtually non-existent, it is possible to host your website on a very modest server or rather the opposite, to get excellent performances and handle huge increases in workload using a CDN like Cloudflare or Cloudfront. Ways to host a static website on Amazon S3 and Cloudfront are explained here:
Static website with Cloudfront
In addition, it is possible to follow the changes and to work collaboratively thanks to `git`, to write the articles online and to generate the website on the fly with services like GitHub and Prose.io, or to have a commenting system with Disqus.
This article will show how to install (I) and use (II) the Jekyll website static generator to create and modify a simple website.
Directly install the last stable version of Ruby, or RVM, then simply launch:
gem install jekyll
The command `jekyll new mysite` will create the source code of a working website in the `mysite` folder. In this folder, you can generate the website with `jekyll build`. The output can then be seen in the `_site/` folder.
With a single command, it is possible to generate the website and create a local host in order to watch the produced website: use `jekyll serve` in order to get your website available on `http://localhost:4000`. You can also automatically regenerate the website each time you change something in the source code (however, this option doesn't detect the changes provided in `_config.yml`) with `jekyll serve -w`, which will be by far the most useful command when you'll start to play with Jekyll.
Jekyll uses several folders:
- `_posts/` in which the articles are stored (you can freely organize your files in `_post`), with names such as `yyyy-mm-dd-post-name.md`;
- `_layouts/` which contains the layout of the website, that is to say everythin that will surround the articles;
- `_includes/`, which contains small page fragments that you wish to include in multiple places on your site (when you put a file in `_includes`, it is possible to include it anywhere with the tag `{{ include filename }}`. Il is also possible to provide it parameters).
The tree structure may then looks like:
mysite/
_includes/
_layouts/
default.html
page.html
post.html
_posts/
2014-08-24-static-website-with-jekyll.md
assets/
style.sass
script.js
favicon.ico
index.html
rss.xml
_config.yml
You can add any folder or file in your website folder. If they don't start with an underscore, Jekyll will generate them on the same location.
Now that the first website is created, we will see how to make it evolve, how to write articles and use metadata.
In order to create an article, juste create in `_posts` folder a file with a name with the following format: `yyyy-mm-dd-post-name.md` (it is also possible to create articles in the folder `_drafts`, without any date in the file name: thus, it will create drafts invisible in the posts list but available with their URL). This file is divided into two sections: the frontmatter where the metadata are stored, and the content of the article.
The frontmatter allows us to declare metadata, which will be called or tested in the website. It is set into the top of the file, under the following format:
--- layout: default title: My title ---
Only the `layout` variable is required: it defines which file in `_layouts/` Jekyll should use to build the page. It is also usual to define a `title` variable in order to provide a title to our article (some variables are reserved by Jekyll with a particuliar behaviour: `permalink` for exemple specifies the final URL of a file).
It is also possible to define default variables, declared once for all or parts of the articles. For instance, instead of declare `layout: default` in each article stored in `_posts/`, you may declare it once in `_config.yml`:
defaults:
-
scope:
path: "_posts"
values:
layout: "default"
By default, Jekyll use Markdown. The purpose of this language is to provide a very simple syntax to replace the most commons HTML tags. It is however still quite possible to use HTML in posts.
From its second version, Jekyll uses Kramdown which add many features like the possibility of giving CSS classes to elements, footnotes, definition lists, tables...
Any metadata "`variable`", declared in the frontmatter or as a default, can be called anywhere in the website, with the tag `{{ page.variable }}`, which returns its value.
It is also possible to do some tests:
{% if page.variable == 'value' %}
banana
{% else %}
coconut
{% endif %}
We can also, for example, make loops on each article satisfying some conditions:
{% assign posts=site.posts | where: "variable", "value" %}
{% for post in posts %}
{{ post.lang }}
{% endfor %}
Although the syntax may not be very elegant to use, the large number of available variables, plus the custom metadata, combined with the filters et commands, may become highly effective.