| layout | title | permalink |
|---|---|---|
home |
Thème GitBook pour Jekyll |
/ |
Pour donner un look GitBook aux sites Jekyll !
Démonstration en ligne sur Github Pages: https://sighingnow.github.io/jekyll-gitbook
GitBook est un style frontend incroyable pour présenter et organiser des contenus (tels que des chapitres de livre
et blogs) sur le Web. Le processus typique pour déployer GitBook sur les pages GitHub est de compiler des fichiers HTML localement, puis de les pousser vers le référentiel Github, généralement vers la branche gh-pages. Toutefois, il est plutôt ennuyeux de répéter une telle charge de travail, et cela complique le contrôle de version via git lorsqu'il y a des fichiers HTML générés à intégrer et à supprimer.
Ce thème reprend les styles du site GitBook et fournit un modèle pour Jekyll de rendu des documents Markdown en HTML, ainsi l'ensemble du site peut être déployé sur les pages Github sans générer et télécharger le bundle HTML à chaque fois qu'il y a des modifications apportées au référentiel d'origine.
Le thème jekyll-gitbook peut être utilisé comme les autres thèmes Jekyll, et supporte la fonction thème distant (remote theme) sur les pages Github.
Vous pouvez ajouter ce thème Jekyll à votre propre site, soit:
- En créant une instance (fork) de ce référentiel et en y ajoutant vos articles rédigés en Markdown dans le dossier
_posts, puis en la poussant (push) vers votre propre référentiel GitHub. - En l'utilisant en tant que thème distant (remote theme) dans
_config.yml(comme nous le faisons pour le présent site),
remote_theme: sighingnow/jekyll-gitbookCe thème peut être exécuté localement à l'aide de Ruby et des Gemfiles.
Tester vos pages GitHub localement avec Jekyll - GitHub
La fonction de recherche dans le thème jekyll-gitbook est fournie par le module gitbook-plugin-search-pro et est activée par défaut.
https://sighingnow.github.io/jekyll-gitbook/?q=generated
La coloration syntaxique est configurable à l'aide de l'entrée suivante dans le fichier _config.yaml :
syntax_highlighter_style: colorfulLe style de coloration syntaxique par défaut est colorful, les styles supportés peuvent être trouvés dans le référentiel rouge. Des styles personnalisés peuvent être ajoutés dans ./assets/gitbook/rouge/.
Le thème jekyll-gitbook fait appel à jekyll-toc pour générer le contenu de la page.
La fonction TOC (table des matières) n'est pas activée par défaut. Pour l'utiliser, modifiez la configuration TOC
dans _config.yml :
toc:
enabled: true
h_min: 1
h_max: 3Le thème jekyll-gitbook supporte l'implémentation des outils d'analyse de traffic Google Analytics, CNZZ et Application Insights grâce à la configuration minimale suivante dans _config.yaml :
tracker:
google_analytics: "<VOTRE CLÉ GOOGLE ANALYTICS, p.e, UA-xxxxxx-x>"De la même façon, CNZZ peut être ajouté avec la configuration suivante dans _config.yaml :
tracker:
cnzz: "<VOTRE CLÉ CNZZ ANALYTICS, p.e., xxxxxxxx>"Application Insights peut être ajouté avec la configuration suivante dans _config.yaml :
tracker:
application_insights: "<VOTRE PHRASE DE CONNEXION POUR APPLICATION INSIGHTS>"Les commentaires Disqus peuvent être activés en ajoutant la configuration suivante dans _config.yaml :
disqushandler: "<VOTRE PSEUDONYME DISQUS>"Vous pouvez ajouter des styles CSS ou des références JavaScript en utilisant des collections de configuration :
- extra_css: pour les feuilles de style supplémentaires. Si l'URL ne commence pas par
httpouhttps, le chemin doit être relatif à la racine du site (sans le caractère/au début). - extra_header_js: pour les scripts supplémentaires à ajouter dans la balise
<head>, après queextra_cssait été ajouté. Si l'URL ne commence pas parhttpouhttps, le chemin doit être relatif à la racine du site (sans le caractère/au début). - extra_footer_js: pour les scripts supplémentaires à ajouter à la fin du document HTML, avant les scripts de tracking. Si l'URL ne commence pas par
httpouhttps, le chemin doit être relatif à la racine du site (sans le caractère/au début).
Les polices de caractères peuvent être personnalisées en modifiant les entrées .book.font-family-0 et .book.font-family-1 dans ./assets/gitbook/custom.css,
.book.font-family-0 {
font-family: Georgia, serif;
}
.book.font-family-1 {
font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
}Le thème jekyll-gitbook supporte les attributs personnalisés de kramdown ({: .block-tip }, {: .block-warning },
{: .block-danger }) comme ceux affichés dans le site web discord.js.
Exemple de code :
> ##### CONSEIL
>
> Ce guide a été testé avec @napi-rs/canvas^0.1.20, assurez-vous donc d'avoir
> cette version (ou similaire) après l'installation.
{: .block-tip }Le rendu peut être prévisualisé sur cette page :
https://sighingnow.github.io/jekyll-gitbook/jekyll/2022-06-30-tips_warnings_dangers.html
Le thème jekyll-gitbook supporte l'ajout d'une image de couverture à une page spécifique en ajoutant un champs cover dans les métadonnées de la page :
---
title: Page avec image de couverture
author: Tao He
date: 2022-05-24
category: Jekyll
layout: post
+ cover: /assets/jekyll-gitbook/dinosaur.gif
---Cet effet peut être prévisualisé sur cette page :
https://sighingnow.github.io/jekyll-gitbook/jekyll/2022-05-24-page_cover.html
Ce projet est en open source sous la licence Apache, version 2.0.
© 2019 Tao He.