Problem with include_yaml and template partials

[pvdemael]

Just started using MkDocs and discovered this plugin, awesome!

Use case

I use Material for MkDocs and want to add extra menu items(e.g. an extra Download Now link).

What works but suboptimal

What I did to make it work:
Added a variable to extra in mkdocs.yml:

extra:
  extra_tabs:
    - title: Link 1
      url: https://example1.com
    - title: Link 2
      url: https://example2.com
      icon: .icons/material/information-slab-box-outline.svg

Override tabs.html partial and add some code to generate the menu items:

{% if "extra_tabs" in config.extra %}
  <!-- Adds tab on right side of header -->
  <ul class="md-tabs__list" style="float: right;">
    {% for tab in config.extra.extra_tabs %}
        <li class="md-tabs__item md-extra-tab">
          <a href="{{ tab.url|url }}" class="md-tabs__link">{{ tab.title }}
            {% if tab.icon %}
              &nbsp;{% include tab.icon %}
            {% endif %}
          </a>
        </li>
    {% endfor %}
  </ul>
{% endif %}

What I need

I now want to use the macros plugin and use include_yaml to split data from configuration. What I thought would work:

Add the macros plugin and configure it to include an external yaml file and remove the extra_tabs variable under extra in mkdocs.yml

plugins:
  - search
  - macros
    include_yaml:
    - assets/data/extra_tabs_data.yml

Created a file extra_tabs_data.yml containing the data needed:

extra_tabs:
  - title: Link 1
    url: https://example1.com
  - title: Link 2
    url: https://example2.com
    icon: .icons/material/information-slab-box-outline.svg

In the tabs.html partial, access the extra_tabs variable to generate the menu items

However this did not work, nothing was rendered.

What I tried

In the tabs.html partial, I used extra_tabs , config.extra.extra_tabs and some other combinations as variable and removed the if clause.

I used a key: value pair to include the yaml file using et: assets/data/extra_tabs_data.yml. During serving, an error was thrown: jinja2.exceptions.UndefinedError: 'mkdocs.config.defaults.MkDocsConfig object' has no attribute 'et'

Questions

1. Can overridden partials access the variables from included yaml files by the macros plugin?
2. If so, how can I access these variables meaning what the exact syntax is to acces variables in included yaml files?
   I thought I would be able to use the extra as stated in use include_yaml macro to add the nav section does not work #181
3. Is there another way using the macros plugin to achieve this?

[fralau]

Thanks for your question. I am not sure exactly what issue you are meeting.

Perhaps a formatting issue in the config.yaml file? Here is what I see:

plugins:
  - search
  - macros
    include_yaml:
    - assets/data/extra_tabs_data.yml

The last line looks suspicious to me, because there should be an indentation.

Since I do not see why there should be an et attribute in that file, was it unintentional? Would it be worth thoroughly checking the syntax?

[pvdemael]

Sorry, was a mistake during formatting of post. There is an indentation.
I got to the et as shown below. I defined it as a key-value pair as the documentation of the plugin describes but is does not work

plugins:
  - search
  - macros
    include_yaml:
      - et: assets/data/extra_tabs_data.yml

When the site is server, I see the following which suggests the file is loaded well.
I defined an attribute version under extra which is also detected well by the plugin.

INFO    -  [macros] - Loading yaml file: C:\...\mkdocs_site\docs/assets/data/extra_tabs_data.yml
INFO    -  [macros] - Extra variables (config file): ['version']
INFO    -  [macros] - Extra filters (module): ['pretty']

In tabs.html, I tried to access the attribute as follows

• without key

  include_yaml:
    - assets/data/extra_tabs_data.yml

  {% for tab in config.extra.extra_tabs %} or {% for tab in extra_tabs %}

  Page renders without errors but without extra links

• with key

  include_yaml:
    - et: assets/data/extra_tabs_data.yml

  {% for tab in config.extra.et.extra_tabs %} or {% for tab in et.extra_tabs %}

  Page not rendered, exits with error

Is there something I am missing? I have doublechecked syntax and it seems to be correct.

[fralau]

In the second case I would remove the dash, since you want key/value pairs. If I am not mistaken, here you have defined a list of dictionaries, and that is not what you want (it is then normal that the key et is not found).

My best advice would be dump the content of config.extra (see how to do thatt) and go ahead according to what you find..

[pvdemael]

Thanks for the help.
I have tested and a dash is always required, with or without key, otherwise an error is thrown:
ERROR - Config value 'plugins': Plugin 'macros' option 'include_yaml': Expected type: <class 'list'> but received: <class 'dict'>
So I printed out the debugging information and got the following output

• with key

  et	dict	extra_tabs = [{'title': 'Link 1', 'url': 'https://example1.com'}, {'title': 'Link 2', 'url': 'https://example2.com', 'icon': '.icons/material/information-slab-box-outline.svg'}]

• without key

  extra_tabs	list	[{'title': 'Link 1', 'url': 'https://example1.com'}, {'title': 'Link 2', 'url': 'https://example2.com', 'icon': '.icons/material/information-slab-box-outline.svg'}]

The following code in a markdown file renders the attributes.

• with key

  {% for tab in et.extra_tabs %}
      {{ tab.title }}
  {% endfor %}
  

• without key

  {% for tab in extra_tabs %}
      {{ tab.title }}
  {% endfor %}
  

BUT

The same code in main.html does not work, e.g

{% extends "base.html" %}

{% block content %}
    {% for tab in extra_tabs %}
        {{ tab.title }}
    {% endfor %}
{% endblock %}

• with key
  jinja2.exceptions.UndefinedError: 'et' is undefined

• without key
  NOTHING is rendered

So it seems that the attributes included by the macros plugin are not accessible by the jinja2 template files.

[fralau]

Ah 💡, I got it! Thank you for your patience, I did not see it immediately.

It is normal that it's not working: the Mkdocs-Macros jinja2 engine (which works on markdown files) is not the same as the MkDocs templating engine (which works on html files).

What you want to do is to trickle the variables to the MkDocs templating engine. You would need a little Python to achieve that effect, but it should be easy.

If I wanted to use those data only in the html partial templates, I would simply define them in the module.py file.

[pvdemael]

No probem. I was already very happy with your fast replies :-)
I am a new user and still must get used to the ecosystem.
I will look into your suggestion. I will definitely use the macros plugin too.

[fralau]

Now that you mention it, we could do something bold for a future development: we could automatically trickle part or all the variables into the MkDocs engine. 🤔 💡 .

Technically, it would be fairly easy to do. The main question would be to make sure that there are no bad side effects.

[pvdemael]

That would be a super handy feature!