diff --git a/docs/divers/devops/hugo/hugo_from_scratch.md b/docs/divers/devops/hugo/hugo_from_scratch.md new file mode 100644 index 00000000..0ff89af1 --- /dev/null +++ b/docs/divers/devops/hugo/hugo_from_scratch.md @@ -0,0 +1,192 @@ +# Construire un site statique avec Hugo + +## Création du projet sur Gitlab + +### Création d'un nouveau projet + +![New blank Project](img/blank-project.png) + +### Configuration du déploiement sur Gitlab Pages + +#### Création du fichier de déploiement `.gitlab-ci.yml` + +![New file](img/gitlab-new-file.png) + +Name the file `.gitlab-ci.yml` and fill it with the following content: + + ``` + # All available Hugo versions are listed here: https://gitlab.com/pages/hugo/container_registry + image: registry.gitlab.com/pages/hugo/hugo_extended:latest + + variables: + GIT_SUBMODULE_STRATEGY: recursive + + test: + script: + - hugo + except: + - master + + pages: + script: + - hugo + artifacts: + paths: + - public + only: + - master + ``` + +#### Fais un *commit* sur les changements + +![Click on commit button](img/gitlab-commit-gitlab-ci.png) + +## Création du site web Hugo en local + +### Création du site + +``` +hugo new site my-website +``` +Cette commande va créer tout l'arborescence nécessaire à Hugo dans le dossier `./my-website`. + +### Modification du `config.toml` + +Edit at least `url` to reflect the adress where it will be deployed by gitlab pages. +If your project is located at `https://gitlab.com/myuser/agroup/myproject`, then +your website will be deployed at `https://myuser.gitlab.io/agroup/myproject`. + +Ajouter les éléments suivants à votre `config.toml`: + ``` + baseurl = "https://myuser.gitlab.io/agroup/myproject/" + title = "My website title" + author = "Le Garage Numérique" + [params] + description = "A description for my website, that can be used on front page." + favicon = "favicon.ico" + logo = "my-logo.png" + ``` + + + +### Création de la home page + +#### Création avec hugo + +``` +hugo new _index.md +``` +A new file is created at `content/_index.md` + +#### Modification + +``` +--- +title: "Mon super contenu" +date: 2020-12-08T00:13:21+01:00 +draft: true +--- + +Ceci est le contenu de la home page pour mon site web +``` +La partie encadrée entre `---` s'appelle le **front matter**, il s'agit de méta-données utilisées pour le déploiement du site. + +#### Création des templates + +Dans le dossier `layouts` on créé l'arborescence suivante: + ``` + ├── _default + │ ├── baseof.html + ├── partials + | ├── head.html + | ├── header.hmtl + | ├── footer.html + └── index.html + ``` + + +!!! note "**layouts/index.html**" + === "Contenu" + ``` + {% raw %} {{define main}} {% endraw %} + {% raw %} {{end}} {% endraw %} + ``` + === "Explication" + Il s'agit d'un template spécifique à la page d'accueil. + On appelle le template `layouts/default/baseof.html` avec la directive `{% raw %} {{define main}} {% endraw %}` + +!!! note "**layouts/default/baseof.html**" + === "Contenu" + ``` + + + {% raw %}{{- partial "head.html" . -}}{% endraw %} + + + {% raw %}{{- partial "header.html" . -}}{% endraw %} + {% raw %}{{- block "main" . }}{{- end }}{% endraw %} + {% raw %}{{- partial "footer.html" . -}}{% endraw %} + + + + ``` + === "Explication" + On appelle le partial `head.html`, puis on créé le `body` avec les partials `header.html` et `footer.html` . + Le bloc central, "main", sera construit à partir de chaque page. + +!!! note "**layouts/partials/head.html**" + === "Contenu" + ``` + {% raw %} + + + + + {{ $.Site.Title }} - {{ .Title }} + + + + {{ hugo.Generator }} + + + {% endraw %} + ``` + === "Explication" + C'est ici qu'on placera notamment les informations de référencement **SEO**. + Entre double-accolades, on appelle des variables. + Quand celles-ci commencent par `$.Site.Params`, il s'agit des variables définies dans la rubrique [params] de `config.toml` + + +!!! note "**layouts/partials/header.html**" + === "Contenu" + ``` + header + ``` + === "Explication" + This is why. + +!!! note "**layouts/partials/footer.html**" + === "Contenu" + ``` + footer + ``` + === "Explication" + This is why. + + +``` +``` +``` +``` +``` +``` +``` +``` +``` +``` +``` +``` +``` +``` +``` +``` \ No newline at end of file diff --git a/docs/divers/devops/hugo.md b/docs/divers/devops/hugo/hugo_from_templates.md similarity index 98% rename from docs/divers/devops/hugo.md rename to docs/divers/devops/hugo/hugo_from_templates.md index 07506efc..b917f061 100644 --- a/docs/divers/devops/hugo.md +++ b/docs/divers/devops/hugo/hugo_from_templates.md @@ -1,5 +1,9 @@ # Déployer un site web statique avec Hugo +## Installer Hugo + +Utilisez le tutoriel de la même rubrique: [installer hugo](install_hugo.md) + ## Création du projet sur Gitlab ### Création d'un nouveau projet diff --git a/docs/divers/devops/hugo/img/blank-project.png b/docs/divers/devops/hugo/img/blank-project.png new file mode 100644 index 00000000..ba01a1c4 Binary files /dev/null and b/docs/divers/devops/hugo/img/blank-project.png differ diff --git a/docs/divers/devops/img/choose-hugo-template.png b/docs/divers/devops/hugo/img/choose-hugo-template.png similarity index 100% rename from docs/divers/devops/img/choose-hugo-template.png rename to docs/divers/devops/hugo/img/choose-hugo-template.png diff --git a/docs/divers/devops/hugo/img/gitlab-commit-gitlab-ci.png b/docs/divers/devops/hugo/img/gitlab-commit-gitlab-ci.png new file mode 100644 index 00000000..a3c3f6a3 Binary files /dev/null and b/docs/divers/devops/hugo/img/gitlab-commit-gitlab-ci.png differ diff --git a/docs/divers/devops/hugo/img/gitlab-new-file.png b/docs/divers/devops/hugo/img/gitlab-new-file.png new file mode 100644 index 00000000..26eaf64f Binary files /dev/null and b/docs/divers/devops/hugo/img/gitlab-new-file.png differ diff --git a/docs/divers/devops/img/new-project.png b/docs/divers/devops/hugo/img/new-project.png similarity index 100% rename from docs/divers/devops/img/new-project.png rename to docs/divers/devops/hugo/img/new-project.png diff --git a/docs/divers/devops/hugo/index.md b/docs/divers/devops/hugo/index.md new file mode 100644 index 00000000..f213ccf7 --- /dev/null +++ b/docs/divers/devops/hugo/index.md @@ -0,0 +1,5 @@ +# Guides pour Hugo + +- [Installer Hugo](install_hugo.md) +- [Déployer un site web avec Hugo, à l'aide des templates](hugo_from_templates.md) +- [Déployer un site web avec Hugo, *from scratch*](hugo_from_scratch.md) \ No newline at end of file diff --git a/docs/divers/devops/hugo/install_hugo.md b/docs/divers/devops/hugo/install_hugo.md new file mode 100644 index 00000000..ace83af1 --- /dev/null +++ b/docs/divers/devops/hugo/install_hugo.md @@ -0,0 +1,41 @@ + +## Installer les dépendances + +``` +sudo apt update +sudo apt install curl wget git +``` + +## Installer hugo + +### Download the last version + +``` +curl -s https://api.github.com/repos/gohugoio/hugo/releases/latest \ + | grep browser_download_url \ + | grep Linux-64bit.deb \ + | grep -v extended \ + | cut -d '"' -f 4 \ + | wget -i - +``` + +### Install it +``` +sudo dpkg -i hugo*_Linux-64bit.deb +``` + +## Run hugo + +``` +hugo --help +``` + +## Ressources + +You can also follow these tutorials : + - [Utiliser des templates](hugo_from_templates.md) + - [Build a hugo website from scratch](hugo_from_scratch.md) + +Or those great ressources online : + - [Course on mikedane.com](https://www.mikedane.com/static-site-generators/hugo/) + - [Official doc](https://gohugo.io/documentation/) \ No newline at end of file diff --git a/docs/divers/devops/index.md b/docs/divers/devops/index.md index a09d4533..19dda24d 100644 --- a/docs/divers/devops/index.md +++ b/docs/divers/devops/index.md @@ -1,5 +1,5 @@ # Guides Devops -- [Déployer un site web avec Hugo](hugo.md) +- [Utiliser Hugo, un Générateur de Sites Statiques (SGG) en Go](hugo/index.md) - [Keycloak as SSO for Nextcloud](sso/index.md) - [Utiliser Gitpod avec Gitlab](gitpod.md) diff --git a/mkdocs.yml b/mkdocs.yml index 8f8216d6..2e4228c0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -101,7 +101,11 @@ nav: - "Calcul Réseau": divers/server/calculer-adresses-reseau.md - "DevOps": - divers/devops/index.md - - "Hugo": divers/devops/hugo.md + - "Hugo": + - "Guides Hugo": divers/devops/hugo/index.md + - "Installer Hugo": divers/devops/hugo/install_hugo.md + - "Utiliser les templates": divers/devops/hugo/hugo_from_templates.md + - "*Build from scratch*": divers/devops/hugo/hugo_from_scratch.md - "Keycloak SSO": - divers/devops/sso/index.md - divers/devops/sso/sso-ldap.md