Partial rendering of Open API doc while enabling 'custom_dir'

[vincentlel]

Hi all, I am investigating mkdocs-material for API documentation and I am using swagger ui plugin to render API specs.

Rendering is great

I wanted to use the announcement features to add release updates on the top of my documentation, but when I update the mkdocs.yml file with

 custom_dir: overrides 

API doc rendering is broken

Do you have any idea of what I am doing wrong? Any guidance on how to overcome this?

Thanks

Vincent

[kamilkrzyskow]

Hi @vincentlel,
I haven't used any swagger API MkDocs plugins, and you haven't provided any files, so I can only assume that either the swagger plugin misbehaves when custom_dir is activated or that you've misconfigured it.

After looking at the source code for the linked plugin I don't see any issues with the custom_dir. So let's redo the custom_dir configuration and then you'll tell us at which stage you have the issue mentioned above.

1. Delete the overrides directory for now.
2. Add the theme: custom_dir: overrides to mkdocs.yml
3. Run mkdocs serve. There should be an error "The path set in custom_dir does not exist."
4. Create empty overrides directory relative to mkdocs.yml and run mkdocs serve. The website should load normally as the overrides directory is empty and doesn't do anything.
5. Create overrides/main.html file with Hello World and run mkdocs serve. The website should only contain the Hello World text as the main.html file overrides the build logic.
6. Replace the contents of the overrides/main.html with {% extends "base.html" %} and run mkdocs serve. The website should load normally as it uses the same configuration as without the overrides directory.
7. Add the announcement announce block override with Hello World and run mkdocs serve. There should be the announcement bar and no other changes to the page.

Final version of the main.html file:

{% extends "base.html" %}

{% block announce %}
  Hello World
{% endblock %}

Lastly, you can run mkdocs serve --watch overrides to allow the changes from overrides to trigger the auto-reload logic.

[vincentlel]

@kamilkrzyskow thanks for your help. I created a test project as recommend and it works just fine. The root cause of the issue was and empty section in main.html {% block extrahead %}{% endblock %} ...