h30x

2019-09-26

Quickstart pour Zola

🇬🇧

Ce tutoriel pas à pas est fait pour les personnes n'ayant jamais utilisé Zola, si vous avez déjà expérimenté ce logiciel, allez plutôt voir la feuille de triche.

Que vous aimiez le Rust et les GSS ou que vous n'ayez aucune notion sur l'un ou l'autre, si vous souhaitez réaliser un site web ou un blog, Zola est fait pour vous ! Nous allons découvrir ici les concepts fondamentaux de Zola, pour une compréhension extensive, consultez la documentation.

Une fois Zola installé, nous allons créer un site avec la commande

$ zola init quicksite

répondons aux questions interactive comme suit afin d'initialiser le fichier de configuration config.toml :

Welcome to Zola!
> What is the URL of your site? (https://example.com): http://example.com
> Do you want to enable Sass compilation? [Y/n]: Y
> Do you want to enable syntax highlighting? [y/N]: N
> Do you want to build a search index of the content? [y/N]: N

et 10 millisecondes plus tard, nous devrions avoir un dossier avec l'architecture suivante

$ tree quicksite/
quicksite/
├── config.toml
├── content
├── sass
├── static
├── templates
└── themes

dans ce dossier, lançons

$ zola serve

et consultons http://127.0.0.1:1111/ dans notre navigateur

zola_welcome

Comme indiqué, nous pouvons installer un thème (sautez directement à la section "contenu"), ou le créer nous même.

Premier thème

Créer un thème est presque aussi facile qu'écrire un site à la main et vous permet de comprendre le fonctionnement de Zola. Si vous êtes pressés, vous pouvez également installer le thème de ce tutoriel et l'examiner. Un thème par défaut est prévu, mais n'est pas encore disponible.

Commençons par créer la page index.html dans le dossier templates

<!doctype html>
<html lang="fr">
<head>
    <meta charset="utf-8"/>
    <title>Quicksite</title>
</head>
<body>
	<h1>Welcome</h1>
	<p>Hello world!</p>
</body>
</html>

la page ouverte dans notre navigateur se rafraîchit toute seule et nous voyons apparaître notre page "hello world"

Plutôt que d'écrire le contenu du site directement dans le thème, ce qui revient à faire un site à la main sans Zola, nous allons utiliser le moteur de template pour remplir le site avec des variables.

Nom du site

Premièrement, pour pouvoir changer le nom du site facilement, ajoutons une variable dans la section [extra] du fichier config.toml

[extra]
# Put all your custom variables here
nom_du_site = "Quickstart site"

pour utiliser cette variable, remplaçons la ligne title dans notre index.html

<title>{{ config.extra.nom_du_site | upper }}</title>

Nous avons ainsi utilisé la variable présente dans config et lui avons appliqué un filtre, c'est à dire une fonction arbitraire.

Contenu en Markdown

Qu'il s'agisse d'écrire un site ou un blog, il est toujours bien de pouvoir gérer le contenu de manière indépendante du thème. Ici, nous écrirons du contenu en Markdown. Créons d'abord un texte d'accueil pour notre site dans un fichier _index.md dans le dossier content

+++
title = "Welcome, you"
+++
Hello my world!

et changeons le fichier index.html pour qu'il prenne en charge ce contenu.

<body>
	<h1>{{ section.title }}</h1>
	<p>{{ section.content | safe }}</p>
</body>

La page se recharge, et nous voyons le contenu de _index.md affiché via le thème index.html ! Nous avons réalisé la séparation du thème et du contenu. Remarquons deux choses : le nom utilisé pour le fichier markdown, et le nom de la variable utilisée pour accéder aux données. Pour comprendre ceci, il nous faut expliquer la structure de contenu de Zola.

Structure de contenu

L'architecture d'un site en Zola peut ressembler à ceci

.
└── content
    ├── _index.md				# https://example.com/
    ├── blog
    │   ├── _index.md			# https://example.com/blog/
    │   ├── hello-world.md 		# https://example.com/blog/hello-world/
    │   ├── my-first-post.md 	# https://example.com/blog/my-first-post/
    │   └── zola-is-great.md	# https://example.com/blog/zola-is-great/
    │
    ├── wiki
    │   ├── _index.md			# https://example.com/wiki/
    │   ├── how-to-build.md 	# https://example.com/wiki/how-to-build/
    │   ├── deploy-advice.md	# https://example.com/wiki/deploy-advice/
    │   └── contrib-guide.md	# https://example.com/wiki/contrib-guide/
    │
    ├── about.md				# https://example.com/about/
    ├── contact.md				# https://example.com/contact/
    └── cv.md					# https://example.com/cv/

Tous les fichiers .md correspondent à des "pages" sauf les fichiers _index.md qui sont des "sections". Ces deux objets diffèrent juste par les variables acceptées dans leur en-têt, la section au format TOML délimitée par +++ en tête de fichier.

En-tête de page

Pour plus d'information, veuillez consulter la documentation dédiée.

title = ""
description = ""
date =
weight = 0
draft = false
slug = ""
path = ""
aliases = []
in_search_index = true
template = "page.html"

[taxonomies]
tags = ["rust", "web"]

[extra]

En-tête de section

Pour plus d'information, veuillez consulter la documentation dédiée.

title = ""
description = ""
sort_by = "none"
weight = 0
template = "section.html"
page_template =
paginate_by = 0
paginate_path = "page"
insert_anchor_links = "none"
in_search_index = true
render = true
redirect_to = ""
transparent = false
aliases = []

[extra]

Template extensible

L'intérêt d'un template est de maximiser la réutilisation de code. Découvrons comment utiliser les fonctionnalités basiques dans un exemple simple.

index.html

<!doctype html>
<html lang="fr">
<head>
    <meta charset="utf-8"/>
    <title>{{ config.extra.nom_du_site | upper }}</title>
</head>
<body>
	{% include "nav.html" %}
	{% block content %}{% endblock content %}
</body>
</html>

On découvre ici la balise include qui permet d'inclure un autre template et la balise block qui permet de déclarer un bloc qui sera remplacé par les templates qui dérivent de celui-ci.

nav.html

<nav>
  <ul>
    <li> <a href="{{ get_url(path="@/_index.md") }}"> Home </a> </li>
    <li> <a href="{{ get_url(path="@/contact.md") }}"> Contact </a> </li>
    <li> <a href="{{ get_url(path="@/about.md") }}"> About </a> </li>
  </ul>
</nav>

On découvre ici la fonction get_url qui permet d'obtenir l'URL d'une page dans le site, et la notation @/fichier qui permet de faire un lien interne vers une page du site.

page.html

{% extends "index.html" %}

{% block content %}
  <h1>{{ page.title }}</h1>
  <p>{{ page.content | safe }}</p>
{% endblock content %}

On découvre ici la balise extends qui permet de dériver d'un template existant pour en remplacer un ou plusieurs blocs.

section.html

{% extends "index.html" %}

{% block content %}
  <h1>{{ section.title }}</h1>
  <p>{{ section.content | safe }}</p>
  <p>Pages in section</p>
  <ul>
  {% for page in section.pages | reverse %}
      <li>
        <em> <a href="{{ page.permalink }}"> {{ page.title }} </a> </em>
        <span>{{ page.date | date(format="%Y-%m-%d") }}</span>
      </li>
  {% endfor %}
  </ul>

{% endblock content %}

On découvre ici la balise for qui permet de faire une boucle dans une liste d'éléments et des filtres comme date qui prennent des arguments.

contact.md

+++
title = "contact"
date = 2019-09-25

+++
Contact me at ...

On découvre ici une métadonnée supplémentaire indiquant la date de la page.

about.md

+++
title = "about"
date = 2019-09-25
+++

This site has been made with :

- Zola
- Sass
- TOML

On découvre ici une liste Markdown qui sera rendue comme une liste HTML.

Un peu de couleur

Sass est une sorte de css sans ponctuation de type {, ; et une gestion des variables. Il est utilisé par beaucoup de frameworks css. Si vous ne souhaitez pas l'utiliser, vous pouvez bien entendu écrire directement des fichiers css et sauter à la section suivante.

SASS

Profitons d'une fonctionnalité très agréable de Zola : la compilation Sass. Ajoutons la ligne

<link rel="stylesheet" href="{{ get_url(path="extra.css")}}"/>

dans le head de notre index.html et ajoutons le fichier extra.sass à la racine de notre dossier sass.

$bg: #111
$cl: #0f0

nav ul li
  display: inline-block
  margin-left: 10px
  border: solid 1px #666

body
  color: $cl
  background-color: $bg

a
  color: #a5a

CSS

Pour ajouter du css à notre thème, il nous suffit d'ajouter la ligne

<link rel="stylesheet" href="{{ get_url(path="extra.css")}}"/>

dans le head de notre index.html et d'écrire le fichier extra.css à la racine de notre dossier static.

nav ul li{
  display: inline-block;
  margin-left: 10px;
  border: solid 1px #666;
}

body {
  color: #0f0;
  background-color: #111;
}

a{
  color: #a5a;
}

Pour la suite

Dans ce court tutoriel nous avons introduit quelques concepts clé de Zola. Vous pouvez maintenant lire la documentation pour plus de détails ou créer tout de suite votre site grâce à Zola !