Skip to main content
Deno 2 is finally here 🎉️
Learn more

lume_navbardata

A Lume plugin for developing multi-language websites. Lume is a static-site generator for the Deno JavaScript/TypeScript runtime.

lume_navbardata creates shared data for Lume projects in order to automate the generation of visual navigation bars. These navigation bars are frequently displayed on top of web pages as a set of links.

Usage

Call lume_navbardata from your Lume project’s configuration file:

// _config.ts

import lume from 'lume/mod.ts';
import lume_navbardata from 'https://deno.land/x/lume_navbardata@v1.0.4/mod.ts';

export default
lume({
  location: new URL('https://site.example'),
  src     : './src',
  dest    : './build',
})
.use(lume_navbardata());

Lume project directory structure

lume_navbardata assumes that your Lume project’s source directory contains one directory per language. The directory name must be a ISO 639-1 language code. lume_navbardata will ignore directories with a non-conforming name. Note that the names of the language directories must be lower-cased.

For example, if your source directory contains the following directories and files:

  • en
  • tr
  • assets
  • index.html

then lume_navbardata will ignore the assets directory and the index.html file.

Within a language directory, lume_navbardata assumes that each link in the navigation bar corresponds to a page in the language directory. lume_navbardata will only consider pages:

  • that have the .yaml, .yml or .njk filename extensions, and
  • whose front matter contains a nav.order entry which is an integer or floating point number that defines the display order in the navigation bar.

For example, if the en directory contains these pages:

  • documentation.yaml
  • about.njk
  • bug-fix-b2345.yaml

and if only documentation.yaml and about.njk have nav.order in their front matter, then the bug-fix-b2345.yaml page will be ignored by lume_navbardata.

Example of valid front matter:

nav:
  order: 1

Which shared data is generated?

Given the source directory structure shown above, lume_navbardata will generate the following data files:

  • en/_data/navbar.yaml
  • tr/_data/navbar.yaml

For example, en/_data/navbar.yaml will be similar to this:

- title: Documentation
  path: documentation
  order: 1
- title: About
  path: about
  order: 2

Note that:

  • in these data files both the title and the path are inferred from the page’s filename.
  • the generated data files will modify your source directory.

Using navbar data in Lume layouts

Here is how the navbar data can be used in Lume layouts for generating navigation bars:

<!DOCTYPE html>
<html lang="{{ lang.code }}">
<head>
  <!-- ... -->
</head>
<body>
  <header>
    <nav>
      <ul>
        <li>
          <a href="/{{ lang.code }}/" aria-label="Return home">
            Site name
          </a>
        </li>

        {% for item in navbar %}
        <li>
          <a 
            href="/{{ lang.code }}/{{ item.path }}/"

            {% if nav.selection == item.path %}
            class="selected"
            {% endif %}
          >
            {{ item.title }}
          </a>
        </li>
        {% endfor %}

      </ul>
    </nav>
  </header>

  <!-- ... -->
</body>
</html>

Note that:

  • pages can indicate their path in their front matter (here in the nav.selection property) so that the current item in the navigation bar can be highlighted.
  • if you wish to select the same navigation bar item for several pages then all these pages should have the same nav.selection value; for example src/docs.yaml and src/specification.yaml can both have the same nav.selection value which equals to docs, but only one of them must have a nav.order property and only a link to that page (for example src/docs.yaml) will be displayed in the navigation bar.
  • in this example lang.code isn’t generated by lume_navbardata but by another Lume plugin called lume_langdata).

License

lume_navbardata is released under the Apache 2.0 License.