Defining variables outside of mkdocs.yml

[syeda-git]

Hello,
How can i define global variables outside of mkdocs.yml file? I see this row in the table but what an external yaml definition file look like. A sample file and how it will be called in mkdocs.yml file will be great.

2. | global | contributor | in external yaml definition files

Syed

[fralau]

In general, yes there are 5 different ways for you to define variables, with 3 ways of defining global variables (see documentation page).

But to help you find the best one, I would need you to be more specific with your request?

[syeda-git]

I would like to set automated builds (Jenkins). There is a single doc set that needs to be published in different flavors. Let's take the example of a doc that is published for Windows, Linux, and Mac. I would like to define the Windows variables in a file different than the other two. So, there will be 3 files for variable definitions. The Windows build picks the Windows variable definition and so on.

I think this is possible. My assumption is that there would be 4 yaml files - first is the main mkdocs.yml and the other three for variables. Is there a need for mkdocs.yml to call the variable files? If yes, how?
Then, what would be the structure of a variable yaml file. Would it only include the variables or the regular site_name, theme and other parameters that are usually in a mkdocs.yml file?

Syed

[fralau]

See the part of the documentation on external YAML files.

[syeda-git]

As per that page, the user has to specify in mkdocs.yml which external YAML file to use. There is just one mkdocs.yml file. When running a build for Windows variables, the user has to manually specify that file in mkdocs.yml. Then, when running a build for Linux variables, the user has to remove the previous (Windows) yaml and specify a Linux yaml. So, from automation perspective, where builds start daily without user intervention, how is this possible? Am i missing something?

Syed

[fralau]

Hi @syeda-git I am not sure I am tracking. In principle the mkdocs.yaml file should be invariant for all platforms. There is no conditional config mechanism that I am aware of, according to platform.

The idea of conditional statements (on a "rules based" engine) is intriguing, and could be interesting... 🤔

Meanwhile, I would use main.py to read a different config files (yaml is file) according to the platform, and then register those variables (by adding them to env.variables).

If you know how to write Python code, that's quite straightforward to do. Something like this should work (I haven't tested):

import platform
import yaml

def define_env(env):
    """
    This is the hook for defining variables, macros and filters

    - variables: the dictionary that contains the environment variables
    """

    PLATFORM = platform.system()

    if PLATFORM == 'Linux':
        config_file = r'...'
    elif PLATFORM == 'Windows':
        config_file = r'...'
    elif PLATFORM == 'Darwin':
        config_file = r'...'
    

    with open(config_file) as file:
        # read the values from the file into a dictionary
        config_specific = yaml.load(file, Loader=yaml.FullLoader)


    # update the variables with the values
    env.variables.update(config_specific)