(Acest articol a fost publicat pentru prima dată pe Rtaskși a contribuit cu drag la R-Bloggers). (Puteți raporta problema despre conținutul de pe această pagină aici)
Doriți să vă împărtășiți conținutul pe R-Bloggers? Faceți clic aici dacă aveți un blog sau aici dacă nu.
Puteți citi postarea originală în formatul său original pe site -ul RTASk de către Thinkr aici: Personalizați expediția: Crearea unei documentații unice pentru pachetul dvs. R
Ah, pkgdown … acel instrument fantastic care transformă documentația pachetului R într -un site web. Dar uneori, îi lipsește un pic de personalitate. Nu vă faceți griji, pkgdown.yml este aici pentru a adăuga personalizare și a face site -ul dvs. să strălucească ca niciodată.
În acest articol, vom explora câteva secrete ale pkgdown.yml fișier care vă va ajuta să vă personalizați documentația.
Sunteți gata pentru aventură? Să mergem!
🔨 Fără pachet la îndemână? Nici o problemă!
Puteți crea rapid unul cu pachetul {FUSEN}: https://thinkr-open.github.io/fusen/articles/how-to-use-fusen.html
Pregătiți -vă expediția: inițializarea pkgdown
Înainte de a vă scufunda în personalizarea documentației dvs., să nu uităm de elementele de bază. În primul rând, inițializează proiectul PKGDown rulând următoarea comandă:
usethis::use_pkgdown()
Aceasta creează structura de bază necesară pentru documentația pachetului.
Odată ce acest lucru se face, puteți genera site -ul dvs. de documentare folosind:
pkgdown::build_site()
Puteți specifica directorul în care site -ul dvs. va fi generat, de exemplu, în inst/site folderul pachetului dvs .:
pkgdown::build_site(override = list(destination = "inst/site"))
În această etapă, site -ul dvs. arată ca toate celelalte:
Acum, sunteți gata să îl personalizați pentru a -l face unic și pentru a reflecta stilul dvs.
Navigați în stil: personalizați -vă călătoria!
NAVBAR -ul documentației dvs. este punctul de plecare al aventurii dvs.
Vrei ca utilizatorii să se simtă ca exploratori, dar cu o hartă bine desenată pentru a evita să se piardă!
Iată cum să personalizați navigarea site -ului dvs. prin intermediul pkgdown.yml fişier:
Structura:
Fiecare articol menționat în structură (de exemplu, acasă, referință, expediții, știri) corespunde unei componente NavBar pe care trebuie să le definiți apoi cu textul și linkul său (HREF).
Alegeți pașii esențiali ai explorării voastre!
navbar: structure: left: (home, reference, expeditions, news) right: (github)
Componente Navbar:
După ce structura este definită, trebuie să specificați textul și link -ul (HREF) pentru fiecare articol Navbar.
text: Definește eticheta care va apărea în bara de navigare.href: Corespunde calea de fișier la care se indică legătura.
De asemenea, puteți adăuga submeniuri organizând linkurile dvs. sub același articol.
navbar: structure: left: (home, reference, expeditions, news) right: (github) components: home: text: "Explorers' Home" href: index.html reference: text: "Backpack Contents" href: reference/index.html expeditions: text: "Expeditions" menu: - text: "Absolute Beginner" href: explorations/absolute_beginner.html - text: "Beginner" href: explorations/beginner.html - text: "Intermediate" href: explorations/intermediate.html - text: "Advanced" href: explorations/advanced.html news: text: "News" href: news/index.html
Aici, creați un submeniu în cadrul „Expedițiilor” cu link -uri către articole pentru niveluri absolute pentru începători, începători, intermediari și avansați, corespunzătoare vinietelor din pachetul dvs.
Acesta este un mod simplu de a face site -ul dvs. mai intuitiv și mai accesibil, indiferent de nivelul utilizatorilor dvs.
💡 Sfat:
Puteți utiliza „Text: ——-” pentru a adăuga o linie separatoare în meniul dvs.
Acest lucru poate fi util pentru gruparea vizuală a diferitelor articole.
expeditions: text: "Expeditions" menu: - text: "Absolute Beginner" href: explorations/absolute_beginner.html - text: "Beginner" href: explorations/beginner.html - text: ------- - text: "Intermediate" href: explorations/intermediate.html - text: ------- - text: "Advanced" href: explorations/advanced.html
Secțiunea de referință: clasificați -vă funcțiile ca un ghid de expertiză
În documentația dvs., probabil că aveți o multitudine de funcții de prezentat, cum ar fi un echipament esențial pentru o expediție.
Cu {pkgdown}, puteți organiza strategic funcțiile dvs., astfel încât utilizatorii să știe exact ce să împacheteze.
Iată cum vă puteți structura funcțiile pe baza utilității lor în timpul expediției:
reference: - title: "Essentials" desc: "The essential tools you cannot forget in your backpack." contents: - map_and_compass - first_aid_kit - title: "If You Have Space" desc: "Additional tools to take if your backpack is large enough." contents: - camera - title: "Extras for Experts" desc: "Special equipment reserved for experienced adventurers looking to maximize exploration." contents: - hiking_poles - emergency_phone
title: Dați un titlu fiecărei categorii de funcții, cum ar fi „Esențial” sau „dacă aveți spațiu”.desc: O scurtă descriere pentru fiecare categorie pentru a informa utilizatorii dvs. despre ceea ce vor găsi în interior.contents: Lista funcțiilor care aparțin acestei categorii.
⚠️ Va trebui să vă asigurați că această listă de funcții este păstrată la zi, astfel încât site -ul dvs. să rămână funcțional și cuprinzător.
Schimbați starea de spirit cu o temă de bootstrap
Site-ul dvs. PKGDown ar putea fi bine structurat, dar ar putea să nu aibă un pic de emoție pentru expediție?
Vești bune: o puteți reîmprospăta cu ușurință schimbând tema Bootstrap.
PKGDown acceptă nativ temele bootswatch-variante de utilizare care vă permit să vă adaptați site-ul într-o clipă.
De exemplu, pentru a schimba aspectul implicit pentru tema Minty, pur și simplu adăugați acest lucru _pkgdown.yml:
template: bootstrap: 5 params: bootswatch: minty
Explorați temele disponibile de bootstrap: https://bootswatch.com/
Mergeți și mai departe: adăugați culori la expediție (CSS)
Dacă doriți și mai multă personalizare pentru a face site -ul dvs. unic, adăugați o notă personală cu CSS.
Plasați un extra.css Fișier în pachetul dvs. pkgdown/ pliant. Acesta va fi automat inclus în site -ul dvs. web.
De exemplu:
/* Navigation bars */
.navbar {
background-color: #0057b8 !important; /* Dark blue background for the navbar */
}
.navbar a {
color: white !important; /* Links in white */
font-weight: bold; /* Links in bold */
}
.navbar .nav-item.dropdown > .nav-link {
color: #f0f0f0; /* White text for the item with sub-menu */
font-weight: bold; /* Text in bold */
}
.navbar .dropdown-menu {
background-color: #003f7f; /* Dark blue background for the sub-menu */
border-radius: 5px; /* Round the corners of the sub-menu */
}
.navbar .dropdown-item {
color: #f0f0f0; /* Text color for the sub-menu items */
font-weight: bold; /* Bold text for better readability */
}
💡 Sfat: nu uitați să adăugați pkgdown/ Folder către .RBuildignOre pentru a evita o notă la verificați pachetul.
Îndreptându -vă spre noi aventuri!
Și acolo îl ai, călătoria ta în lumea lui {pkgdown} se apropie de sfârșit … sau mai bine zis, este începutul unei noi aventuri! Cu aceste sfaturi, documentația dvs. nu va mai fi o hartă sfâșiată, ci un Ghid adevărat, personalizat pentru exploratorii dvs. de cod.
Cu un pic de personalizare, stil și o notă de originalitate, site -ul dvs. devine mult mai mult decât un manual tehnic: este o invitație de a explora pentru utilizatorii dvs. Deci, apucați -vă pkgdown.ymlechipează -te cu cea mai bună paletă de culori și pornește pentru a cuceri vârfurile documentației!
Pentru a merge mai departe: https://pkgdown.r-lib.org/index.html
Această postare este mai bine prezentată pe site -ul său original Thinkr aici: personalizați expediția: Crearea unei documentații unice pentru pachetul dvs. R
