Faire une preview du wiki GitLab en local, c'est pas le truc le plus simlpe - pourtant j'ai ma solution qui se passe bien.

Parce que j’en ai eu marre de GitHub, de la main mise par Microsoft et puis pour plein de raisons qui font que je préfère aujourd’hui d’autres solutions… Je passe la plupart de mes projets perso sur GitLab. Et GitLab, il a un wiki de projet assez bien foutu, sauf pour bosser dessus en local avant de mettre en ligne.

En clair, c’est assez cool de base. Il fait un dépôt séparé, vous le cloner sur votre poste, et bosser dessus. Oui, je sais, les éditeurs savent rendre le contenu en “joli” etc.

Mais gérer la sidebar, vérifier les liens, etc. ça, c’est une tannée.

Donc, parce que j’avais besoin de vérifier un gros Wiki pour mon projet texlive-pandoc (une image OCI pour générer des documents de manière efficace…)

J’ai bossé un peu (ça m’arrive…)

Cette solution peut fonctionner avec d’autres services tels que GitHub ou Gitea, ou Forgejo. Avec, peut-être, une adaptation ou deux à faire. En tout cas, c’est OK pour GitLab.

TL;DR

Tout est dans https://gitlab.com/metal3d/easy-gitlab-local-wiki, suivez les instruction, ça revient à faire, dans votre dépôt de wiki:

# si vous n'avez pas de Makefile:
curl -O https://gitlab.com/metal3d/easy-gitlab-local-wiki/-/raw/main/Makefile
# Si vous avez déjà un Makefile:
curl -o local-server.mk https://gitlab.com/metal3d/easy-gitlab-local-wiki/-/raw/main/Makefile
# puis faire include local-server.mk dans votre Makefile

# ajoutez .caddy-tmp à votre .gitignore
grep ".caddy-tmp" .gitignore || echo ".caddy-tmp" >> .gitignore

Et enfin, lancez make ou make serve et visitez http://127.0.0.1:8080, voilà…

Cloner le wiki

Quand vous créez un “wiki” d’un projet, vous avez une option dans n’importe quelle page existante dans le menu en haut à droite.

Cela vous indique la commande pour récupérer le code entier chez vous, sur votre poste.

Maintenant, je vous explique les problèmes et la solution. Si ça vous saoule de tout lire, allez en bas de la page, y’a le contenu du Makefile à mettre dans le dépôt.

Les problèmes

Le problème c’est que je ne dois pas polluer le dépôt avec des trucs en trop. Un .gitignore mal gérer, un commit malheureux, et tout part dans le Wiki. Certes, ça ne va pas forcément apparaitre, mais quand même…

Et le second souci, c’est que je ne veux pas me battre avec une configuration à m’arracher les cheveux. Je voulais un truc simple qui fonctionne sans trop d’effort, sans installer des dépendances. Bref, un conteneur et puis voilà.

Je vais accéter un Makefile, et un .gitignore

La solution

Ma solution est de ne pas fournir autre chose qu’un Makefile, il génère un compose file et un fichier de configuration.

Je vous ai tout mis ici: https://gitlab.com/metal3d/easy-gitlab-local-wiki mais on peut quand même discuter un peu non ?

Le “compose file”, c’est pour Podman (ou Docker, mais il me prend le chou lui). Il démarre un service tout simple : Caddy. Bon sang que je l’aime ce service.

Ensuite, c’est simple : on génère un fichier index.html qui nous injecte Docsify avec un peu de paramétrage bateau.

Et le tout, dans un répertoire .caddy-tmp à ignorer une fois pour toutes.

L’idée n’est pas génialissime, c’est un bricolage qui fait très bien le job.

Avant de vous donner le contenu à copier-coller salement, je vous explique le tour de passe-passe que je fais.

Le compose file généré

Le Makefile va générer .caddy-tmp/compose.yaml qui fonctionne avec podman compose et docker compose (au moins, je pense que nerdctl compose est OK). Ce fichier montre le répertoire racine, ../, dans /srv - choix absolument arbitraire.

Il va aussi monter le fichier Caddyfile dans /etc/caddy/Caddyfile. Ce fichier va servir les pages en Markdown et un fichier index.html qui sera aussi dans .caddy-tmp (donc on ne pollue pas le wiki).

services:
  wiki-preview:
    image: docker.io/library/caddy:latest
    ports:
      - "8080:8080"
    volumes:
      - ../:/srv:Z
      - ./Caddyfile:/etc/caddy/Caddyfile:Z
    user: "${UID}:${GID}"
    userns_mode: keep-id

Le fichier Caddyfile généré

Le Makefile génère aussi .caddy-tmp/Caddyfile, et lui, il fait de la magie :

:8080 {
    root * /srv
    encode gzip

    rewrite / /.caddy-tmp/index.html
    rewrite /index.html /.caddy-tmp/index.html

    @exists file {path}
    handle @exists {
        file_server
    }

    handle {
        rewrite * /.caddy-tmp/index.html
        file_server
    }
}

Le fichier “index.html” généré

Et enfin, le Makefile génère un fichier .caddy-tmp/index.html qui charge docsify avec un peu de config.

Il n’y a rien de vraiment fou, juste le fait que je fais un alias pour la sidebar et que j’ai demandé de ne pas compiler les liens des PDF que je fournis dans la doc (cette ligne, à la limite, vous pouvez l’enlever).

J’utilise le mode history parce que je ne voulais pas de “hashtag” dans les chemins, pour simuler un comportement proche de celui de GitLab wiki.

Il faudra certainement que vous adaptiez le chargement des composants pour la coloration syntaxique hein… J’ai chargé ceux qui me servent, mais ce ne sont probablement pas ceux dont vous avez besoin.

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: 'Wiki',
      homepage: 'Home.md',
      ext: '.md',
      routerMode: 'history',
      noCompileLinks: ['.*.pdf'],
      loadSidebar: true,
      alias: {
        '/.*/_sidebar.md': '/_sidebar.md'
      }
    }
  </script>
  <script src="https://cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
	<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
	<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-latex.min.js"></script>
	<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-makefile.min.js"></script>
	<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-markdown.min.js"></script>
	<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
	<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-perl.min.js"></script>
</body>
</html>

Et donc, en démarrant podman -f .caddy-tmp/compose.yaml up, après avoir généré les fichiers, j’ai juste à naviguer vers http://127.0.0.1:8080 et le tour est joué !

Le Makefile (enfin !)

Le Makefile, que vous pouvez copier, est donc celui-ci :

CADDY_DIR = .caddy-tmp
INDEX_FILE = Home.md
RUNTIME := $(shell command -v podman > /dev/null 2>&1 && echo podman || echo docker)

serve: generate
	$(RUNTIME) compose -f $(CADDY_DIR)/compose.yaml up

generate: $(CADDY_DIR) $(CADDY_DIR)/Caddyfile $(CADDY_DIR)/index.html $(CADDY_DIR)/compose.yaml

$(CADDY_DIR):
	mkdir -p $(CADDY_DIR)

$(CADDY_DIR)/Caddyfile:
	$(file > $(CADDY_DIR)/Caddyfile,$(CADDYFILE_CONTENT))

$(CADDY_DIR)/index.html:
	$(file > $(CADDY_DIR)/index.html,$(INDEX_HTML_CONTENT))
	
$(CADDY_DIR)/compose.yaml:
	$(file > $(CADDY_DIR)/compose.yaml,$(COMPOSE_BASE))

clean-caddy:
	rm -rf $(CADDY_DIR)

define CADDYFILE_CONTENT
:8080 {
    root * /srv
    encode gzip

    rewrite / /$(CADDY_DIR)/index.html
    rewrite /index.html /$(CADDY_DIR)/index.html

    @exists file {path}
    handle @exists {
        file_server
    }

    handle {
        rewrite * /$(CADDY_DIR)/index.html
        file_server
    }
}
endef

define INDEX_HTML_CONTENT
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$$docsify = {
      name: 'Wiki',
      homepage: '$(INDEX_FILE)',
      ext: '.md',
      routerMode: 'history',
      noCompileLinks: ['.*.pdf'],
      loadSidebar: true,
      alias: {
        '/.*/_sidebar.md': '/_sidebar.md'
      }
    }
  </script>
  <script src="https://cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-latex.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-makefile.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-markdown.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-perl.min.js"></script>
</body>
</html>
endef

define COMPOSE_BASE
services:
  wiki-preview:
    image: docker.io/library/caddy:latest
    ports:
      - "8080:8080"
    volumes:
      - ../:/srv:Z
      - ./Caddyfile:/etc/caddy/Caddyfile:Z
    user: "$${UID}:$${GID}"
    userns_mode: keep-id
endef

Copiez ce Makefile dans votre dépôt wiki, et ajoutez .caddy-tmp/ dans .gitignore, et c’est tout.

Tapez la commande make et hop, visitez http://127.0.0.1:8080 et vous avez votre documentation qui marche, avec la sidebar si vous l’avez généré, etc.

Attention, le cache est souvent problématique, il faut souvent taper CTRL+Maj+R (je ne connais plus celui de Firefox) pour rafraichir en vidant le cache. Je n’ai pas trouvé de solution pour ce souci, mais ce n’est pas non plus trop dur hein.

C’est finalement plus que ça

Ce Makefile fonctionne bien pour un wiki à tester, mais en vérité, il peut fonctionner pour tout dépôt de documentation ou un minisite basé sur le Markdown. L’intérêt est surtout de ne pas laisser trainer de la configuration dans la base de contenu.

Je m’en sers fréquemment, il est inclus dans mon Makefile du wiki de texlive-pandoc, et je vous invite à l’adapter à vos besoins.

Bon j’ai tout mis dans https://gitlab.com/metal3d/easy-gitlab-local-wiki, vous pouvez suivre les instructions, ce sera plus simple que de copier-coller un bloc depuis cette page.

En espérant vous avoir donné un truc sympa…