mirror of https://github.com/onweru/compose.git
---
title: "Navigation and Search"
weight: 6
description: >
The top level menu (the one that appears in the top navigation bar for the entire site) uses your site's main menu. All Hugo sites have a main menu array of menu entries, accessible via the .Site.Menus site variable and populatable via page front matter or your site's config.toml.
To add a page or section to this menu, add it to the site's main menu in either config.toml or in the destination page's front matter (in _index.md or _index.html for a section, as that's the section landing page). For example, here's how we added the Documentation section landing page to the main menu in this site:
---
title: "Docsy Documentation"
linkTitle: "Documentation"
menu:
main:
weight: 20
---
The menu is ordered from left to right by page weight. So, for example, a section index or page with weight: 30 would appear after the Documentation section in the menu, while one with weight: 10 would appear before it.
If you want to add a link to an external site to this menu, add it in config.toml, specifying the weight.
[[menu.main]]
name = "GitHub"
weight = 50
url = "https://github.com/google/docsy/"
Depending on your project's releases and versioning, you may want to let your users access "old" versions of your site (how you deploy your archived sites is up to you) to read about previous versions of your project.
If you add some [params.versions] in config.toml, the Docsy theme adds a version selector drop down to the top-level menu. You specify a URL and a name for each version you would like to add to the menu, as in the following example:
# Add your release versions here
[[params.versions]]
version = "master"
url = "https://master.kubeflow.org"
[[params.versions]]
version = "v0.2"
url = "https://v0-2.kubeflow.org"
[[params.versions]]
version = "v0.3"
url = "https://v0-3.kubeflow.org"
(don't forget to add your current version so users can navigate back!)
The default version drop-down menu title is Releases. To change this, change the version_menu parameter in config.toml:
version_menu = "Releases"
The section menu, as shown in the left side of the docs section, is automatically built from the content tree. Like the top-level menu, it is ordered by page or section index weight (or by page creation date if weight is not set), with the page or index's Title, or linkTitle if different, as its link title in the menu. If a section subfolder has pages other than _index.md or _index.html, those pages will appear as a submenu, again ordered by weight. For example, here's the metadata for this page showing its weight and title:
---
title: "Navigation and Search"
linkTitle: "Navigation and Search"
date: 2017-01-05
weight: 3
description: >
Customize site navigation and search for your Docsy site.
---
To hide a page or section from the menu, set toc_hide: true in front matter.
By default, the section menu will show the current section fully expanded all the way down. This may make the left nav too long and difficult to scan for bigger sites. Try setting site param ui.sidebar_menu_compact = true in config.toml.
Breadcrumb navigation is enabled by default. To disable breadcrumb navigation, set site param ui.breadcrumb_disable = true in config.toml.
Docsy offers multiple options that let your readers search your site content, so you can pick one that suits your needs. You can choose from:
If you enable any of these search options in your config.toml, a search box displays in the right of your top navigation bar. By default a search box also displays at the top of the section menu in the left navigation pane, which you can disable if you prefer, or if you're using a search option that only works with the top search box.
Be aware that if you accidentally enable more than one search option in your config.toml you may get unexpected results (for example, if you have added the .js for Algolia DocSearch, you'll get Algolia results if you enable GCSE search but forget to disable Algolia search).
By default, the search box appears in both the top navigation bar and at the top of the sidebar left navigation pane. If you don't want the sidebar search box, set sidebar_search_disable to true in config.toml:
sidebar_search_disable = true
Deploy your site and ensure that it's built with HUGO_ENV="production", as Google will only crawl and index Docsy sites built with this setting (you probably don't want your not-ready-for-prime-time site to be searchable!). You can specify this variable as a command line flag to Hugo:
$ env HUGO_ENV="production" hugo
Alternatively, if you're using Netlify, you can specify it as a Netlify deployment setting in netlify.toml or the Netlify UI, along with the Hugo version. It may take a day or so before your site has actual search results available.
Add any further configuration you want to your search engine using the Edit search engine options. In particular you may want to do the following:
{{% alert title="Tip" %}}
Your site search results should show up within a couple of days. If it takes longer than that, you can manually request that your site is indexed by submitting a sitemap through the Google Search Console.
{{% /alert %}}
Once you have your search engine set up, you can add the feature to your site:
Ensure you have a Markdown file in content/en/search.md (and one per other languages if needed) to display your search results. It only needs a title and layout: search, as in the following example:
---
title: Search Results
layout: search
---
Add your Google Custom Search Engine ID to the site params in config.toml. You can add different values per language if needed.
# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id = "011737558837375720776:fsdu1nryfng"
Lunr is a Javascript-based search option that lets you index your site and make it searchable without the need for external, server-side search services. This is a good option particularly for smaller or non-public sites.
To add Lunr search to your Docsy site:
Enable local search in config.toml.
# Enable local search
offlineSearch = true
Once you've completed these steps, local search is enabled for your site and results appear in a drop down when you use the search box.
{{% alert title="Tip" %}}
If you're testing this locally using Hugo’s local server functionality, you need to build your offline-search-index.xxx.json file first by running hugo. If you have the Hugo server running while you build offline-search-index.xxx.json, you may need to stop the server and restart it in order to see your search results.
{{% /alert %}}