Change block overrides depending on OS environment variabled

[Enn83]

Hi !

I am currently looking for a way to show an announcement bar only when I build the documentation for a branch different than master from a GitLab pipeline, so by using the $CI_COMMIT_BRANCH variable in branch pipelines.

Option °1:

I was wondering if there is a way to do something like this in the overrides/main.html (jinja2) file, i.e. get environment variables:

{% extends "base.html" %}

{% set DOC_BRANCH = os.environ.get('CI_COMMIT_BRANCH', False) %}
{% if DOC_BRANCH != "master" %}
	{% block announce -%}
		Be careful, you are currently reading the documentation for a branch under development: {{ DOC_BRANCH }}.
	{%- endblock %}
{% endif %}

I think of course I can't use python syntax in jinja2 files, and tutos I found on internet say to add a custom_filter which seems to be added in the python file that call the jinja2 process (but I'm not sure ...).

Option °2:

I also find this Q&A discussion Versioning - Pre-Release Banner #5803 which seems not bad for what I want to do, I just have to replace the value in the mkdocs.yml file by the branch name before starting the build (for example with a sed -i ... in the pipeline job). It is not perfect but better than nothing. However I got this error when building the site :

Config value: 'extra'. Error: The configuration is invalid. The expected type was a key value mapping (a python dict) but
            we got an object of type: <class 'list'>

... when I use this ...

{% set example = config.extra.example %}

Do you know if a thing like this can be done easily, or why I got this error when I try the second option?

Thank you in advance!

[squidfunk]

Thanks for asking. #5803 was also immediately coming to my mind. You can use environment variables in MkDocs, so something like this should work, setting the branch name to master by default:

extra:
  branch: !ENV [BRANCH, "master"]

And then call MkDocs like so:

BRANCH=`git branch --show-current` mkdocs build

In your override:

{% if config.extra.branch != "master" %}
  {% block announce -%}
    Be careful, you are currently reading the documentation for a branch under development: {{ config.extra.branch }}.
  {%- endblock %}
{% endif %}

[Enn83]

I'm sorry, I completely forgot that there was documentation for mkdocs in addition to that for material-mkdocs 🤦‍♂️.

Unfortunately I can't try this until Wednesday, I'll come back as soon as I have a result!

Note: Is it normal for the BRANCH variable declaration to be on the same line as mkdocs build or is a line break missing?

[squidfunk]

There are tons of ways to define environment variables – this is one of them. Please check the documentation of your operating system how to define environment variables.

[Enn83]

I've tried it and it works like a charm 😊!

I just added config. before each extra.branch :

{% if config.extra.branch != "master" %}
  {% block announce -%}
    Be careful, you are currently reading the documentation for a branch under development: {{ config.extra.branch }}.
  {%- endblock %}
{% endif %}

Thanks a lot! Now my documentation is even more beautiful!

[squidfunk]

Awesome! I corrected my example.

[Enn83]

I'm back here to make an update, with this code snippet, the announcement appears all the time, even if the branch is on "master".

{% if config.extra.branch != "master" %}
  {% block announce -%}
    Be careful, you are currently reading the documentation for a branch under development: {{ config.extra.branch }}.
  {%- endblock %}
{% endif %}

I had to swap the "block" and "if" and now the announcement disappears if I'm on the "master" branch and appears in other branches:

{% block announce -%}
  {% if config.extra.branch != "master" %}
    Be careful, you are currently reading the documentation for a branch under development: {{ config.extra.branch }}.
  {% endif %}
{%- endblock %}

I don't really know jinja2 so I don't know if this is a limitation or if the first syntax is wrong ...

Also, in the second case, the minus sign in {% block ... -%} and {%- endblock %} are useful because they remove empty new lines to hide completely the announcement block it is empty.