Is it possible to disable the announcement bar with config or envrionment variable?

[lampensau]

Hello fellow mkdocs-material users, I need to create two separate builds of our documentation, where only one makes use of the announcement bar.

I'm currently achieving this by having two separate theme override directories, each having a different main.html. This is a bit cumbersome, as I need to maintain many similar files across two different directories. Therefore, I'd like to be able to control the feature's activation via a (custom) configuration (e.g., theme.announce.enable).

With that said, I'm failing terribly with all my attempts:

1. Trying to fence off the {% block announce %} in main.html with a conditional if-statement like {% if config.theme.announcement % } does not work for me. The block is always rendered, regardless of the if-statement I use.
2. Trying to fence off the content of the {% block announce %} in main.html with a conditional if-statement results in an empty announcement bar; the basic HTML structure for the announcement is injected at build.

The only thing that works for me is to re-implement the announcement block with the header block in the overrides/main.html:

{% extends "base.html" %}

{% block header %}
{% if "announce.dismiss" in features and config.extra.announce.enabled %}
<div data-md-component="announce">
  <aside class="md-banner">
    <div class="md-banner__inner md-grid md-typeset">
      <button
        class="md-banner__button md-icon"
        aria-label="{{ lang.t('announce.dismiss') }}"
      >
        {% set icon = config.theme.icon.close or "material/close" %}
        {% include ".icons/" ~ icon ~ ".svg" %}
      </button>
      
      <p>
        Testing: {{ config.extra.announce.text }}
      </p>
    </div>
    {% include "partials/javascripts/announce.html" %}
  </aside>
</div>
{% endif %}

<!-- Original Header -->
{% include "partials/header.html" %}
{% endblock %}

I can now add some extra configuration to my mkdocs.yml to enable/disable or change the announcement:

extra:
  announce:
    enabled: !ENV [CI_WEB, false]
    text: >-
      <strong>🚀 Announcement:</strong> We have an announcement header that can be toggled on and off, all controlled via the <a href="#">mkdocs.yml</a> file. 🎉

However, now I have one empty and unused <div data-md-component="announce"> block in my final HTML. Is this really the only solution (besides maintaining a custom base.html)?

Related: #6097, #5842, #3355
Minimal working example: 9.5.26+insiders.4.53.11-toggle-announcement-header.zip

[kamilkrzyskow]

Hello @lampensau,
if you add block announce overrides in your main.html the self.announce() condition will trigger and will add the elements that are inside the conditional block but still outside of the announce block of base.html

mkdocs-material/src/templates/base.html

Lines 231 to 252 in 0c54a88

	{% if self.announce() %}
	<aside class="md-banner">
	<div class="md-banner__inner md-grid md-typeset">
	<!-- Button to dismiss announcement -->
	{% if "announce.dismiss" in features %}
	<button
	class="md-banner__button md-icon"
	aria-label="{{ lang.t('announce.dismiss') }}"
	>
	{% set icon = config.theme.icon.close or "material/close" %}
	{% include ".icons/" ~ icon ~ ".svg" %}
	</button>
	{% endif %}
	<!-- Announcement bar content -->
	{% block announce %}{% endblock %}
	</div>
	{% if "announce.dismiss" in features %}
	{% include "partials/javascripts/announce.html" %}
	{% endif %}
	</aside>

Therefore, if you have a block that is empty a black bar is still present, because the added <aside> and other elements add their own margin/padding. You can add https://squidfunk.github.io/mkdocs-material/customization/#additional-css to override the margin and keep it hidden.

Ref:
https://github.com/Gothic-Modding-Community/gmc/blob/dev/overrides/assets/stylesheets/extra.css#L212-L214

Another option is to use dynamic template override with a hook:

• How to dynamically override templates with hooks? #5060

Updated version from the guide, haven't gotten the time to rewrite it with new scripts. Basically you need to connect the overriding hook to the manager to assure proper file backups etc.

• https://github.com/Gothic-Modding-Community/gmc/blob/dev/overrides/.hooks/theme_overrides_manager.py
• https://github.com/Gothic-Modding-Community/gmc/blob/dev/overrides/.hooks/language_flags.py

So your options are:

1. Fix layout with CSS
2. Override templates with a hook
3. Replace base.html (?) I'm a bit confused on that front, as you say that there is the empty <div data-md-component="announce">, but it's always there even without overriding the announce block. Does the empty block create some issues?

[kamilkrzyskow]

@squidfunk You've explained why the data-component tag needs to be there, but what about my suggestion for the if self.announce() conditional? This could be a https://xyproblem.info/ so to clarify the issue is that the md-banner__inner class adds a margin:

mkdocs-material/src/templates/assets/stylesheets/main/components/_banner.scss

Lines 44 to 49 in ccc8d84

	// Banner wrapper
	&__inner {
	padding: 0 px2rem(16px);
	margin: px2rem(12px) auto;
	font-size: px2rem(14px);
	}

So if in the main.html template the block announce override has a conditional where one result doesn't result in adding text content it ends up with an empty black bar.

I think the CSS is ok, and would prefer some backend setting to block the announce bar from appearing.
Another option to the ones I've given in the previous comment would be a theme.features flag announce.force_hide, this should be still configurable via !ENV, but I didn't test it 🤔

Perhaps you have a different perspective and the CSS could be changed to hide the black bar when empty, while still adding identical looking padding/margin when there is content inside?

Preview

[squidfunk]

what about my suggestion for the if self.announce() conditional

What suggestions specifically?

This could be a https://xyproblem.info/

I don't really understand that 🤷‍♂️

So if in the main.html template the block announce override has a conditional where one result doesn't result in adding text content it ends up with an empty black bar.

That is correct and not ideal, yes. If we could somehow check the contents of the announce block, that would be amazing.

would prefer some backend setting to block the announce bar from appearing.

That makes using the announcement bar more complicated and inflexible. We should try and improve the current behavior without adding more and more settings that somehow try to adjust behavior.

Maybe, to expand on my previous explanation, let me try and explain it again:

1. The data-md-component=announce must be present, so the announcement bar is compatible with instant navigation.
2. Within the announcement bar, we want to make sure that the content of the user is correctly aligned to the site and has sufficient margins and paddings. Thus, if the announcement block is defined, we add the wrappers, and inside those wrappers the content of the announcement bar. If we would not add those wrappers, the user would need to do so, and our implementation would essentially leak into user space, making upgrades more cumbersome. This is why we decided to do it like that. Additionally, as you know, making customization more involved will leads to more issues and users asking why there is no spacing and things look off 😅

I understand that it's not optimal, but the easiest solution is to have a second main.html with the announcement bar defined. Templating in MkDocs and Jinja is very, very limited. To make it simpler which pages receive the announcment bar and which don't, the meta plugin might also be helpful.

@kamilkrzyskow if you can come up with a solution under which 1. an 2. still work the same, which is more comfortable to work with, we're happy to consider it for integration. It might be possible to improve the self.announce() check somehow, but I have no immediate idea how to do this within Jinja.

[lampensau]

After some testing, and @squidfunk warning in regards to navigation.instant, I've decided to implement the CSS fix suggested by @kamilkrzyskow:

.md-banner .md-banner__inner {
    margin: 0;
}

.md-banner .md-banner__inner > p,
.md-banner .md-banner__inner > button {
    margin: 0.6rem 0;
}

This removes the empty remnants of the announcement header when it features no content:

{% block announce %}
{% if config.extra.announce.enabled %}      
<p class="md-banner-content">
  {% if config.extra.announce.text %}
  {{ config.extra.announce.text }}
  {% elif config.extra.announce.version and not config.extra.announce.text %}          
  <strong>🚀 We've released version {{ config.extra.announce.version }}:</strong> Checkout the release notes of the new <a href="{{ 'en/release-notes/firmware' | url }}">firmware</a> and <a href="{{ 'en/release-notes/software' | url }}">software</a> to find out more. 🎉
  {% elif not config.extra.announce.version and not config.extra.announce.text %}
  <strong style="color:red">Attention:</strong> Please provide content for this announcement or disable this feature in your <code>mkdocs.yml</code>: config.extra.announce.enabled: false.
  {% endif %}
</p>
{% endif %}
{% endblock %}

[kamilkrzyskow]

@squidfunk

What suggestions specifically?

Those for the conditional modification, add an, by default, False option to the conditional:
if self.announce() and not config.extra.hide_announce
if self.announce() and not page.meta.hide_anounce
if self.announce() and not "announce.force_hide" in features

would prefer some backend setting to block the announce bar from appearing.

That makes using the announcement bar more complicated and inflexible. We should try and improve the current behavior without adding more and more settings that somehow try to adjust behavior.

Templating in MkDocs and Jinja is very, very limited.

Since the Jinja2 templating is limited, the theme could add more options to control features that are not abstracted into partials, but are kept in the base.html, like the conditional and whole wrapper for the announce block.

1. Changing the conditional doesn't affect the data-md-component=announce
2. I'm not aware of any CSS that would be applied only when there is content inside the container. Both padding and margin will create this empty space.
   I did some searching and found https://developer.mozilla.org/en-US/docs/Web/CSS/:empty which is supported in all browsers.
   So putting the banner margin into a :not(:empty) selector would help a bit. Unfortunately, it detects white space, which is not cleared by default in Jinja2 and people would also have to know about using dashes {%- -%}, which was mentioned in
   Change block overrides depending on OS environment variabled #5842 (reply in thread)

---

Given that users do have the option to modify the CSS to suit their needs, perhaps this doesn't need a better configurable solution at all. People just need to be more aware of this, which was successfully accomplished via this discussion.

[squidfunk]

PRs appreciated, if we can make it clearer in the documentation. I'd also be happy with a combination of :empty and more explicit whitespace control, as long as we're not adding more and more options that possibly interfere with instant navigation.

I'm taking all of this back to the drawing board where I'm currently at, rethinking the biggest parts of Material for MkDocs. We should really make extension simpler than it currently is – it shouldn't be limited by "there's a whitespace in there".