(hybrid?) literate-nav creates a broken sitemap

[kratsg]

Note: I'm always using mkdocs build --no-directory-urls to build the docs.

I'm using the gen-files project to generate a SUMMARY.md file for use with literate-nav. I generate the following SUMMARY.md

'* [mapyde](mapyde/index.md)\n    * [backends](mapyde/backends/index.md)\n        * [madgraph](mapyde/backends/madgraph.md)\n    * [container](mapyde/container.md)\n    * [runner](mapyde/runner.md)\n    * [typing](mapyde/typing.md)\n    * [utils](mapyde/utils.md)'

however, running linkchecker over the sitemap gives me an error because there is an invalid URL added:

    <url>
         <loc>None</loc>
         <lastmod>2022-11-28</lastmod>
         <changefreq>daily</changefreq>
    </url>
    <url>
         <loc>https://scipp-atlas.github.io/mario-mapyde/reference/mapyde/index.html</loc>
         <lastmod>2022-11-28</lastmod>
         <changefreq>daily</changefreq>
    </url>
    <url>
         <loc>https://scipp-atlas.github.io/mario-mapyde/reference/mapyde/container.html</loc>
         <lastmod>2022-11-28</lastmod>
         <changefreq>daily</changefreq>
    </url>

however, if I edit the mkdocs.yml configuration to something nonsensical for the nav_file and let literal-nav handle subdirectory for me...

  literate-nav:
    nav_file: fake.md

then the sitemap around this point looks like:

    <url>
         <loc>https://scipp-atlas.github.io/mario-mapyde/reference/SUMMARY.html</loc>
         <lastmod>2022-11-28</lastmod>
         <changefreq>daily</changefreq>
    </url>
    <url>
         <loc>https://scipp-atlas.github.io/mario-mapyde/reference/mapyde/index.html</loc>
         <lastmod>2022-11-28</lastmod>
         <changefreq>daily</changefreq>
    </url>
    <url>
         <loc>https://scipp-atlas.github.io/mario-mapyde/reference/mapyde/container.html</loc>
         <lastmod>2022-11-28</lastmod>
         <changefreq>daily</changefreq>
    </url>

which tells me that the SUMMARY.md file is getting included as None in the sitemap! I'm not entirely sure how to fix this. Oddly, if I edit the mkdocs.yml to include a link to the SUMMARY.md directly like so:

      - Code Reference: reference/
      - Fake: reference/SUMMARY.md

then the None entry goes away! It seems mkdocs might be getting a little confused, or literate-nav needs to do a little extra work to either hide or add SUMMARY.md into the nav correctly.

[kratsg]

Further info: I am using basically the same script in oprypin/mkdocs-gen-files!2 for generating the SUMMARY.md. This is used in mkdocstrings and they have the same issue as seen on this line: https://github.com/mkdocstrings/python/blob/273dbb6f3cc5efd28b37586892c80c207ab92a80/sitemap.xml#L44 /cc @pawamoy

[kratsg]

I found a usable workaround. Because I suspected mkdocs is picking up any md files and trying to use that, I went ahead and changed the generating script to output a txt file instead:

with mkdocs_gen_files.open("reference/SUMMARY.txt", "w") as nav_file:
    nav_file.writelines(nav.build_literate_nav())

and updated the literate-nav plugin to point at this text file:

  literate-nav:
    nav_file: SUMMARY.txt

and now linkchecker has no error, and the sitemap does not include this SUMMARY.txt (and it shouldn't).

[pawamoy]

Hey @kratsg, thanks for the ping. I'll probably start using SUMMARY.txt as well then :rocket:

[oprypin]

This will be fixed in MkDocs. But not released yet.

https://github.com/mkdocs/mkdocs/commit/07a297b3b4de4a1b49469b1497ee34039b9f38fa