Closed ssbarnea closed 1 year ago
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
Side note: it seems like the implicit_index setting could be useful for you.
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>
I am not saying that my 2nd comment addresses the issue. My 1st comment, however, does address it. This is the same problem.
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]
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.
I am facing confusing stacktrace errors while trying to follow the examples from official documentations. Example:
Outcome:
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.