Block override doesnt work

[fmalinge]

Hi,
I ve created a custom theme to make small modification to the mkdocs theme.
I ve created a main.html (witch extend the base) 👍
it override footer block : OK
But I cant override next_prev block (to translate the search box)
Is it because next_prev is include in the nav.html ?
Thanks
Fred

[waylan]

The search box should be in the search_button block, not next_prev. And I just noticed the docs list it as search_box. Looks like we have a small error in our docs.

[fmalinge]

Yes, that what i did , here is my main.html in the custom_theme to translate some terms in french (footer override is OK, but not the search_button and the next_prev) :

{% extends "base.html" %}
{%- block search_button %}
<li>
    <a href="#" data-toggle="modal" data-target="#mkdocs_search_modal">
        <i class="fa fa-search"></i> Recherche
    </a>
</li>
{%- endblock %}

{%- block next_prev %}
    {%- if page and (page.next_page or page.previous_page) %}
        <li {% if not page.previous_page %}class="disabled"{% endif %}>
            <a rel="next" {% if page.previous_page %}href="{{ page.previous_page.url }}"{% endif %}>
                <i class="fa fa-arrow-left"></i> Précédent
            </a>
        </li>
        <li {% if not page.next_page %}class="disabled"{% endif %}>
            <a rel="prev" {% if page.next_page %}href="{{ page.next_page.url }}"{% endif %}>
                Suivant <i class="fa fa-arrow-right"></i>
            </a>
        </li>
    {%- endif %}
{%- endblock %}
{%- block footer %}
    <hr>
    {%- if config.copyright %}
        <p>{{ config.copyright }}</p>
    {%- endif %}
{%- endblock %}
{%- block footer %}
    <hr>
    {%- if config.copyright %}
        <p>{{ config.copyright }}</p>
    {%- endif %}
    <p>Documentation créée par <a href="http://www.mkdocs.org/">MkDocs</a>.</p>
{%- endblock %}

[waylan]

Groan. I just did a quick search and the first result indicates this is not possible. Apparently, when I was adding the blocks to the templates, I never tested whether this works for the "included" templates. There are some possible workarounds, but those require edits to the base.html and nav.html before they will work.

@fmalinge there is one other workaround you could try. Copy nav.html to your custom theme dir and make the changes/translations there. The nav.html file in your custom theme dir will replace/override the one in the theme.

[fmalinge]

OK, but it's a shame because override template block was a good solution (we can update mkdocs without losing its code). Is what i can create a custom_nav that would be an extend of nav (extend nav.html)
Thanks for your quick replies
Fred

[akhilputhiry]

@waylan According to this PR pallets/jinja#84 it seems blocks inside included templates can be overriden

[waylan]

Yes and in pallets/jinja#243 they reverted the change removing support as it apparently broke stuff. So unless you run a custom modified version of Jinja, this isn't going to work, which is disappointing to say the least.

[jberkel]

Just fell into the same trap. The mkdocs-docs mentions this, but just in passing:

You may re-define as many blocks as you desire, as long as those blocks are defined in the parent.

http://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks

However the list of block names which follows includes a few which are not (easily) overridable, such as next_prev, so I assumed it would work.

[ColdHeat]

This is extremely unclear in the docs... I don't think the docs should be saying that next_prev is overridable through main.html if it actually isn't possible at the moment.

[tmenier]

@waylan Would you consider a PR that does away with any include files that contain blocks and just merge that content directly into base.html? The way it stands, 5 out the 14 documented overridable template blocks simply don't work at all, and I doubt Jinja is ever going to support this.

[waylan]

I'm of two minds about this. On the one hand, making the changes would give us the intended/desired behavior. On the other hand, the existing file structure of the themes has existed long before we added blocks and there are potentially many existing users who are already providing their own overriding template files (such as nav.html) and making the change would break those overrides. That said, if we are ever going to make the change, now is the time to do it (before we release 1.0).

Something that we need to remember (and perhaps the docs could be more clear about) is that MkDocs may provide support for a feature, but that does not mean that every theme does. This is one of those features where MkDocs provides the mechanisms, but support is entirely dependent on the theme making use of that mechanism. Ideally the "default" theme would support all features, but that shouldn't be assumed about all themes in general.

If that all sounds indecisive, that's because I'm not sure how I want to proceed. If someone could submit a PR which addressed all my concerns, that would be great. But I doubt that's possible. So do we support the documented feature that had never worked, or the undocumented feature that has always worked?

[tmenier]

Good point about breaking users who may have overridden an entire include. (That was going to be my work-around, so I would have broken myself!)

Another possible solution is to create a new out-of-the-box theme, like "mkdocs2" (or whatever you come up with that's bound to be better). Folks could "upgrade" to that if and when they choose, and that theme could support all 14 blocks by flattening everything to base.html or whatever. But then again, I'm not sure if supporting another theme indefinitely just for this is better than just taking a breaking change for 1.0.

I think the docs are clear that not all themes necessarily support all features. The bigger problem as I see it is they say "The MkDocs and ReadTheDocs themes provide the following blocks: ...", which is simply not correct.

Anyway, happy to help if you want. I was really excited to find MkDocs and I'm loving it so far. Thank you.

[wren]

Can the docs be updated to reflect this known issue? I followed the docs step-by-step only to end up spending an hour searching the internet for reasons why search_box wasn't working. Only stumbling into this closed issue saved me.