Skip to content

Define navigation

Every project has a navigation structure, whether you write one out or not. Without a nav list in zensical.toml or mkdocs.yml, Zensical builds one implicitly from your files and folders. Writing an explicit list instead gives you control over order, labels, and grouping, and once you do, Zensical Studio treats every path in it the same way it treats a Markdown link: it completes them, validates them, and keeps them in sync as files move.

Example project

This workflow uses the project in zensical-example-project.zip; it has no nav list yet, so it is a good starting point for adding one.

Write an explicit list

Add a nav list to zensical.toml. As you type each path, Zensical Studio completes it from the Markdown files already in your project, the same completion you get for a link target, and it works even on an empty entry, so you can trigger it before typing anything:

nav = [
    "index.md",
    "getting-started.md",
    { "Workspace settings" = "workspace-settings.md" },
    { "Automations" = "automations.md" },
    { "Notifications" = "notifications.md" },
    { "Performance" = "performance.md" },
]

Each path is a real reference to that file, not just a string. Use Find All ReferencesFind All ReferencesFind referencesFind UsagesShift+F12 on a Markdown file to see its nav entry alongside any regular links that point to it.

Rename or move a page, the nav entry follows

Rename or move a Markdown file the way you normally would, in the ExplorerExplorerProject panelProject tool window or with F2. Its nav path updates as part of the same coordinated edit that already updates Markdown links, images, snippets, and directive targets, not a separate step.

This is safe even if zensical.toml is already open with other, unsaved edits of your own: only the navigation path changes, nothing else you were in the middle of writing gets touched. Studio also holds off on reporting a missing-target diagnostic until the whole operation completes, so you never see a brief, false "broken path" warning flash up mid-rename.

Recovering a move made outside Studio

A file moved outside Studio entirely, from the command line, a Git operation, or another tool, does not get its nav entry updated at the time. Zensical Studio recovers it the next time it indexes the project, the same repair path already covered for in-content links in Catch and repair problems.

A whole directory move is recovered outright. A single moved file is recovered too, but only when Studio finds exactly one newly created file whose content exactly matches a file that went missing in the same project; if more than one file could match, or the content changed along with the move, Studio leaves the path alone rather than guessing.

Catching a broken path

A nav entry pointing at a path that does not exist, a typo, or a file that was deleted without updating nav, is flagged the same way a broken Markdown link is: inline and in the Problems panelProblems panelDiagnostics panelProblems tool window.

Where to go next