mkdocs-literate-nav icon indicating copy to clipboard operation
mkdocs-literate-nav copied to clipboard

flag to skip erroneous literate-nav-files

Open FrankEppink opened this issue 3 years ago • 0 comments

I think it would be helpful to have the possibility to skip a literate-nav-file (in our case the default SUMMARY.md) when it contains errors.

Scenario

  • We include multiple (n > 10) documentation repositories in our mkdocs call.
  • If only one of them uses an invalid SUMMARY.md file the whole mkdocs process fails.
  • The SUMMARY.md files are sometimes edited by people with limited technical skills.

Example

SUMMARY.md file contains a line starting with "*" but has nothing else, i.e.

* [link-name](link/)
*

this results in an error:

...
File "/usr/lib/python3.9/site-packages/mkdocs_literate_nav/parser.py", line 272, in _iter_children_without_tail
    raise LiterateNavParseError(
mkdocs_literate_nav.parser.LiterateNavParseError: Expected no text after <a href="link/">link-name</a>, but got '\n*'.
The problematic item:
<li><a href="link/">link-name</a>
*</li>
...

Proposal

Of course the error needs to be fixed in the SUMMARY.md file which causes the problems, but it would be good to have the option skip erroneous SUMMARY.md file to keep the process working.

I am thinking of a flag like "skip_erroneous_nav_files" which has default false to enable a "fail-fast" approach, but also enabling a more robust approach when setting this flag in the mkdocs config to true.

I briefly checked the code, the exception is thrown at: https://github.com/oprypin/mkdocs-literate-nav/blob/master/mkdocs_literate_nav/parser.py#L100

FrankEppink avatar Jan 10 '22 11:01 FrankEppink