You can customise the navigation bar that appears at the top of the page with the navbar field. It's made up of two pieces: structure, which defines the overall layout, and components, which defines what each piece looks like. This organisation makes it easy to mix and match pkgdown defaults with your own customisations.

This is the default structure:

    left:  [intro, reference, articles, tutorials, news]
    right: [search, github]

It makes use of the the six built-in components:

[^dots]: Note that dots (.) in the package name need to be replaced by hyphens (-) in the vignette filename to be recognized as the intro. That means for a package the intro needs to be named foo-bar.Rmd.

You can use the structure field to reorganise the navbar without changing the default contents:

    left:  [search]
    right: [reference, articles]

You can use components to override the default content. For example, this yaml provides a custom articles menu:

    text: Articles
    - text: Category A
    - text: Title A1
      href: articles/a1.html
    - text: Title A2
      href: articles/a2.html
    - text: -------
    - text: "Category B"
    - text: Article B1
      href: articles/b1.html

Components uses the same syntax as RMarkdown menus. The elements of menu can be:

Instead of text, you can also use the name of an icons from fontawesome. You should also provide a textual description in the aria-label field for screenreader users.

To add a new component to the navbar, you need to modify both structure and components. For example, the following yaml adds a new "twitter" component that appears to the left of the github icon.

    right: [twitter, github]
      icon: fa-twitter
      aria-label: Twitter

Finally, you can add arbitrary HTML to three locations in the navbar:

    before_title: <!-- inserted before the package title in the header ->
    before_navbar: <!-- inserted before the navbar links -->
    after_navbar: <!-- inserted after the navbar links -->

These includes will appear on all screen sizes, and will not be collapsed into the the navbar drop down.

You can also customise the colour scheme of the navbar by using the type and bg parameters. See above for details.

Try the pkgdown package in your browser

Any scripts or data that you put into this service are public.

pkgdown documentation built on May 29, 2024, 10:27 a.m.