# Navigation A clear and concise navigation structure is an important aspect of good project documentation. Zensical provides several options to configure the behavior of navigational elements, including [tabs](<#navigation-tabs>) and [sections](<#navigation-sections>), as well as features such as [instant navigation](<#instant-navigation>) and [instant previews](<#instant-previews>). Additional navigation can be configured [in the footer](). ## Configuration By default, Zensical creates the navigation sidebar on the basis of the folder structure and content of the Markdown pages. Likewise, it uses a default layout that can be overridden using various feature flags described on this page. Pages can be omitted from the default navigation with [`not_in_nav`](). They are still built and included in search and the sitemap. Pages matched by [`draft_docs`]() are also omitted from the default navigation, including during preview. ### Explicit navigation If you want to exercise more control over the structure of your navigation, you can create an explicit definition of the navigation structure in your configuration file. In the simplest case, you simply list the paths to your content files, leaving it to Zensical to extract a title for each of them from the content itself. The paths need to be relative to the [`docs_dir`](). ```toml [project] nav = [ "index.md", "about.md", ] ``` ```yaml nav: - index.md - about.md ``` Instead of letting Zensical figure out the title to use for the navigation entry for a page, you can also explicitly specify a title: ```toml [project] nav = [ { "Home" = "index.md" }, { "About" = "about.md" }, ] ``` ```yaml nav: - Home: index.md - About: about.md ``` #### Navigation sections You can define navigation sections to create a navigation hierarchy that guides your users to the information they require. ```toml [project] nav = [ { "Home" = "index.md" }, { "About" = [ "about/index.md", "about/vision.md", "about/team.md", ] }, ] ``` ```yaml nav: - Home: index.md - About: - about/index.md - about/vision.md - about/team.md ``` #### External links Navigation items typically provide a path to a Markdown page. However, any string that cannot be resolved to a Markdown page is treated as a URL. ```toml [project] nav = [ { "GitHub Repo" = "https://github.com/zensical/docs" }, ] ``` ```yaml nav: - GitHub Repo: https://github.com/zensical/docs ``` The "GitHub Repo" navigation entry takes the user to the repository for the Zensical Documentation. ### Instant navigation When instant navigation is enabled, clicks on all internal links will be intercepted and dispatched via [XHR]() without fully reloading the page. Add the following lines to your configuration: ```toml [project.theme] features = [ "navigation.instant", ] ``` ```yaml theme: features: - navigation.instant ``` The resulting page is parsed and injected and all event handlers and components are rebound automatically, i.e., **Zensical now behaves like a Single Page Application**. Also, the search index is persisted through navigation, which is especially useful for large documentation sites. > [!NOTE] > > **The [`site_url`]() setting must be set** > > Note that you must set [`site_url`]() when using instant navigation, as instant navigation relies on the generated `sitemap.xml` which will be empty if this setting is omitted. #### Instant prefetching Instant prefetching is a new experimental feature that will start to fetch a page once the user hovers over a link. This reduces the perceived loading time for the user, especially on slow connections, as the page will be available immediately upon navigation. Enable it with: ```toml [project.theme] features = [ "navigation.instant", "navigation.instant.prefetch", ] ``` ```yaml theme: features: - navigation.instant - navigation.instant.prefetch ``` #### Progress indicator In order to provide a better user experience on slow connections when using instant navigation, a progress indicator can be enabled. It will be shown at the top of the page and will be hidden once the page has fully loaded. You can enable it in your configuration with: ```toml [project.theme] features = [ "navigation.instant", "navigation.instant.progress", ] ``` ```yaml theme: features: - navigation.instant - navigation.instant.progress ``` The progress indicator will only show if the page hasn't finished loading after 400ms, so that fast connections will never show it for a better instant experience. ### Instant previews Instant previews allow the user to preview another site of your documentation without navigating to it. They can be very helpful to keep the user in context. Instant previews can be enabled on any header link with the `data-preview` attribute: Link with instant preview ````markdown ``` markdown [Attribute Lists](#){ data-preview } ``` ```` [Attribute Lists]() > [!NOTE] > > **Limitations** > > Instant previews are still an experimental feature and currently limited to headerlinks. This means, you can use them on any internal link that points to a header on another page, but not other elements with `id` attributes. #### Automatic previews The recommended way to work with instant previews is to use the Markdown extension that is included with Zensical, as it allows you to enable instant previews on a per-page or per-section level for your documentation: ```toml [[project.markdown_extensions.zensical.extensions.preview.configurations]] targets.include = [ "customization.md", "compatibility/markdown/*", ] ``` ```yaml markdown_extensions: - zensical.extensions.preview: configurations: - targets: include: - customization.md - compatibility/markdown/* ``` The above configuration is what we use for our documentation. We've enabled instant previews for our changelogs, customization guide and for all Markdown extensions in the setup guide. > [!NOTE] > > **Full configuration example** > > ```toml > [[project.markdown_extensions.zensical.extensions.preview.configurations]] > sources.include = [] # (1)! > sources.exclude = [] > targets.include = [] # (2)! > targets.exclude = [] > ``` > > ```yaml > markdown_extensions: > - zensical.extensions.preview: > configurations: > - sources: # (1)! > include: > - ... > exclude: > - ... > targets: # (2)! > include: > - ... > exclude: > - ... > ``` > > 1. Sources specify the pages *on* which instant previews should be enabled. If this setting is omitted, instant previews will be enabled on all pages. You can use patterns to include or exclude pages. Exclusion is evaluated on top of inclusion, so if a page is matched by both, it will be excluded. > > Note that you can define multiple items under the `configurations` setting, which allows to precisely control where instant previews are shown. > 2. Targets specify the pages *to* which instant previews should be enabled. This is the recommended way to enable instant previews. --- > [!NOTE] > > **The [`site_url`]() setting must be set** > > Note that you must set [`site_url`]() when using instant previews, as instant previews rely on the generated `sitemap.xml` which will be empty if this setting is omitted. ### Anchor tracking When anchor tracking is enabled, the URL in the address bar is automatically updated with the active anchor as highlighted in the table of contents. Add the following lines to your configuration: ```toml [project.theme] features = [ "navigation.tracking", ] ``` ```yaml theme: features: - navigation.tracking ``` ### Navigation tabs When tabs are enabled, top-level sections are rendered in a menu layer below the header for viewports above `1220px`, but remain as-is on mobile. Add the following lines to your configuration: ```toml [project.theme] features = [ "navigation.tabs", ] ``` ```yaml theme: features: - navigation.tabs ``` #### Sticky navigation tabs When sticky tabs are enabled, navigation tabs will lock below the header and always remain visible when scrolling down. Just add the following two feature flags to your configuration: ```toml [project.theme] features = [ "navigation.tabs", "navigation.tabs.sticky", ] ``` ```yaml theme: features: - navigation.tabs - navigation.tabs.sticky ``` ### Navigation sections When sections are enabled, top-level sections are rendered as groups in the sidebar for viewports above `1220px`, but remain as-is on mobile. Add the following lines to your configuration: ```toml [project.theme] features = [ "navigation.sections", ] ``` ```yaml theme: features: - navigation.sections ``` Both feature flags, [`navigation.tabs`](<#navigation-tabs>) and [`navigation.sections`](<#navigation-sections>), can be combined with each other. If both feature flags are enabled, sections are rendered for level 2 navigation items. ### Navigation expansion When expansion is enabled, the left sidebar will expand all collapsible subsections by default, so the user doesn't have to open subsections manually. Add the following lines to your configuration: ```toml [project.theme] features = [ "navigation.expand", ] ``` ```yaml theme: features: - navigation.expand ``` ### Navigation path Breadcrumbs When navigation paths are activated, a breadcrumb navigation is rendered above the title of each page, which might make orientation easier for users visiting your documentation on devices with smaller screens. Add the following lines to your configuration: ```toml [project.theme] features = [ "navigation.path", ] ``` ```yaml theme: features: - navigation.path ``` ### Navigation pruning When pruning is enabled, only the visible navigation items are included in the rendered HTML, **reducing the size of the built site by 33% or more**. Add the following lines to your configuration: ```toml [project.theme] features = [ "navigation.prune", # (1)! ] ``` 1. This feature flag is not compatible with [`navigation.expand`](<#navigation-expansion>), as navigation expansion requires the complete navigation structure. ```yaml theme: features: - navigation.prune # (1)! ``` 1. This feature flag is not compatible with [`navigation.expand`](<#navigation-expansion>), as navigation expansion requires the complete navigation structure. This feature flag is especially useful for documentation sites with thousands of pages, as the navigation makes up a significant fraction of the HTML. Navigation pruning will replace all expandable sections with links to the first page in that section (or the section index page). ### Section index pages When section index pages are enabled, documents can be directly attached to sections, which is particularly useful for providing overview pages. Add the following lines to your configuration: ```toml [project.theme] features = [ "navigation.indexes", # (1)! ] ``` 1. This feature flag is not compatible with [`toc.integrate`](<#navigation-integration>), as sections cannot host the table of contents due to missing space. ```yaml theme: features: - navigation.indexes # (1)! ``` 1. This feature flag is not compatible with [`toc.integrate`](<#navigation-integration>), as sections cannot host the table of contents due to missing space. In order to link a page to a section, create a new document with the name `index.md` in the respective folder, and add it to the beginning of your navigation section: ```toml [project] nav = [ { "Section" = [ "section/index.md", # (1)! { "Page 1" = "section/page-1.md" }, # ... { "Page n" = "section/page-n.md" }, ] }, ] ``` 1. `README.md` is also considered an index page. ```yaml nav: - Section: - section/index.md # (1)! - Page 1: section/page-1.md # ... - Page n: section/page-n.md ``` 1. `README.md` is also considered an index page. ### Table of contents #### Anchor following When anchor following for the [table of contents]() is enabled, the sidebar is automatically scrolled so that the active anchor is always visible. Add the following lines to your configuration: ```toml [project.theme] features = [ "toc.follow", ] ``` ```yaml theme: features: - toc.follow ``` #### Navigation integration When navigation integration for the [table of contents]() is enabled, it is always rendered as part of the navigation sidebar on the left. Add the following lines to your configuration: ```toml [project.theme] features = [ "toc.integrate", # (1)! ] ``` 1. This feature flag is not compatible with [`navigation.indexes`](<#section-index-pages>), as sections cannot host the table of contents due to missing space. ```yaml theme: features: - toc.integrate # (1)! ``` 1. This feature flag is not compatible with [`navigation.indexes`](<#section-index-pages>), as sections cannot host the table of contents due to missing space. ### Back-to-top button A back-to-top button can be shown when the user, after scrolling down, starts to scroll up again. It's rendered centered and at the bottom of the page. Add the following lines to your configuration: ```toml [project.theme] features = [ "navigation.top", ] ``` ```yaml theme: features: - navigation.top ``` ## Usage ### Hide the sidebars The navigation and/or table of contents sidebars can be hidden for a document with the front matter `hide` property. Add the following lines at the top of a Markdown file: ```yaml --- hide: - navigation - toc --- # Page title ... ``` ### Hide the navigation path While the [navigation path](<#navigation-path>) is rendered above the main headline, sometimes, it might be desirable to hide it for a specific page, which can be achieved with the front matter `hide` property: ```yaml --- hide: - path --- # Page title ... ``` ## Customization ### Content area width The width of the content area is set so the length of each line doesn't exceed 80-100 characters, depending on the width of the characters. While this is a reasonable default, as longer lines tend to be harder to read, it may be desirable to increase the overall width of the content area, or even make it stretch to the entire available space. This can easily be achieved with an [additional style sheet]() and a few lines of CSS: ```css .md-grid { max-width: 1440px; /* (1)! */ } ``` 1. If you want the content area to always stretch to the available screen space, reset `max-width` with the following CSS: ```css .md-grid { max-width: initial; } ``` ```toml [project] extra_css = [ "stylesheets/extra.css", ] ``` ```yaml extra_css: - stylesheets/extra.css ```