Skip to content
/ mkdocs Public
  • Sponsor
  • Notifications You must be signed in to change notification settings
  • Fork 2.5k
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow broken Nav without failing building the rest of the docs #1406

Closed
wants to merge 1 commit into from

Conversation

sean-heller
Copy link

We've noticed when many teams are contributing to a single mkdocs file, broken TOC files will eventually happen. and the mkdocs build breaks. It'd be nice to have the option to continue the build, and replace broken TOC pages with a 404 page.

Looking for input on what exactly that 404 page should look like, for now I've literally just put the text "404" on the page!

@waylan
Copy link
Member

waylan commented Feb 15, 2018

First of all, the "TOC" is the list of headers within a page. You appear to be referring to the "pages config setting" which we often refer to as the "nav" . Any such references to "toc" should be updated to refer to the "nav".

Second, we are very resistant to adding new settings. I question whether this new allow_missing_pages setting is really needed. We already have a strict mode for the build which fails on warnings. Seems like that might be a sensible approach (missing page issues a warning and that warning results in an error only in strict mode).

Third, I'm not sure we want to do this at all. As per #699 we intend to support building pages which are not listed in the pages config setting. The config setting will simply become a mechanism to define the global navigation for the site. Why would anyone add items to the nav which don't exist? Seems backwards to me. In any event, as per #778, we also will be adding the ability to include external links in the nav, so at that point, we will have items in the nav which we won't even know if they exist.

Given the above, my inclination is to address this with #699 and #778, if at all. Therefore, it makes no sense to apply this patch (or update it). I'll leave this open and add it to the Pages Refactor project so we don't forget about it.

@waylan
Copy link
Member

waylan commented Feb 15, 2018

Oh and we would not create the page with the body of "404" or anything else (the themes already provide a 404 page). Instead, simply move on to the next page. But for that to happen we need #699 which separates the page building from the nav.

@sean-heller
Copy link
Author

thanks for the quick response!

  1. re: toc vs pages, understood
  2. rather than a new config i can leverage the strict config setting
  3. with our builds, we have teams adding misconfigured toc.yml's in their respective project which is breaking the whole site. i'd like to be able to relax this so other documentation can still be updated
  4. noted on the 404 page, maybe I can just have it display the theme's 404 pagr for now?

@waylan
Copy link
Member

waylan commented Feb 15, 2018

maybe I can just have it display the theme's 404 pagr

It already does for any non-existent page which is requested as long you the server is configured correctly (the dev server is).

for now

Unless you are forking locally, there is no need. The next release we do will have the above discussed changes. An interim fix will never make it to a release.

@waylan waylan changed the title Allow broken TOCs without failing building the rest of the docs Allow broken Nav without failing building the rest of the docs Apr 4, 2018
@waylan waylan closed this in 34ef3ca Jun 28, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants