Using Insiders Blog plugin without defined Navigation

[polymorcodeus]

Heya-

I'm trying to figure out if it's possible to enable the Blog insiders plugin without a defined nav section. We have a main site with a number of remote repos "publishing" into our main site, to keep the docs close to the tooling so we just rely on a non-defined nav section.

However it looks? like this might be incompatible with the Blog plugin as I get this error when trying to build:
ERROR - Blog root 'blog/index.md' not in navigation.

I'm currently pulling down the latest Insiders version - just in case - however the documentation definitely seems to indicate you have to hard define it in the nav section. Though I'm really hoping I'm just missing something obvious.

[squidfunk]

Currently not possible, yes. We could in theory add the blog "somewhere", but that's likely not the location you would imagine. I'm not sure that this is a good idea. Have you considered using the awesome-pages plugin, which allows you to partially define your navigation? It might also be possible to just scope this to the blog section. Not sure though, I'm not a user.

[polymorcodeus]

FULL disclosure - this is incredibly hacky and I'm sure this could be worked into something slightly more production worthy BUT this works for my narrow use case. I've briefly tested this for multiple rest sections, YMMV.

Also, I'm not remotely a python dev, so apologies in advance.

TL;DR - stores REST_PLACE_HOLDER elements and removes them in config stage as needed. Uses updated get_nav function that ignores the fact that a config["nav"] is defined and inserts them back into the nave.items list. You'll get a INFO: The following pages exist in the docs directory, but are not included in the "nav" configuration: that I haven't bothered to try and supress.

NAV section:

nav:
  - index.md
  - Blog:
    - blog/index.md
  - tags.md
  - ...

Personal Fork of mkdocs-awesome-pages-plugin:

plugin.py - replaced func(s) on_nav and on_config with below
...
    def on_nav(self, nav: MkDocsNavigation, config: Config, files: Files):
        explicit_nav = nav if not config["nav"] else None
        
        if self.nav_config_with_rest:
            # restore explicit config with rest placeholder and build nav
            config["nav"] = self.nav_config_with_rest
            awesome_nav = get_awesome_navigation(files, config)
            
            explicit_nav = get_navigation(files, config)

            for key, value in self.rest_dict.items(): # Add "rest sections" back to nav
                rest_link = Link(AwesomePagesPlugin.REST_PLACEHOLDER, value)
                explicit_nav.items.insert(key, rest_link)
            
        explicit_sections = set(get_by_type(explicit_nav, Section)) if explicit_nav else set()

        if self.nav_config_with_rest:
            self.rest_blocks = self._generate_rest_blocks(awesome_nav.items, [page.file for page in explicit_nav.pages])
            self._insert_rest(explicit_nav.items) 
            nav = explicit_nav

        return AwesomeNavigation(nav.items, Options(**self.config), config["docs_dir"], explicit_sections).to_mkdocs()

    def on_config(self, config: Config):
        for name, plugin in config["plugins"].items():
            if name == "awesome-pages":
                break
            if hasattr(plugin, "on_nav"):
                warnings.warn(NavPluginOrder(name))

        if config["nav"]:
            self._find_rest(config["nav"])
            if self.rest_items:
                self.nav_config_with_rest = config["nav"]

                self.temp_nav_config = config["nav"]

                for index,item in enumerate(config["nav"]):
                    if type(item) is dict: 
                        if AwesomePagesPlugin.REST_PLACEHOLDER in item:
                            self.rest_dict.update({index:item[AwesomePagesPlugin.REST_PLACEHOLDER]})
                            self.temp_nav_config.pop(index)

                config["nav"] = self.temp_nav_config  # Leave non "rest-like" nav, namely for Blog validation
                
        return config

navigation.py - add imports (needed for func) and new func get_awesome_navigation
...
# Custom get_awesome_navigation
from mkdocs.utils import nest_paths
from mkdocs.structure.files import Files

import logging
log = logging.getLogger(__name__)
from urllib.parse import urlsplit

from typing import TYPE_CHECKING, Any, Iterator, List, Mapping, Optional, Type, TypeVar, Union
from mkdocs.config.defaults import MkDocsConfig
# Custom get_awesome_navigation
...
## Remove config['nav'] from mkdocs.structure.nav > nav_config
def get_awesome_navigation(files: Files, config: Union[MkDocsConfig, Mapping[str, Any]]) -> MkDocsNavigation:
    """Build site navigation from config and files."""
    nav_config = nest_paths(f.src_uri for f in files.documentation_pages())
    items = _data_to_navigation(nav_config, files, config)
    if not isinstance(items, list):
        items = [items]

    pages = _get_by_type(items, Page)

    _add_previous_and_next_links(pages)
    _add_parent_links(items)

    missing_from_config = [file for file in files.documentation_pages() if file.page is None]
    if missing_from_config:
        log.info(
            'The following pages exist in the docs directory, but are not '
            'included in the "nav" configuration:\n  - {}'.format(
                '\n  - '.join(file.src_path for file in missing_from_config)
            )
        )
        for file in missing_from_config:
            Page(None, file, 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('/'):
            log.debug(
                f"An absolute path to '{link.url}' is included in the 'nav' "
                "configuration, which presumably points to an external resource."
            )
        else:
            msg = (
                f"A relative path to '{link.url}' is included in the 'nav' "
                "configuration, which is not found in the documentation files"
            )
            log.warning(msg)
    return MkDocsNavigation(items, pages)

[squidfunk]

Thanks for sharing! As already said, we'll investigate if we can lift this restriction in the future, but for now, other users have something they can build on if they wish to implement the same thing, thanks to you!

[boozedog]

@polymorcodeus would you consider submitting a PR with your changes to the mkdocs-awesome-pages-plugin repo?

[polymorcodeus]

@boozedog Absolutely can - it felt like a bit of a hack and my python is horrible. :) Need to make sure what I actually have rolled and will get it up there.

[boozedog]

@boozedog Absolutely can - it felt like a bit of a hack and my python is horrible. :) Need to make sure what I actually have rolled and will get it up there.

@polymorcodeus Awesome, I did open an issue on that repo as well ... I didn't see a public fork so I could try out your code but I'm happy to test it if you like ... let me know!

[boozedog]

so it looks like @polymorcodeus fix won't be integrated into https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin anytime soon (probably not 'til blog becomes a public feature)

@squidfunk would you reconsider providing some default behavior for blog in the nav when nav is not defined? I do like the ability to add pages without manually managing the nav, and my sense is that moar plugins isn't the answer

Any default behavior you provide is fine w/ me, for now I have to disable the blog which makes me sad

[squidfunk]

There's an open PR over at Insiders for this right now. I just haven't had the time to review it. It's likely not mergeable as-is, but I will check and reconsider. However, it'll be "just add the blog somewhere", probably at the end. I'm not sure that's good.

[boozedog]

@squidfunk at the end is fine with me! I'll shift my commenting to that PR

[squidfunk]

https://github.com/squidfunk/mkdocs-material-insiders/pull/64 is an attempt to allow for both, defining and omitting explicit listing blog entries in the navigation. I invite everybody that needs this functionality to test the PR.

[squidfunk]

As an update: we're close to finishing a ground-up rewrite of the blog plugin, which removes all of the current limitations and improves interop with third party plugins like awesome pages and friends. I'm sorry this took some time and made so many people upset, but I think the result is a very mature implementation which allows us to take blogging to the next level.

For updates, please follow #5686

[StefanoCecere]

with 9.4.1 it works very well! i just add - blog to awesome .pages et voilà. thank you!

[squidfunk]

Awesome, glad we solved it!