(lecture : 5 minutes)

Publier un README sous forme de site Web

J’ai parlé l’autre jour de mon initiative de fichier GDPR.txt. J’ai publié un site ce soir pour présenter tout ça : gdpr-txt.org. J’ai saisi l’occasion pour réfléchir à la manière la plus simple que j’avais de publier ce site. En trois mots : un fichier README, Pandoc et GitLab.

Le fichier README contient le contenu de mon site au format Markdown. C’est donc un site simple qui ne contient qu’une seule page. Pour commencer, ça me suffit amplement.

Pour le mettre en ligne, j’ai besoin de le transformer en HTML. Il existe des tas de solutions à base de générateur de sites statiques, mais je voulais un truc encore plus simple. J’ai un petit faible pour Pandoc, le couteau-suisse des convertisseurs de documents. La commande est simple :

$ pandoc --output=index.html README.md

Pandoc va lire le fichier README.md et générer un fichier index.html. On peut également préciser un template à Pandoc, afin qu’il génère un HTML plus complet :

$ pandoc --output=index.html --template=template.html README.md

Le fichier template.html n’est pas très compliqué à écrire1 :

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>GDPR.txt</title>
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <style>
            html {
                color: #2b0e44;
                font-size: 24px;
                line-height: 1.3;
                background-color: #fefcfe;
            }

            main {
                max-width: 700px;
                margin-right: auto;
                margin-left: auto;
                padding-top: 5rem;
                padding-bottom: 5rem;
            }

            a {
                color: #8445bc;
            }

            a:hover {
                color: #793aaf;
            }
        </style>
    </head>

    <body>
        <main>
            $body$
        </main>
    </body>
</html>

Notez que j’ai décidé d’embarquer un peu de CSS directement dans mon template pour éviter de m’encombrer d’un fichier supplémentaire. Ce sera un choix à revoir si le style devient plus complexe.

Il ne reste plus qu’à mettre ce HTML en ligne. Mon dépôt de code se trouve sur Framagit, une instance de GitLab. Celui-ci met à disposition un système pour publier facilement des sites statiques en ligne : GitLab Pages. Il suffit de créer un fichier .gitlab-ci.yml et de lui faire générer le site dans un répertoire nommé public/ :

---

pages:
  stage: deploy
  script:
    - apt-get update -y && apt-get install -y pandoc
    - mkdir public
    - pandoc --output=public/index.html --template=template.html README.md
  artifacts:
    paths:
      - public
  only:
    refs:
      - main

À partir de là, le site est automatiquement publié sur marienfressinaud.frama.io/gdpr-txt. Il ne me reste plus qu’à configurer mon nom de domaine pour le faire pointer vers Framagit. Mon enregistrement DNS ressemble à ça chez Gandi :

@ 10800 IN ALIAS marienfressinaud.frama.io.
_gitlab-pages-verification-code 10800 IN TXT "gitlab-pages-verification-code=90dff6058cf863ecb357ab2279e144fb"

Pas d’inquiétude : les informations sont bien entendues fournies par Framagit2.

Je suis plutôt content de cette solution. Elle ne révolutionne rien et reste technique, mais elle se met rapidement en place et m’a demandé peu de connaissances supplémentaires. J’aurais pu me passer de la partie DNS, voire également de Pandoc en écrivant directement le fichier HTML (ça m’arrive), mais j’aime le confort de rédaction du Markdown.

  1. Je l’ai tout de même légèrement simplifié par rapport à mon fichier d’origine pour des raisons de clarté. ↩

  2. Attention toutefois à l’enregistrement de vérification (le deuxième) qui est légèrement erroné dans Framagit : il faut soit ajouter un point à la fin de _gitlab-pages-verification-code.gdpr-txt.org, soit virer la dernière partie (ce que j’ai moi-même fait). Il y a moins de risque d’erreur en passant par l’interface graphique de Gandi (pour une fois). ↩