MarkBind - User Guide: Navigation Components

Navigation Components

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

Dropdowns

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.

<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>

Navbars

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 sticky>
  <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 environment--combined"><li><a highlight-on="sibling-or-child" href="/userGuide/index.html" class="nav-link">USER GUIDE</a></li></div>
    <div tags="environment--dg environment--combined"><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!

Breadcrumbs

Breadcrumb components provide an easy way for readers to navigate the hierarchy of the site.

Usage

Simply include the breadcrumb component (<breadcrumb />) into the page you want and breadcrumbs for that page will be automatically generated.

You can also insert the breadcrumb component into a layout file to generate breadcrumbs for all pages using that layout.

CODE:

<breadcrumb />

OUTPUT:

››

Breadcrumb components refer to the Site Navigation for the hierarchy of pages.

Breadcrumbs will not appear if there is no Site Navigation present on the page!

<breadcrumb />

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:

Format your siteNav as an unordered Markdown list
Include it under a <site-nav> element.
(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:

Getting Started
Authoring Contents

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, * Authoring Contents :expanded: makes the menu item Authoring Contents expand by default.

<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>

print page nav as table of content

A Page Navigation Menu (pageNav for short) displays a list of the current page's headings. Page navigation menus are typically configured in layouts, but can also be utilized in individual pages.

Adding a pageNav

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.
(Optional) You may also specify a page navigation title within <frontmatter> that will be placed at the top of the page navigation menu.
Position the page navigation menu within your layout using the <page-nav /> component.
(Optional) To make pageNav accessible on smaller screens, you can use the <page-nav-button /> component in the navbar.
(Optional) To make pageNav available on print, you can position the page navigation menu on individual pages with the <page-nav-print /> component.

Additional details on printing pageNav

You can specify the location of the page navigation menu on print by using either of the following syntaxes:

<page-nav-print />
<page-nav-print></page-nav-print>
- This is useful if you want to include a custom title (or any other content) before the page navigation menu. For example, <page-nav-print>Table of Contents</page-nav-print>

You can specify multiple <page-nav-print /> components in a page and they do not have to be at the top of the page. They also do not appear when viewed on a browser.

Example In the page that you want to have page navigation printed (i.e. to serve as a table of content when viewed on PDFs), use the <page-nav-print /> component to position the pageNav like so:

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

<page-nav-print />

# Overview
Content of the page...

To view the pageNav on print, open the print preview of the page using the browser's print function.

If you are using Chrome, you can right-click on the page and select "Print" to open the print preview. You can try it out by going to our CLI Commands page and printing it.

Scroll To Top Button

The scroll-top-button component allows users to move to the top of the page.

Adding a scroll-top-button

Add <scroll-top-button></scroll-top-button> to layout file.

Options

Name	Type	Default	Description
icon^[S]	`String`	`:fas-arrow-circle-up:`	Inline MarkDown text of the icon displayed on the left.
icon-size	`String`	`lg`	Resizes the icon. Supports integer-scaling of the icon dimensions e.g. `2x`, `3x`, `4x`, etc.
bottom	`String`	`2%`	Distance from bottom edge of page.
right	`String`	`2%`	Distance from right edge of page.

<scroll-top-button
    icon=":fas-arrow-circle-up:"
    icon-size="2x"
    bottom="2%"
    right="2%"
></scroll-top-button>

Pop-Up Components

Other Components

Navigation

Dropdowns

Search Bars

Navbars

Usage

Site Navigation Menus

Page Navigation Menus

Scroll To Top Button