Function get_navigation

mkdocs/structure/nav.py:130–185

Build site navigation from config and files.

(files: Files, config: MkDocsConfig)

def get_navigation(files: Files, config: MkDocsConfig) -> Navigation:
    """Build site navigation from config and files."""
    documentation_pages = files.documentation_pages()
    nav_config = config['nav']
    if nav_config is None:
        documentation_pages = sorted(documentation_pages, key=file_sort_key)
        nav_config = nest_paths(f.src_uri for f in documentation_pages if f.inclusion.is_in_nav())
    items = _data_to_navigation(nav_config, files, config)
    if not isinstance(items, list):
        items = [items]

    # Get only the pages from the navigation, ignoring any sections and links.
    pages = _get_by_type(items, Page)

    # Include next, previous and parent links.
    _add_previous_and_next_links(pages)
    _add_parent_links(items)

    missing_from_config = []
    for file in documentation_pages:
        if file.page is None:
            # Any documentation files not found in the nav should still have an associated page, so we
            # create them here. The Page object will automatically be assigned to `file.page` during
            # its creation (and this is the only way in which these page objects are accessible).
            Page(None, file, config)
            if file.inclusion.is_in_nav():
                missing_from_config.append(file.src_path)
    if missing_from_config:
        log.log(
            config.validation.nav.omitted_files,
            'The following pages exist in the docs directory, but are not '
            'included in the "nav" configuration:\n  - ' + '\n  - '.join(missing_from_config),
        )

    links = _get_by_type(items, Link)
    for link in links:
        scheme, netloc, path, query, fragment = urlsplit(link.url)
        if scheme or netloc:
            log.debug(f"An external link to '{link.url}' is included in the 'nav' configuration.")
        elif (
            link.url.startswith('/')
            and config.validation.nav.absolute_links
            is not _AbsoluteLinksValidationValue.RELATIVE_TO_DOCS
        ):
            log.log(
                config.validation.nav.absolute_links,
                f"An absolute path to '{link.url}' is included in the 'nav' "
                "configuration, which presumably points to an external resource.",
            )
        else:
            log.log(
                config.validation.nav.not_found,
                f"A reference to '{link.url}' is included in the 'nav' "
                "configuration, which is not found in the documentation files.",
            )
    return Navigation(items, pages)