Navigation bar

Present the project brand, artistic motif and first level navigation links.

Table of Contents

Presentation template
Configuration files
Configuration variables
Reusing navitems configuration in shortcuts
Showing navigation bar at page level
Showing navigation bar at site level
Hiding navigation bar at page level
Hiding navigation bar at site level
Related topics

Navigation bar is fixed on top of all site pages. It presents the CentOS Brand, the CentOS Motif and, first level navigation links.

Presentation template

Navigation bar presentation template is defined in the _include/base/navbar.html file.

Navigation bar presentation template doesn’t support nesting menus.

Configuration files

Navigation bar presentation template reads configuration variables from different configuration files. The first configuration file found wins and stops the reading of other configuration files. This section describes these files and their reading order.

Site’s configuration file:

_config.yml

The site’s configuration file allows you to set configuration variable on all site pages.

                  # site.defaults - Set global default values.
defaults:
  - scope:
      path: "" # an empty string here means all files in the project.
    values:
      with_navbar_data:
        navitems:
          - name: "Documentation"
            icon: "fa-solid fa-book"
            link: "/documentation"
            menu: []
            visible_on: ["navbar"]

                

By default, the with_navbar_data page configuration variable is not set in _config.yml file and the navigation bar presentation template reads the site’s data file instead.

Markdown files (i.e., pages) preamble section:

                  ---
title: Page with navbar customization data

with_navbar_data:
  navitems:
    - name: "Documentation"
      icon: "fa-solid fa-book"
      link: "/documentation"
      menu: []
      visible_on: ["navbar"]
---

Page content.

                

By default, the with_navbar_data page configuration variable is not set in markdown files and the navigation bar presentation template reads the site’s data file instead.

Site’s data files:
```
_data/{{ site.component_data_dirname }}/navbar.yml
_data/navbar.yml
```
When none of the navbar site data files exist, or is empty, the navigation bar presentation template reads the theme navbar component’s data file.
Theme component’s data file.
```
_data/base/navbar.yml
```
The theme component’s data file is always available when you build your site with jekyll-theme-centos container image. This file provides default values for navigation bar presentation template.

Example:
```
{"brand_manifestation"=>"jekyll-theme-centos-base", "navitems"=>[{"name"=>"Documentation", "icon"=>"fa-solid fa-book", "link"=>"/documentation", "menu"=>[], "visible_on"=>["navbar"]}]}
```

Configuration variables

Navigation bar configuration variables let you to control the navigation bar presentation template visibility in the page layout, the content it presents and how it presents it. The presentation order of elements inside the navigation bar presentation template cannot be changed without changing the navigation bar presentation template file.

Navigation bar configuration variables are described in the following table:

Name	Description
`with_navbar`	The navigation bar switcher. Possible values are `true` (default) or `false`.
`with_navbar_data`	The navigation bar optional configuration data. By default, it is not set. When you set this variable, it has preference over data files. See configuration files.

The with_navbar_data data structure:

              ---
navitems:
  - name: "Documentation"
    icon: "fa-solid fa-book"
    link: "/documentation"
    menu: []
    visible_on: ["navbar"]
  - name: "Menu Link 1"
    icon: "fa-solid fa-link"
    menu:
      - name: "Menu Link 1 - Simple Link 1"
        link: "#"
      - name: "Menu Link 1 - Simple Link 2"
        link: "#"
    visible_on: ["navbar","footer"]

            

Name	Description
`class`	The bootstrap customization class applied on navbar element.
`brand_image_class`	The bootstrap customization class applied on navbar brand image.
`brand_image_height`	The image height of navbar brand image.
`brand_manifestation`	The name of the visual manifestation the site is for.
`brand_manifestation_class`	The bootstrap customization class applied on visual manifestation element.
`navitems`	The navbar-items. See data structure below.

The navitems data structure:

Name	Description
`name`	The link name.
`link`	The link URL associated to the link name. Here, URLs are relative to `site.baseurl`.
`icon`	The link icon. Possible values to use here are limited to fontawesome freely distributed icons.
`visible_on`	Possible values are `["navbar"]` to present the menu only in the navigation bar, `["footer"]` to present the menu on the page footer only, and `["navbar", "footer"]` to present the menu in both navigation bar and footer elements.
`menu`	Whether the link is a menu holding other links. When the value is an empty list (e.g., `[]`), navigation bar presentation template renders a simple link. When the list is not empty it renders a menu of links. See data structure below.

The menu data structure:

Name	Description
`name`	The name of the link.
`link`	The link URL associated to the link name. Here, URLs are relative to `site.baseurl`.

Reusing navitems configuration in shortcuts

              ---
title: This is a page enables both navbar and shortcuts

with_shortcuts: true
with_navbar: true
with_navbar_data:
  navitems:
    - name: "Menu Link 1"
      icon: "fa-solid fa-link"
      menu:
        - name: "Menu Link 1 - Simple Link 1"
          link: "#"
        - name: "Menu Link 1 - Simple Link 2"
          link: "#"
      visible_on: ["navbar"]
    - name: "Menu Link 2"
      icon: "fa-solid fa-link"
      menu:
        - name: "Menu Link 2 - Simple Link 1"
          link: "#"
        - name: "Menu Link 2 - Simple Link 2"
          link: "#"
      visible_on: ["navbar", "footer"]
---

Some content here.

            

To reuse navigation bar navitems configuration in shortcuts, do the following:

Do not define the with_shortcuts_data configuration variable or set any of the shortcuts configuration files. This makes the shortcuts presentation template to read the navigation bar configuration variables instead.
Define navbar configuration variables (e.g., with_navbar_data) or navbar configuration files (e.g., _data/navbar.yml). All menu entries you define under navitems property are considered by both to navigation bar and shortcuts presentation templates.
Control visibility through visible_on property.

              ---
title: This is a page with navbar enabled and configured

with_navbar: true
with_navbar_data:
  navitems:
    - name: "Menu Link 1"
      icon: "fa-solid fa-link"
      menu:
        - name: "Menu Link 1 - Simple Link 1"
          link: "#"
        - name: "Menu Link 1 - Simple Link 2"
          link: "#"
      visible_on: ["navbar"]
---

Some content here.

            

To show navigation bar at page level, do the following:

Add with_navbar configuration variable to page preamble in Markdown files with value true.
Add with_navbar_data configuration variable to page preamble in Markdown files with navitems set to the message you want to communicate.

              # site.defaults - Set global default values.
defaults:
  - scope:
      path: "" # an empty string here means all files in the project.
    values:
      with_navbar: true
      with_navbar_data:
        navitems:
          - name: "Menu Link 1"
            icon: "fa-solid fa-link"
            menu:
              - name: "Menu Link 1 - Simple Link 1"
                link: "#"
              - name: "Menu Link 1 - Simple Link 2"
                link: "#"
            visible_on: ["footer"]

            

To show navigation bar at site level, edit site’s configuration file (e.g., _config.yml) and do the following:

Add with_navbar configuration variable with value true under defaults values.
Add with_navbar_data configuration variable with navitems, and any other supported property, under defaults values.

              ---
title: This is a page with navbar disabled

with_navbar: false
---

Some content here.

To hide navigation bar at page level, set with_navbar configuration variable to false in the page preamble of Markdown files.

              # site.defaults - Set global default values.
defaults:
  - scope:
      path: "" # an empty string here means all files in the project.
    values:
      with_navbar: false

            

To hide navigation bar at site level, set with_navbar configuration variable to false in the site configuration file _config.yml, under defaults values.