add hugo from scratch devops guide

2020-12-08 02:11:39 +01:00 · 2020-12-08 02:11:39 +01:00 · fba110010b
commit fba110010b
parent 91b8fef118
11 changed files with 248 additions and 2 deletions
--- a/docs/divers/devops/hugo/hugo_from_scratch.md
+++ 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"
+        ```
+        <!DOCTYPE html>
+        <html>
+            {% raw %}{{- partial "head.html" . -}}{% endraw %}
+
+            <body>
+                {% raw %}{{- partial "header.html" . -}}{% endraw %}
+                {% raw %}{{- block "main" . }}{{- end }}{% endraw %}
+                {% raw %}{{- partial "footer.html" . -}}{% endraw %}
+            </body>
+
+        </html>
+        ```
+    === "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 %}
+        <head>
+            <meta charset="UTF-8" />
+            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+            <meta name="robots" content="index, follow" />
+            <title>{{ $.Site.Title }} - {{ .Title }}</title>
+            <link rel="icon" href="{{ $.Site.BaseURL }}{{ $.Site.Params.favicon }}" />
+            <meta name="description" content="{{ $.Site.Params.description }}" />
+
+            {{ hugo.Generator }}
+
+        </head>
+        {% 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.
+
+
+```
+```
+```
+```
+```
+```
+```
+```
+```
+```
+```
+```
+```
+```
+```
+```
--- a/docs/divers/devops/hugo/hugo_from_templates.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
--- a/docs/divers/devops/hugo/img/blank-project.png
+++ b/docs/divers/devops/hugo/img/blank-project.png
--- a/docs/divers/devops/hugo/img/choose-hugo-template.png
+++ b/docs/divers/devops/hugo/img/choose-hugo-template.png
--- a/docs/divers/devops/hugo/img/gitlab-commit-gitlab-ci.png
+++ b/docs/divers/devops/hugo/img/gitlab-commit-gitlab-ci.png
--- a/docs/divers/devops/hugo/img/gitlab-new-file.png
+++ b/docs/divers/devops/hugo/img/gitlab-new-file.png
--- a/docs/divers/devops/hugo/img/new-project.png
+++ b/docs/divers/devops/hugo/img/new-project.png
--- a/docs/divers/devops/hugo/index.md
+++ 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)
--- a/docs/divers/devops/hugo/install_hugo.md
+++ 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/)  
--- 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)
--- 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