mkdocs_literate_nav.parser.LiterateNavParseError

[ssbarnea]

I am facing confusing stacktrace errors while trying to follow the examples from official documentations. Example:

- [home](index.md)
- [About](about.md)
- [Contact](contact.md)
- [Articles](posts/)
- Categories
    - [ansible](ansible/index.md)
    - ansible/*.md
- [Tags](tags.md)

Outcome:

$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
Traceback (most recent call last):
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/mkdocs/__main__.py", line 234, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 83, in serve
    builder(config)
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 76, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/mkdocs/commands/build.py", line 297, in build
    files = config.plugins.run_event('files', files, config=config)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/mkdocs/plugins.py", line 520, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/mkdocs_literate_nav/plugin.py", line 45, in on_files
    config["nav"] = resolve_directories_in_nav(
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/mkdocs_literate_nav/plugin.py", line 106, in resolve_directories_in_nav
    result = nav_parser.markdown_to_nav()
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/mkdocs_literate_nav/parser.py", line 73, in markdown_to_nav
    return self._resolve_wildcards(self._list_element_to_nav(ext.nav, root, first_item), roots)
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/ssbarnea/.pyenv/versions/3.11.1/lib/python3.11/site-packages/mkdocs_literate_nav/parser.py", line 116, in _list_element_to_nav
    raise LiterateNavParseError(error, item)
mkdocs_literate_nav.parser.LiterateNavParseError: Expected no more elements, but got <a href="ansible/index.md">ansible</a>.
Did not find any item/section content specified.
Examples:
    * [Item title](item_content.md)
    * Section title
        * [Sub content](sub/content.md)
        * *.md

The problematic item:

<li>Categories
    - <a href="ansible/index.md">ansible</a>
    - ansible/*.md</li>
FAIL: 1

I really fail to see the error and the exception does not help either. I would argue that the stack trace should not happen but that is the lesser important issue.

The example is also using the discouraged "*" bullet lists instead of recommended dashes. Still, that is not related to the error, as the recommended example is basically the same as the once causing the failure.

[oprypin]

The error does actually give us the ability to see what's happening. mkdocs-literate-nav does not by itself deal with Markdown, here it shows what HTML it is receiving from stock parsing.

The problematic item:

<li>Categories
    - <a href="ansible/index.md">ansible</a>
    - ansible/*.md</li>

You can see here that the sub-list is somehow not recognized as an actual list and keeps the literal dashes.

Why the Markdown parsing does that, I don't know. You can try viewing this snippet of Markdown in normal MkDocs rendering (possibly by copy-pasting it somewhere - without Markdown extensions enabled) and I expect it to also exhibit that problem, then you can edit it until it works

[oprypin]

Side note: it seems like the implicit_index setting could be useful for you.

[ssbarnea]

Thanks for the index comment, that simplifies the things a little but still does not address the main issue I reported.

To list a folder with md documents into the nav I can do:

- [i18n](i18n/)

That works fine and adds a new section for it. Still, If I am trying to put it as a sub-section like below, it get the crash:

- Categories
    - [i18n](i18n/)

I might be missing something, but I was expected this to work.

    raise LiterateNavParseError(error, item)
mkdocs_literate_nav.parser.LiterateNavParseError: Expected no more elements, but got <a href="i18n/">i18n</a>.
Did not find any item/section content specified.
Examples:
    * [Item title](item_content.md)
    * Section title
        * [Sub content](sub/content.md)
        * *.md

The problematic item:

<li>ZZ
    - <a href="i18n/">i18n</a></li>

[oprypin]

I am not saying that my 2nd comment addresses the issue. My 1st comment, however, does address it. This is the same problem.

[oprypin]

Also actually I cannot reproduce the issue:

$ cat mkdocs.yml     
site_name: test
theme: readthedocs

plugins:
  - literate-nav:
      nav_file: SUMMARY.md

$ cat docs/SUMMARY.md        
- Categories
    - [i18n](i18n/)

$ mkdocs build
[ok]

[ssbarnea]

I am using material theme and few other plugins, maybe there is something else that affects the outcome. I will try to build a minimal MVP to test the behavior, maybe I will be able to isolate the issue.