Navigation Components

User Guide → Navigation Components

Navigation Components

The components in this page are used for scaffolding site and page navigation.

While the main use case for dropdowns is under navbars, they can also be used as top-level components.

CODE:

<!--Notice how header attribute supports inline MarkDown-->
<dropdown header="*Action*" type="primary">
  <li><a href="#dropdown" class="dropdown-item">Action</a></li>
  <li><a href="#dropdown" class="dropdown-item">Another action</a></li>
  <li><a href="#dropdown" class="dropdown-item">Something else here</a></li>
  <li role="separator" class="dropdown-divider"></li>
  <li><a href="#dropdown" class="dropdown-item">Separated link</a></li>
</dropdown>

<!-- For segmented dropdown, ignore header and add a "before" slot -->
<dropdown type="info">
  <button slot="before" type="button" class="btn btn-info">Segmented</button>
  <li><a href="#dropdown" class="dropdown-item">...</a></li>
</dropdown>

<!-- Right aligned list -->
<dropdown header="Right aligned list" type="primary" menu-align-right>
  <li><a href="#dropdown" class="dropdown-item">Something else here</a></li>
</dropdown>

<!-- Inside a bootstrap button group -->
<div class="btn-group d-flex mt-3" role="group">
  <a href="#dropdown" class="btn btn-danger w-100" role="button">Left</a>
  <!-- With slots you can handle some elements as native bootstrap -->
  <dropdown class="w-100">
    <button slot="button" type="button" class="btn btn-warning dropdown-toggle w-100">
      Action
      <span class="caret"></span>
    </button>
    <ul slot="dropdown-menu" class="dropdown-menu">
      <li><a href="#dropdown" class="dropdown-item">Action</a></li>
      <li><a href="#dropdown" class="dropdown-item">Another action</a></li>
      <li><a href="#dropdown" class="dropdown-item">Something else here</a></li>
      <li role="separator" class="dropdown-divider"></li>
      <li><a href="#dropdown" class="dropdown-item">Separated link</a></li>
    </ul>
  </dropdown>
  <a href="#dropdown" class="btn btn-success w-100" role="button">Right</a>
</div>

OUTPUT:

Left
Right

Dropdowns can also be nested within each other to create multi-level submenus.

CODE:

<!-- Nest the dropdown syntax to create dropdown submenus -->
<dropdown header="*Multi-Level Dropdown*" type="primary">
  <li><a href="#dropdown" class="dropdown-item">Item</a></li>
  <li><a href="#dropdown" class="dropdown-item">Another item</a></li>
  <dropdown header="*Submenu*">
    <li><a href="#dropdown" class="dropdown-item">Item</a></li>
    <li><a href="#dropdown" class="dropdown-item">Another item</a></li>
  </dropdown>
</dropdown>

OUTPUT:

Options

Name Type Default Description
disabled Boolean false Whether Dropdown can be opened.
menu-align-right Boolean false Whether the dropdown list will be right-aligned.
header[S] String '' Dropdown button header text. (Supports inline MarkDown syntax)
type String default Supports: default, primary, danger, info, warning, success.

You may refer to this documentation regarding how you can use the Bootstrap buttons, and how to style them.

<dropdown header="Action" type="primary">
  <li><a href="#dropdown" class="dropdown-item">Action</a></li>
  <li><a href="#dropdown" class="dropdown-item">Another action</a></li>
  <li role="separator" class="dropdown-divider"></li>
  <li><a href="#dropdown" class="dropdown-item">Separated link</a></li>
</dropdown>

Search Bars

The searchbar component allows users to search all headings within any page on the site.

CODE:

<searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback"></searchbar>
<searchbar :data="searchData" placeholder="Search (Right-aligned dropdown)" :on-hit="searchCallback" menu-align-right></searchbar>

To use the searchbar within a navbar, add the following markup to your file. The searchbar can be positioned using the slot attribute for the list. The following markup adds a searchbar to the right side of the navbar with appropriate styling.

<li slot="right">
  <form class="navbar-form">
    <searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback"></searchbar>
  </form>
</li>

OUTPUT:

Enter a search term (eg. 'search bar') to see the search result dropdown.


      Options

      Name Type Default Description
      algolia Boolean false Whether the searchbar should be connected to Algolia DocSearch.
      data Array The local data source for suggestions. Expected to be a primitive array. To use MarkBind's search functionality, set this value to "searchData".
      menu-align-right Boolean false Whether the search bar's dropdown list will be right-aligned.
      on-hit Function A callback function when you click or hit return on an item. To use MarkBind's search functionality, set this value to "searchCallback".
      placeholder String '' The placeholder text shown when no keywords are entered in the search bar.

      Note: If you are using MarkBind's search functionality, then enableSearch must be set to true in site.json.

      See: User Guide: Site Configuration → enableSearch.

      Related topic: User Guide: Making the Site Searchable.

      Related topic: User Guide: Using Plugins → Algolia: Enabling Algolia DocSearch.

      <searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback" menu-align-right></searchbar>

      <li slot="right">
  <form class="navbar-form">
    <searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback"></searchbar>
  </form>
</li>

        Navbar allows visitors of your website to navigate through pages easily.

        Navbars support link highlighting; link highlighting can be customised by specifying rules.

        • Define default-highlight-on in <navbar> to specify fallback highlight rules.
        • Define data-highlight in <a> tags with the class nav-link or dropdown-item to specify individual highlight rules.

        Note: Navbars should be placed within a header file to ensure that they are correctly positioned at the top of the page, above the site navigation and page navigation menus.

        CODE:

        <navbar type="primary">
  <!-- Brand as slot -->
  <a slot="brand" href="/" title="Home" class="navbar-brand">MarkBind</a>
  <li><a href="/userGuide/components/navigation.html#navbars" class="nav-link">Highlighted Link</a></li>
  <!-- You can use dropdown component -->
  <dropdown header="Dropdown" class="nav-link">
    <li><a href="#navbars" class="dropdown-item">Option</a></li>
  </dropdown>
  <!-- For right positioning use slot -->
  <li slot="right">
    <a href="https://github.com/MarkBind/markbind" target="_blank" class="nav-link">Fork...</a>
  </li>
</navbar>

<navbar type="dark">
  <!-- Brand as slot -->
  <a slot="brand" href="/" title="Home" class="navbar-brand">MarkBind</a>
  <li><a href="/userGuide/components/navigation.html#navbars" class="nav-link">Highlighted Link</a></li>
  <!-- You can use dropdown component -->
  <dropdown header="Dropdown" class="nav-link">
    <li><a href="#navbars" class="dropdown-item">Option</a></li>
  </dropdown>
  <!-- For right positioning use slot -->
  <li slot="right">
    <a href="https://github.com/MarkBind/markbind" target="_blank" class="nav-link">Fork...</a>
  </li>
</navbar>

<navbar type="light">
  <!-- Brand as slot -->
  <a slot="brand" href="/" title="Home" class="navbar-brand">MarkBind</a>
  <li><a href="/userGuide/components/navigation.html#navbars" class="nav-link">Highlighted Link</a></li>
  <!-- You can use dropdown component -->
  <dropdown header="Dropdown" class="nav-link">
    <li><a href="#navbars" class="dropdown-item">Option</a></li>
  </dropdown>
  <!-- For right positioning use slot -->
  <li slot="right">
    <a href="https://github.com/MarkBind/markbind" target="_blank" class="nav-link">Fork...</a>
  </li>
</navbar>

        OUTPUT:

        Options

        Name Type Default Description
        type String primary Supports: primary, dark, light, none.
        default-highlight-on String sibling-or-child Supports: sibling-or-child, sibling, child, exact, none. Specifies link highlight rules for navbars.

        If you wish to further customize your navbar beyond the primary, dark, and light theme colors, specify the type="none" attribute and insert your own custom styles via the add-class attribute. You can use built-in background styles or insert your own defined CSS classes.

        Navbar Link Highlighting

        <head-bottom>
  <link rel="stylesheet" href="/css/main.css">
</head-bottom>

<header fixed>
  <navbar type="dark">
    <a slot="brand" href="/index.html" title="Home" class="navbar-brand"><img src="/images/logo-darkbackground.svg" height="20"></a>
    <li><a highlight-on="exact" href="/index.html" class="nav-link">HOME</a></li>
    <div tags="environment--ug"><li><a highlight-on="sibling-or-child" href="/userGuide/index.html" class="nav-link">USER GUIDE</a></li></div>
    <div tags="environment--dg"><li><a highlight-on="sibling-or-child" href="/devGuide/index.html" class="nav-link">DEVELOPER GUIDE</a></li></div>
    <li><a highlight-on="exact" href="/showcase.html" class="nav-link">SHOWCASE</a></li>
    <li><a highlight-on="exact" href="/about.html" class="nav-link">ABOUT</a></li>
    <li>
      <a href="https://github.com/MarkBind/markbind" target="_blank" class="nav-link"><md>:fab-github:</md></a>
    </li>
    <li slot="right">
      <form class="navbar-form">
        <searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback" menu-align-right></searchbar>
      </form>
    </li>
  </navbar>
</header>

        Highlight Options

        Name Description
        child Highlights link if URL in address bar is a child of the link. E.g foo/bar is a child of foo.
        sibling Highlights link if URL in address bar is a sibling of the link. E.g foo/bar and foo/bear are siblings.
        sibling-or-child Highlights link if URL in address bar is a sibling or child of the link.
        exact Highlights link if URL in address bar exactly matches link.
        none No highlighting.
        <navbar type="primary">
  <!-- Brand as slot -->
  <a slot="brand" href="/" title="Home" class="navbar-brand">MarkBind</a>
  <li><a href="/userGuide/components/navigation.html#navbars" class="nav-link">Highlighted Link</a></li>
  <!-- You can use dropdown component -->
  <dropdown header="Dropdown" class="nav-link">
    <li><a href="#navbars" class="dropdown-item">Option</a></li>
  </dropdown>
  <!-- For right positioning use slot -->
  <li slot="right">
    <a href="https://github.com/MarkBind/markbind" target="_blank" class="nav-link">Fork...</a>
  </li>
</navbar>

        Mobile page and site navigation menus

        The navbar component also provides access to MarkBind's site navigation and page navigation menu components if used in the page's layout. No additional setup is required!

        If you are viewing the documentation on a larger device, resize the window to see what it looks like.

        Alternatively, if you want to display in these navigation menus, the navbar is also able to "pull in" any container element with a html id of "site-nav" or "page-nav". You may refer to the layouts section for an example.

        The navbar component auto-detects if the MarkBind's navigation components or your element containers has any .
        If absent, the navigation buttons to open the menus are automatically hidden.

        Mobile navigation menu button placement

        If you wish to alter the button placement on the navbar, you may use the <site-nav-button /> and <page-nav-button /> components in the lower-navbar slot.

        By default, if the lower-navbar slot is not specified, the site and page navigation buttons are simply placed as such.

        <navbar>
  <!-- Any normal navbar items -->
  <a slot="brand" href="/" title="Home" class="navbar-brand">MarkBind</a>
  <li><a href="/userGuide/components/navigation.html#navbars" class="nav-link">Highlighted Link</a></li>
  <!-- Use slot to wrap the buttons in the lower navbar -->
  <div slot="lower-navbar" class="nav-menu-container">
    <site-nav-button />
    <page-nav-button />
  </div>
</navbar>
        Component Description
        page-nav-button Pulls any element with an identifier, id=page-nav into the menu. If no such element exists, it pulls any page navigation menu used in the layout.
        site-nav-button Pulls any element with an identifier, id=site-nav into the menu. If no such element exists, it pulls all site navigation menu components used in the layout.

        Styling the mobile page and site navigation menus

        You may also wish to style your navigation content differently on mobile view. By default, MarkBind already provides some reasonable overrides for smaller screens, applied over any styles you might have for the mobile navigation content identified above.

        Css class attached to the root navigation element
        .mb-mobile-nav {
    display: block !important;
    margin: 0 !important;
    border: none !important;
    padding: 10px !important;
    width: 100% !important;
    max-width: 100% !important;
}

        If you require greater customisation, you may simply compose the respective selectors with the .mb-mobile-nav element.

        Example

        #site-nav.mb-mobile-nav {
  /* Be sure to add the !important css rule when overriding .mb-mobile-nav's properties! */
  border: 1px solid black !important;
  /* For other properties, there is no need. */
  color: red;
}

        Refer to the layouts section to find out how to add custom css files to a page!

        A Site Navigation Menu (siteNav for short) can be used to show a road map of the main pages of your site.

        Steps to add a siteNav:

        1. Format your siteNav as an unordered Markdown list
        2. Include it under a <site-nav> element.
        3. (Optional) To make siteNav accessible on smaller screens, you can use the <site-nav-button /> component in the navbar.

        CODE:

        <site-nav>
* [**Getting Started**](/userGuide/gettingStarted.html)
* **Authoring Contents** :expanded:
  * [Overview](/userGuide/authoringContents.html)
  * [Adding Pages](/userGuide/addingPages.html)
  * [MarkBind Syntax Overview](/userGuide/markBindSyntaxOverview.html)
  * [Formatting Contents](/userGuide/formattingContents.html)
  * [Using Components](/userGuide/usingComponents.html)
</site-nav>

        OUTPUT:

        MarkBind has styles nested lists with additional padding and smaller text sizes up to 4 nesting levels. Beyond that, you'd have to include your own styles.

        Expanding menu items by default

        You can append the :expanded: to a to make it expand by default. In the example above, * Docs :expanded: will make the menu item Docs expand by default.

        A parent menu item that is also linked will not be collapsible e.g., the Search menu item in the above example.

        Page Navigation Menus

        A Page Navigation Menu (pageNav for short) a list of the current page's headings. Page navigation menus are only available for use in layouts.

        Adding a pageNav

        1. Specify the smallest heading level you want to be included within the <frontmatter> of a page with or a .

          The default level uses the headingIndexingLevel property of your site configuration file.

        2. (Optional) You may also specify a page navigation title within <frontmatter> that will be placed at the top of the page navigation menu.

        3. Position the page navigation menu within your layout using the <page-nav /> component.

        4. (Optional) To make pageNav accessible on smaller screens, you can use the <page-nav-button /> component in the navbar.

        Example In the page that you want to have page navigation, you may show only <h1> and <h2> headings in the pageNav, and set a custom pageNav title like so:

        <frontmatter>
  pageNav: 2
  pageNavTitle: "Chapters of This Page"
</frontmatter>

        Then, in your layout file, use the <page-nav /> component to position the pageNav.

        Example Example usage of the <page-nav /> component

        You can see an example of a Page Navigation Bar on the right side of this page.


        Pop-Up Components

        Other Components