Documentation du Crieur

Votre site généré, il revient à vous de le mettre en ligne sur l'instance Git et serveur qui correspond à vos besoins, valeurs, etc. Nous vous recommandons l'instance GitLab d'Huma-Num, qui nécessite toutefois une demande d'autorisation au préalable via https://humanid.huma-num.fr/. Alternativement, l'instance Git de l'association Framasoft : https://framagit.org/users/sign_up, qui demande aussi une autorisation mais dont le délai est moins long.

Spécification de l'URL et des templates

Le Crieur va générer par défaut du HTML/CSS/JS dans le dossier public où vous avez lancé la génération avec la ligne de commande, au travers de la commande build. Vous pouvez déposer ce dossier sur n’importe quel hébergeur mais cela implique qu'il vous faudra avoir dans le fichier de configuration .toml l’option base-url activée, et dans laquelle vous spécifiez entre guillemets l'URL racine de votre site (par exemple "https://crieur.org", ou celui de votre page générée avec GitLab pages).

N'oubliez pas de placer les dossiers templates/ et statics/ également sur le dépôt en ligne si vous avez personnalisé votre site et de bien y rediriger depuis le fichier de configuration .toml en racine du dépôt.

Déployer avec Git Pages

Sur votre dépôt Git public créé pour accueillir votre site fait avec le Crieur, il vous faut activer certains paramètres et, pour GitLab Pages, y placer un fichier d'intégration continue intitulé .gitlab-ci.yml (intitulé précisément ainsi, et en n'oubliant pas le . au début du titre du fichier).

Pour les paramètres, en ce qui concerne le GitLab d'HumaNum ou Framagit, il faut aller dans "général", sous-section "visibilité", activez "pages" et l'option "tout le monde" pour que ce soit visible par tous le monde (pas seulement les membres du dépôt). Pour GitHub, il faut aller dans les paramètres du repo, chercher "Pages", et ajouter déploiement depuis la branche et le dossier "/docs" (cela implique de renommer le dossier "public" en "docs", dans ce cas, et de rediriger le target-path à "docs" dans le fichier de configuration .toml).

Pour le fichier d'intégration continue pour les dépôts GitLab, vous pouvez y placer et adapter ce code minimaliste d'intégration continue, ce qui permettra de déployer en ligne les contenus dans public de votre branche principale :

image: alpine:latest
stages:
  - deploy
pages:
  stage: deploy
  script:
  - echo 'La magie...'
  artifacts:
    paths:
    - public
  only:
  - main

Automatisation de la génération et du déploiement

Si vous souhaitez automatiser la génération et le déploiement de votre site sur Gitlab Pages, vous pouvez vous inspirer du fichier .gitlab-ci.yml du dépôt du Crieur, jusqu’à la ligne - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH inclue, en pensant bien à modifier le titre du fichier documentation.toml au nom de votre propre fichier de configuration (et à modifier l’URL de la commande echo à celui de votre site).

Avec un tel fichier d'intégration continue, qui comprend les commandes du Crieur pour importer les corpus Stylo et les mettre en forme selon les configurations spécifiées, il vous suffit de relancer le "job" sur l'interface en ligne de GitLab pour le mettre à jour à partir de modifications sur Stylo, sans besoin de passer par la ligne de commande et la génération du site en local, sur sa machine !