Ah, pkgdown… Ce fantastique outil qui transforme la documentation de votre package R en un site web. Mais parfois, il manque un peu de personnalité. Pas de panique, pkgdown.yml est là pour ajouter de la personnalisation et faire briller votre site comme jamais.
Dans cet article, nous allons explorer ensemble quelques secrets du fichier pkgdown.yml qui vous permettront de personnaliser votre documentation.
Prêt(e) pour l’aventure ? C’est parti !
🔨 Pas de package sous la main, pas de soucis !
Vous pouvez rapidement en créer un avec le package {fusen} https://thinkr-open.github.io/fusen/articles/How-to-use-fusen.html
Préparez votre expédition : Initialisation du pkgdown
Table des matières
Avant de plonger dans la personnalisation de votre documentation, n’oublions pas les étapes de base. Tout d’abord, initialisez votre projet pkgdown en exécutant la commande suivante :
usethis::use_pkgdown()Cela crée la structure de base nécessaire à la documentation de votre package.
Une fois cela fait, vous pouvez générer votre site de documentation en utilisant :
pkgdown::build_site()Vous pouvez préciser le répertoire dans lequel sera généré votre site, par exemple dans le dossier inst/site de votre package :
pkgdown::build_site(override = list(destination = "inst/site"))À ce stade votre site ressemble à tous les autres :
Maintenant, vous êtes prêts à le personnaliser pour qu’il soit unique et à votre image.
Naviguer avec style : Personnalisez votre parcours !
La navbar de votre documentation est le point de départ de l’aventure.
Vous voulez que les utilisateurs se sentent comme des explorateurs, mais avec une carte bien tracée pour ne pas se perdre !
Voici comment personnaliser la navigation de votre site au travers du fichier pkgdown.yml :
Structure :
La structure de la barre de navigation permet de définir l’ordre et la disposition des éléments de votre menu. Par exemple, vous pouvez choisir d’afficher certains liens à gauche (comme l’accueil, les références et les actualités) et d’autres à droite (comme un lien vers votre dépôt GitHub).
Chaque élément mentionné dans structure (ex. home, reference, expeditions, news) correspond à un composant de la navbar que vous devez ensuite définir avec son texte et son lien (href).
À vous de choisir les étapes essentielles de votre exploration !
navbar:
structure:
left: [home, reference, expeditions, news]
right: [github]Composants de la navbar :
Une fois la structure définie, vous devez spécifier le texte et le lien (href) de chaque élément de la navbar.
text: définit le libellé qui apparaîtra dans la barre de navigation.href: correspond au chemin du fichier vers lequel pointe le lien.
Vous pouvez également ajouter des sous-menus en organisant vos liens sous un même élément.
navbar:
structure:
left: [home, reference, expeditions, news]
right: [github]
components:
home:
text: "Accueil des explorateurs"
href: index.html
reference:
text: "Contenu du sac à dos"
href: reference/index.html
expeditions:
text: "Expéditions"
menu:
- text: "Grand Débutant"
href: explorations/grand_debutant.html
- text: "Débutant"
href: explorations/debutant.html
- text: "Intermédiaire"
href: explorations/intermediaire.html
- text: "Avancé"
href: explorations/avance.html
news:
text: "Nouveautés"
href: news/index.htmlIci, vous créez un sous-menu dans “Expéditions” avec des liens vers des articles Grand Débutant, Débutant, Intermédiaire et Avancé, qui correspondant à des vignettes de votre package.
C’est un moyen simple de rendre votre site plus intuitif et accessible, peu importe le niveau de vos utilisateurs.
💡 Astuce :
Vous pouvez utiliser “text: ——-” pour ajouter une ligne de séparation dans votre menu.
Cela peut être utile pour regrouper visuellement différents articles
expeditions:
text: "Expéditions"
menu:
- text: "Grand Débutant"
href: explorations/grand_debutant.html
- text: "Débutant"
href: explorations/debutant.html
- text: -------
- text: "Intermédiaire"
href: explorations/intermediaire.html
- text: -------
- text: "Avancé"
href: explorations/avance.html
La section reference : Catégorisez vos fonctions comme un guide expérimenté
Dans votre documentation, vous avez probablement une multitude de fonctions à présenter, comme par exemple les choses à prévoir pour une prochaine expéditions.
Avec {pkgdown}, vous pouvez organiser vos fonctions de manière stratégique, en les classant de manière à ce que les utilisateurs sachent exactement quoi emporter.
Voici comment vous pouvez structurer vos fonctions selon leur utilité pendant l’expédition :
reference:
- title: "Indispensables"
desc: "Les outils essentiels que vous ne pouvez pas oublier dans votre sac à dos."
contents:
- carte_et_boussole
- trousse_de_secours
- title: "Si vous avez de la place"
desc: "Les outils supplémentaires à emporter si votre sac est suffisamment grand pour les contenir."
contents:
- appareil_photo
- title: "Extras pour les experts"
desc: "Les équipements spéciaux réservés aux aventuriers expérimentés qui cherchent à maximiser leur exploration."
contents:
- batons_marche
- telephone_durgencetitle: Vous donnez un titre à chaque catégorie de fonctions, comme “Indispensables” ou “Si vous avez de la place”.desc: Une petite description pour chaque catégorie, histoire d’informer vos utilisateurs de ce qu’ils vont trouver à l’intérieur.contents: La liste des fonctions qui appartiennent à cette catégorie.
⚠️ Vous devrez veiller à maintenir cette liste de fonctions à jour, afin que votre site soit toujours fonctionnelle et exhaustif.
Changez d’ambiance avec un thème Bootstrap
Votre site pkgdown a beau être bien balisé, il manque peut-être un peu de peps pour motiver l’expédition ?
Bonne nouvelle : vous pouvez lui donner un coup de frais facilement en changeant le thème Bootstrap.
pkgdown supporte directement les thèmes Bootswatch, des variantes prêtes à l’emploi qui permettent d’adapter votre site en un clin d’œil.
Par exemple, pour troquer le look standard contre le thème Minty, ajoutez simplement ceci dans votre _pkgdown.yml :
template:
bootstrap: 5
params:
bootswatch: minty
Découvrer les différents thèmes bootstrap disponibles : https://bootswatch.com/
Pour aller encore plus loin : Mettez de la couleur à votre expédition (CSS)
Si vous souhaitez aller encore plus loin dans la personnalisation afin que votre site vous ressemble et non à une auberge aux couleurs standard : ajoutez une touche personnelle avec du CSS.
Déposer un fichier extra.css dans le dossier pkgdown/ de votre package. Il sera automatiquement inclus dans votre site web.
/* Barres de navigation */
.navbar {
background-color: #0057b8 !important; /* Fond bleu foncé pour la navbar */
}
.navbar a {
color: white !important; /* Liens en blanc */
font-weight: bold; /* Liens en gras */
}
.navbar .nav-item.dropdown > .nav-link {
color: #f0f0f0; /* Texte blanc pour l'item avec sous-menu */
font-weight: bold; /* Texte en gras */
}
.navbar .dropdown-menu {
background-color: #003f7f; /* Fond bleu foncé pour le sous-menu */
border-radius: 5px; /* Arrondir les coins du sous-menu */
}
.navbar .dropdown-item {
color: #f0f0f0; /* Couleur du texte des éléments du sous-menu */
font-weight: bold; /* Texte en gras pour plus de lisibilité */
}
💡 Astuce : Pensez à ajouter le dossier pkgdown/ dans votre .Rbuildignore pour éviter une NOTE lors du check de votre package.
Cap sur de nouvelles aventures !
Et voilà, votre expédition dans l’univers de {pkgdown} touche à sa fin… ou plutôt, c’est le début d’une nouvelle aventure ! Grâce à ces astuces, votre documentation ne sera plus une simple carte froissée, mais un véritable guide taillé sur mesure pour vos explorateurs de code.
Avec un peu de personnalisation, de style et une touche d’originalité, votre site devient bien plus qu’un manuel technique : c’est une invitation au voyage pour vos utilisateurs. Alors, à vos pkgdown.yml, équipez-vous de votre plus belle palette de couleurs, et partez conquérir les sommets de la documentation !
Pour aller plus loin : https://pkgdown.r-lib.org/index.html
