You can read the original post in its original format on Rtask website by ThinkR here: Customize your expedition: Create a unique documentation for your R Package

Ah, pkgdown… That fantastic tool that turns your R package documentation into a website. But sometimes, it lacks a bit of personality. No worries, pkgdown.yml is here to add customization and make your site shine like never before.

In this article, we will explore some secrets of the pkgdown.yml file that will help you personalize your documentation.
Ready for the adventure? Let’s go!

🔨 No package at hand? No problem!
You can quickly create one with the {fusen} package: https://thinkr-open.github.io/fusen/articles/How-to-use-fusen.html

Prepare your expedition: Initializing pkgdown

Before diving into customizing your documentation, let’s not forget the basics. First, initialize your pkgdown project by running the following command:

usethis::use_pkgdown()

This creates the basic structure needed for your package documentation.
Once this is done, you can generate your documentation site using:

pkgdown::build_site()

You can specify the directory where your site will be generated, for example, in the inst/site folder of your package:

pkgdown::build_site(override = list(destination = "inst/site"))

At this stage, your site looks like all the others:

Now, you are ready to personalize it to make it unique and reflect your style.

Navigate in style: Customize your journey!

Your documentation’s navbar is the starting point of your adventure.
You want users to feel like explorers but with a well-drawn map to avoid getting lost!

Here’s how to customize your site’s navigation through the pkgdown.yml file:

Structure:

The navbar structure allows you to define the order and layout of your menu items. For example, you can choose to display some links on the left (such as home, reference, and news) and others on the right (such as a link to your GitHub repository).

Each item mentioned in the structure (e.g., home, reference, expeditions, news) corresponds to a navbar component that you must then define with its text and link (href).

Choose the essential steps of your exploration!

navbar:
  structure:
    left: [home, reference, expeditions, news]
    right: [github]

Navbar components:

Once the structure is defined, you must specify the text and link (href) for each navbar item.

• text: Defines the label that will appear in the navigation bar.
• href: Corresponds to the file path to which the link points.

You can also add submenus by organizing your links under the same item.

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

Here, you create a submenu under “Expeditions” with links to articles for Absolute Beginner, Beginner, Intermediate, and Advanced levels, corresponding to vignettes in your package.
This is a simple way to make your site more intuitive and accessible, regardless of your users’ level.

💡 Tip:

You can use “text: ——-” to add a separator line in your menu.
This can be useful for visually grouping different articles.

    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

The reference section: Categorize your functions like an expert guide

In your documentation, you probably have a multitude of functions to present, like essential gear for an expedition.
With {pkgdown}, you can strategically organize your functions so that users know exactly what to pack.

Here’s how you can structure your functions based on their utility during the expedition:

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: You give a title to each function category, such as “Essential” or “If You Have Space”.
• desc: A brief description for each category to inform your users about what they will find inside.
• contents: The list of functions that belong to this category.

⚠️ You will need to ensure that this list of functions is kept up to date, so that your site remains functional and comprehensive.

Change the mood with a Bootstrap theme

Your pkgdown site might be well-structured, but it might lack a bit of excitement for the expedition?
Good news: you can freshen it up easily by changing the Bootstrap theme.

pkgdown natively supports Bootswatch themes—ready-to-use variants that let you adapt your site in an instant.

For example, to swap the default look for the Minty theme, simply add this to your _pkgdown.yml:

template:
  bootstrap: 5
  params:
    bootswatch: minty

Explore the available Bootstrap themes: https://bootswatch.com/

Go Even Further: Add Colors to Your Expedition (CSS)

If you want even more customization to make your site unique, add a personal touch with CSS.

Place an extra.css file in your package’s pkgdown/ folder. It will automatically be included in your website.

For example :

/* 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 */
}

💡 Tip: Remember to add the pkgdown/ folder to your .Rbuildignore to avoid a NOTE when checking your package.

Heading Towards New Adventures!

And there you have it, your journey into the world of {pkgdown} is coming to an end… or rather, it’s the beginning of a new adventure! With these tips, your documentation will no longer be a crumpled map, but a true, tailor-made guide for your code explorers.

With a bit of customization, style, and a touch of originality, your site becomes much more than a technical manual: it’s an invitation to explore for your users. So, grab your pkgdown.yml, equip yourself with your best color palette, and set off to conquer the peaks of documentation!

To go further: https://pkgdown.r-lib.org/index.html

This post is better presented on its original ThinkR website here: Customize your expedition: Create a unique documentation for your R Package