Right, let’s talk about getting your pages onto the damn menu. You’ve built a page, you’re proud of it, and now you want people to actually find it. In static site generators, menus aren’t magical, sentient beings that automatically discover your content. You have to explicitly tell the system, “Hey, put this thing here.” The most elegant, keep-it-all-together way to do this is directly in the page’s front matter.

Think of front matter as the instruction sheet you paperclip to a document before filing it. It’s the metadata for your page, written in YAML (or TOML, or JSON), sitting right at the top between two sets of triple dashes (---). This is where you declare, “I am a page that belongs in the main navigation,” and you do it by defining a menu property.

The Basic Syntax

It’s dead simple. In the front matter of any page (.md, .html, etc.), you add a menu key. The value is typically a mapping (a dictionary) that specifies which menu you want this page to appear in and what its entry should look like.

Here’s the most common, bare-bones approach. You’re just saying, “Yep, put this in the main menu.” The system will use your page’s title for the link text and its permalink for the URL.

---
title: "My Brilliant Page"
menu:
    main:
---

But let’s be honest, the default settings often aren’t enough. You’ll want control.

Taking Control: Weight, Identifier, and Parent

Menus need order, and by default, most generators order pages alphabetically by title. This is, frankly, a terrible way to organize a navigation menu unless you’re writing a dictionary. You need to specify an order, and you do that with weight.

weight is just a number. The lower the number, the earlier (more to the left) the item appears. Items with the same weight are sorted by title. I think of it like this: negative numbers are far left, zero is your anchor, positive numbers march off to the right.

---
title: "Home"
menu:
    main:
        weight: -100 # This bad boy is going first.
---

---
title: "Contact"
menu:
    main:
        weight: 100 # This will likely be last.
---

Now, what if you’re using a menu other than main? Maybe you have a footer menu. Just change the key!

---
title: "Privacy Policy"
menu:
    footer: # This adds it to a menu called "footer"
        weight: 10
---

Here’s where it gets spicy: nested menus. To make a child item, you need to tell it who its parent is. You do this by setting a unique identifier on the parent menu item and then referring to it with parent on the child.

# In `services.md` (the parent)
---
title: "Our Services"
menu:
    main:
        identifier: services # I am declaring my ID
        weight: 20
---

# In `services/web-design.md` (the child)
---
title: "Web Design"
menu:
    main:
        parent: services # I am referencing the parent's ID
        weight: 1
---

This will generate a structure where “Web Design” appears as a dropdown or nested item under “Our Services”. The weight on the child only affects its order within that dropdown.

The Name Gotcha and Best Practices

A common head-scratcher: “Why is my link text wrong?” By default, the system uses the page’s title. But sometimes you need the menu text to be shorter or different. For this, you use name.

---
title: "Our Comprehensive Guide to Web Design in the 21st Century"
menu:
    main:
        name: "Web Design" # This is what shows in the menu.
        weight: 15
---

Best practice? Always set the name if your title is longer than 2-3 words. Navigation menus are not the place for your Pulitzer-winning headline; they are for clear, scannable labels.

Another pitfall: forgetting the structure. Your theme must be built to support the menus you’re defining. If you define a footer menu but your theme’s partials only look for the main menu, those links are going nowhere. Always check your theme’s documentation. And for heaven’s sake, keep your weight values documented in a spreadsheet or a comment in your config file. “-100 for Home, -50 for About, 10 for Blog…” It saves you from the inevitable guessing game six months from now.

This method keeps your content and its presentation neatly linked. The alternative—defining the entire menu structure in a central config file—decouples things and can be a maintenance nightmare. Trust me, telling the page itself where it lives is the cleaner, more scalable approach. You’re not just creating pages; you’re architecting a structure. Now go build one that doesn’t suck.