menus.toml

Overview

The config/_default/menus.toml file defines and populates all menu entries used in Alpha.

Alpha supports six specific menu identifiers:

• [[main]], [[main_secondary]], [[main_social]] — used in the hamburger menu
• [[footer]], [[footer_social]] — used in the footer
• [[sc_social]] — used in the social shortcode.

Usage

Menu Entry Format

# Menus
[[main]]          # Menu identifier        
  name = "Home"   # Menu entry
  url = "/"       # URL for the menu entry
  weight = 100    # Priority weight

# Social Menus
[[main_social]]                # Menu identifier
  name = "Github"              # Social name
  url = "https://github.com/"  # URL for the social entry
  pre = "#github"              # Icon for the social network
  weight = 100                 # Priority weight

Note: Menu identifiers are hardcoded, do not rename or alter them.

To disable a menu entry, either delete its keys or comment out the entire block:

# This entry will not render  
# [[main]]               
#  name = "Home"   
#  url = "/"       
#  weight = 100    

Social Menus

The pre key determines the icon shown for a social network.
If pre is omitted or contains an invalid value, the name key value is used instead.

Valid values:

# Social icon values
  pre = "#instagram"
  pre = "#tiktok"
  pre = "#twitter"
  pre = "#youtube"
  pre = "#facebook"
  pre = "#twitch"
  pre = "#reddit"
  pre = "#pinterest"
  pre = "#linkedin"
  pre = "#discord"
  pre = "#snapchat"
  pre = "#telegram"
  pre = "#bluesky"
  pre = "#mastodon"
  pre = "#github"
  pre = "#gitlab"
  pre = "#bitbucket"

Multilingual Menus

If your site is multilingual or your main language is not English, you’ll need to:

• Add translated versions of the menus.toml file, or
• Translate the default one for each language.

Otherwise, menus.toml will be used as a fallback.

To localize menus:

1. Copy menus.toml
2. Rename it to menus.[language_code].toml
3. Translate the values only, do not change the keys.

Note: The [language_code] must match the section language code defined in languages.toml.

Example:

# languages.toml
[fr]
  weight = 2
  languageName = "French"
  languageCode = "fr-CA"

# menus.fr.toml 
[[main]]              
  name = "Accueil"  
  url = "/"       
  weight = 100

Best Practices

• The original intent behind the menu design is to use [[main_secondary]] and [[footer]] for “utility pages” such as Policy, About, Contact, and similar entries.
• All menus are optional. Use only as many as your project requires.
• There is no hardcoded limit to the number of entries, but too many entries or long name values may visually break the layout.

Keys Reference

name

name = "Example"— (string, optional)

Display name of the menu entry.

url

url = "/posts/example" — (string, optional)

URL for the menu entry. Both relative and absolute URLs are supported.

weight

weight = 100 — (integer, optional)

Sets the order of the menus entries. Lower values appear first.

pre

pre = "#github" — (string, optional)

Displays a social network icon. Must use a predefined value from the list above.

Used only in [[main_social]], [[footer_social]], [[sc_social]]