Menu

Menus allow you to describe the site navigation structure in a simple declarative way. Menus come in two steps:

  1. Defining a menu.md file that contains the menu structure for the directory it's in.
  2. Using the useContent() function to retrieve the menu structure in a template for rendering. Read more here

File Structure

First layout files as follows:

src/
└── routes/
    └── some/
        ├── menu.md
        ├── layout.tsx
        └── path/
            └── index.tsx  # https://example.com/some/path

Navigating to https://example.com/some/path activates:

  • src/routes/some/path/index.tsx: This component will be used for rendering the page content.
  • src/routes/some/layout.tsx: This layout will be used to provide content around the src/routes/some/path/index.tsx. Internally the layout can use src/routes/some/menu.md to render the menus.
  • src/routes/some/menu.md: This file will be used to declare the menu structure which will be rendered by src/routes/some/layout.tsx.

Declaring Menu Structure

Use menu.md to declare the menu structure.

  • Use the headings (#, ##, etc..) to define menu depth
  • Use the bulleted list (-) to define menu items.
src/route/some/menu.md
# Docs
 
## Getting Started
 
- [Introduction](introduction/index.md)
 
## Components
 
- [Basics](/docs/(qwik)/components/basics/index.mdx)

Retrieving Menu Structure

At runtime, any component can retrieve the menu with useContent() hook. The type returned is ContentMenu.

The example above will return:

{
  text: "Docs",
  items: [
    {
      text: "Getting Started",
      items: [
        {
          text: "Introduction",
          href: "/docs/introduction"
        }
      ],
    },
    {
      text: "Components",
      items: [
        {
          text: "Basics",
          href: "/docs/(qwik)/components/basics"
        }
      ],
    },
  ],
}

Using ContentMenu in a layout

While useContent() can be invoked from any component that is part of the current route. It is typically used in a layout component (or a component used by layout) to render the menu. An example usage is shown here:

import { component$ } from '@builder.io/qwik';
import { useLocation, useContent } from '@builder.io/qwik-city';
export default component$(() => {
  const { menu } = useContent();
  const { url } = useLocation();
 
  return (
    <nav class="menu">
      {menu
        ? menu.items?.map((item) => (
            <>
              <h5>{item.text}</h5>
              <ul>
                {item.items?.map((item) => (
                  <li>
                    <a
                      href={item.href}
                      class={{
                        'is-active': url.pathname === item.href,
                      }}
                    >
                      {item.text}
                    </a>
                  </li>
                ))}
              </ul>
            </>
          ))
        : null}
    </nav>
  );
});

Contributors

Thanks to all the contributors who have helped make this documentation better!

  • manucorporat
  • adamdbradley
  • the-r3aper7
  • Oyemade
  • mhevery
  • nnelgxorz
  • jakovljevic-mladen
  • cunzaizhuyi
  • AnthonyPAlicea