Versioning - Pre-Release Banner

[adam-moss]

Hi,

New to mkdocs and mkdocs-material, both of which I'm finding most awesome with an amazingly simple learning curve, and have inspired me to create an additional handler for mkdocstrings.

Apologies if this has been asked/answered but my search foo is failing me.

In https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/#versioning it describes how to implement a customisation to incorporate an "outdated" banner in my docs. This works an absolute treat, although I did have to spend a bit of trial-and-error with mike as I'm using GitLab rather than GitHub (and a bit OCD).

Now I'm wondering if it is possible to basically do the opposite of the outdated banner, and highlight when the user is on a "future" / pre-release version of the docs?

At the moment I publish updated docs as next when merged to main, and publish a tagged version with the latest alias only when a release is tagged and packaged.

Thusly it would be nice to highlight these docs as being pre-release.

Thanks.

[squidfunk]

Thanks for asking, and we're glad that you enjoy our work! There's currently no pre-release banner, and it's also not planned right now, but you could just use the announcement bar with some custom styling and only enable it on pre-release builds? How? That's left to be worked out, but maybe ask the authors of mike whether you can detect if you're running a pre-release build in the template. You could then define a custom announcement bar and only render it when you're on a pre-release build. I understand that this sounds involved, and I'm sorry that there's currently no easy way to do this, but it should be possible with some legwork.

We will consider this feature in the future.

[adam-moss]

Ah... that's a great idea, thank you, I'll have a play around share what I come up with 😄

[adam-moss]

I've just had a chance to play with this and have come up with a fairly clean solution I think.

In mkdocs.yml, add an extra attribute that is passed into the jinja2 template via mkdocs itself:

extra:
  pre_release: true

In overrides/main.html, use the passed variable in a conditional surrounding the announce block:

{% extends "base.html" %}

{% if config.extra.pre_release %}
  {% block announce %}
    You are currently viewing <strong>pre-release</strong> documentation.  This may contain features that have not yet been packaged. For the most accurate information, please <strong><a href="{{ '../' ~ base_url }}">access the release version</a></strong>.
  {% endblock %}
{% endif %}

{% block outdated %}
  You are currently viewing <strong>outdated</strong> documentation.  For the most up-to-date information, please <strong><a href="{{ '../' ~ base_url }}">refer to the latest release</a></strong>.
{% endblock %}

And in extra.css, change .md-banner to match the md-banner--warning styling:

.md-banner {
  background-color: var(--md-warning-bg-color);
  color: var(--md-warning-fg-color);
}

I must admit I'm not entirely sure on the implications of that last one elsewhere in the theme, looks through the src folder doesn't suggest anything obvious but it is easy enough to remove if needs be.

Thanks for the suggestion pointing me in the right direction 😄

[squidfunk]

To be honest, I wasn't sure if conditional definition of blocks works, so cool!

I must admit I'm not entirely sure on the implications of that last one elsewhere in the theme, looks through the src folder doesn't suggest anything obvious but it is easy enough to remove if needs be.

You're using the announcement bar feature as advertised, with the slight change that you can toggle it via mkdocs.yml, so all should be good. To me, this looks like a very clean solution, also the CSS 🚀

[AdrianoKF]

I just tried this out, however, it seems that conditionally defining blocks in Jinja isn't supported - I could not get the notification to be hidden, despite a lot of attempts.

What (kinda) worked for me was flipping the template around: defining the announce block unconditionally, and guarding the rendering of its content with an if. However, when the toggle is turned off, the base template then unfortunately renders the banner containing an inner div with a margin (which shows up above the main header as a bit of empty space). With a few CSS hacks I got to a point where toggling the banner yields the desired outcome, but it's not pretty.

{% extends "base.html" %}
{% block announce %}
  {% if config.extra.pre_release %}
    <!-- Need to reapply margin from base CSS, which is overridden in extra CSS (to fix empty banner) -->
    <div style="margin: 0.6rem auto">
      ...
    </div>
  {% endif %}
{% endblock %}

.md-banner__inner {
    margin: 0;
}

extra:
  pre_release: !ENV [DOCS_PRERELEASE, false]

[squidfunk]

If you cleverly use Jinja whitespace control, the banner should not be rendered, as the announce block will be empty:

{% extends "base.html" %}
{% block announce %}
  {%- if config.extra.pre_release -%}  <!-- See the dashes here -->
    <!-- Need to reapply margin from base CSS, which is overridden in extra CSS (to fix empty banner) -->
    <div style="margin: 0.6rem auto">
      ...
    </div>
  {%- endif -%} <!-- See the dashes here -->
{% endblock %}

[AdrianoKF]

Thanks, @squidfunk, that does the trick (TIL about the whitespace control in Jinja - I was familiar with the idea from Helm charts).

In this case, all the stylesheets in both the template and the extra CSS file can be omitted 🙌🏻