Navigation

GuideNH builds its navigation tree from page frontmatter.

In the in-game sidebar, expanded ancestor pages stay pinned at the top while their still-visible descendants scroll underneath. Multiple expanded ancestor levels can stack at once, and each sticky row is pushed away only when its entire visible subtree scrolls out, similar to the VSCode file explorer.

Navigation Frontmatter

The navigation map controls whether a page appears in the guide tree.

navigation:
  title: Structure Preview
  parent: index.md
  position: 20
  icon: minecraft:diamond_block

Field Reference

Field	Description
`title`	Required display title
`keyword`	Optional single search keyword or alias
`keywords`	Optional list of search keywords or aliases
`parent`	Optional parent page id, resolved like a guide page link
`position`	Optional sibling ordering hint
`recommend`	Optional home-page recommendation priority; absent means the page is not shown in the Recommended panel
`priority`	Optional load priority for same-path page overrides; default `0`
`icon`	Optional single item icon; supports inline `mod:item:meta:{snbt}` tails
`icons`	Optional cycling item icons list; entries may be plain item ids with optional inline `:{snbt}` or `{id, meta?, nbt?}` maps
`icon_texture`	Optional texture icon resolved from guide assets
`icon_textures`	Optional cycling texture icon list
`required_mod`	Optional single mod id; page is hidden when this mod is not loaded
`required_mods`	Optional list of mod ids; page is hidden unless all listed mods are loaded
`excluded_mod`	Optional single mod id; page is hidden when this mod is loaded
`excluded_mods`	Optional list of mod ids; page is hidden when any listed mod is loaded

`navigation.position`

navigation.position is an optional integer used to order sibling pages in the navigation tree.

Missing position defaults to 0.
Larger values appear earlier.
If two pages have the same value, they are sorted by title alphabetically.

Search Keywords

navigation.keyword adds one search alias. navigation.keywords adds a list of aliases. Both fields can be used together; values are trimmed and duplicate values are ignored. Keyword matches use the same language analyzer and prefix matching as title and page content searches, while results continue to show the normal navigation title.

navigation:
  title: Molecular Assembler
  keyword: assembler
  keywords:
    - molecular assembler
    - autocrafting machine

Home Page Recommendations

`navigation.recommend`

navigation.recommend is an optional integer used by the home page Recommended panel.

Pages only appear in the Recommended panel when this field is present.
0 is valid.
Larger values appear earlier.
If two pages have the same value, they are sorted by title alphabetically.
The panel works at the GuidePage level, so each recommended page entry jumps directly to that page.

navigation:
  title: Steam Stage Checklist
  parent: index.md
  recommend: 0

Mod Requirements

Use required_mod or required_mods to require one or more loaded mods. Use excluded_mod or excluded_mods to hide a page when one or more incompatible mods are loaded. When a condition is not met, the page is excluded from the navigation tree and all page indices (item, category, etc.) so it cannot be found through navigation or search.

navigation:
  title: Applied Energistics Integration
  parent: index.md
  required_mod: appliedenergistics2

navigation:
  title: Multi-Mod Feature
  parent: index.md
  required_mods:
    - gregtech
    - appliedenergistics2

Both keys may be combined; the page is only shown when every listed mod is present.

Required and excluded conditions can also be combined. All required mods must be loaded and none of the excluded mods may be loaded.

navigation:
  title: Client-only Integration
  parent: index.md
  required_mod: guide_api
  excluded_mods:
    - incompatible_addon
    - legacy_addon

Load Priority

When several loaded resource packs provide the same guide page path, GuideNH reads the page frontmatter first and chooses the candidate with the highest navigation.priority.

navigation:
  title: Pack Override
  parent: index.md
  priority: 100

Rules:

missing priority is 0
values are signed Java integers up to 2147483647
higher priority wins
if priorities are equal, the later processed resource pack entry wins, matching Minecraft resource-pack override order
priority only decides between candidates for the same page path and language/fallback layer

This is useful when a mod ships a baseline guide page and a pack wants to replace it without relying only on resource-pack ordering.

Icon Sources

GuideNH chooses navigation/search icons in this order:

icon_textures if at least one texture entry is configured
icon_texture if the texture file loads successfully
icons if at least one configured item resolves successfully
icon if the item exists
no icon if neither is usable

Texture icons are read from runtime assets, so relative page-local files such as test1.png work.

Parent And Root Nodes

Omit parent to create a root node.
Set parent: index.md or any other page id to create a child node.
The parent page must exist in the same guide navigation tree.

navigation.parent uses the same namespace rules as Markdown page links:

parent: index.md and parent: ./index.md resolve inside the current page namespace.
parent: /index.md resolves from the current page namespace root.
parent: gregtech:index.md or parent: gregtech:/index.md explicitly targets another namespace.

Data-driven guides are isolated by namespace. Pages under assets/guidenh/guidenh/_en_us/... belong to guidenh:guidenh; pages under assets/gregtech/guidenh/_en_us/... belong to gregtech:guidenh. Relative parents and links never fall through to another mod's same-named page.

Category Pages

Pages can join one or more named categories using frontmatter:

categories:
  - basics
  - machines|Arc Furnace

Each entry can be either a category name or category|sort key.

Those categories are queryable through the built-in <Category name="machines" rows="3" /> tag and also auto-create hidden searchable pages such as Category:machines. GuideNH also auto-creates the hidden searchable special pages Special:AllPages and Special:Categories.

Item-Indexed Pages

Pages can register item-to-page mappings using item_id (one value) or item_ids (a list):

item_id: "minecraft:potion 16384-16462,!16386 | ae2:white_paint_ball:*"
item_ids:
  - minecraft:compass
  - minecraft:wool:*
  - "minecraft:potion 0-16,20-36,!28"
  - minecraft:iron_ore#crafting

These mappings are used by <ItemLink>. item_id is one NEI-style expression and each item_ids entry is the same kind of expression. For example, minecraft:potion 16384-16462,!16386 matches a metadata range except for 16386, while minecraft:potion 0-16,20-36,!28 combines two metadata ranges and excludes 28. ae2:white_paint_ball:* is a compatible strict all-meta mapping.

An optional #anchor suffix scrolls to a specific heading when the link is clicked. The anchor is formed by lowercasing the heading text and replacing spaces with hyphens (e.g. ## Crafting Recipe → #crafting-recipe).

Lookup behavior:

exact item + exact meta
wildcard-meta fallback if present
matching item expression

Heading Anchor Links

GuideNH supports heading anchor navigation in Markdown links and <a> tags. Anchors are derived from heading text by lowercasing and replacing spaces with hyphens.

Same-page anchor:

[Jump to Installation](#installation)
[Jump to Crafting Recipe](#crafting-recipe)

Cross-page anchor:

[See Getting Started](./getting-started.md#installation)
[Another guide](other-guide.md#usage)

Absolute path anchor (using the guide namespace, avoids relative path ambiguity in subdirectories):

[Absolute link](guidenh:other-guide.md#usage)
[Any namespace](mymods:crafting/iron.md#smelting)

The namespace:path format resolves to the guide page whose id matches namespace:path. This is identical to what relative paths resolve to, but avoids ../ navigation. The page must exist in the same guide as the link source.

Named inline anchors can also be placed with <a name="..."> in MDX:

<a name="custom-anchor" />

...content...

[Jump here](#custom-anchor)

Navigating to a link with an anchor scrolls the guide to the target heading or named anchor.

`<SubPages>`

<SubPages> renders links to navigation children.

Attributes

Attribute	Type	Default	Meaning
`id`	page id or empty string	current page	Page whose children should be listed
`alphabetical`	boolean expression	`false`	Sort children by title instead of navigation order

Examples

<SubPages />
<SubPages id="index.md" />
<SubPages id="" alphabetical={true} />

Special case: id="" lists root navigation nodes.

`<Category>`

<Category> renders links to every page in a named category.

Attributes

Attribute	Type	Default	Meaning
`name`	string	none	Category name to render
`rows`	positive integer	`3`	Number of display columns in the MediaWiki-style layout

<Category name="machines" rows="3" />

If the category is missing, GuideNH renders an inline error.

The same category also has an auto-generated hidden searchable page at Category:machines.

`<Special>`

<Special> renders one of the built-in MediaWiki-style special page listings.

Attributes

Attribute	Type	Default	Meaning
`name`	string	none	Supported values: `AllPages`, `Categories`
`rows`	positive integer	`3`	Number of display columns in the MediaWiki-style layout

<Special name="AllPages" rows="4" />
<Special name="Categories" rows="3" />

The same content is also available through the hidden searchable pages Special:AllPages and Special:Categories.

Uh oh!

Navigation

Navigation

Navigation Frontmatter

Field Reference

navigation.position

Search Keywords

Home Page Recommendations

navigation.recommend

Mod Requirements

Load Priority

Icon Sources

Parent And Root Nodes

Category Pages

Item-Indexed Pages

Heading Anchor Links

<SubPages>

Attributes

Examples

<Category>

Attributes

<Special>

Attributes

Search Result Titles

Related Pages

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

`navigation.position`

`navigation.recommend`

`<SubPages>`

`<Category>`

`<Special>`