Can you rename folder names at build?

[Andre601]

I have a site where I have a versioned assets folder, meaning a path may be similar to the following:

assets/
  v0.1-alpha/
    setup.lua

I would like to try and have the v0.1-alpha folder be made created/renamed based on a value in the mkdocs.yml config, alongside any other placeholder inside a file to reflect this.

So, if the setup.lua file contains print("This is version {{ script_version }}!") and I set v0.2-alpha as extra.script_version in mkdocs.yml, should the folder path be:

assets/
  v0.2-alpha/
    setup.lua

and the content in setup.lua print("This is version v0.2-alpha")

Is this achievable?

[fralau]

Thanks for your question!

Before I answer, I would need to better understand the workflow: where the original information would be on the lua version, what would be in the mkdocs.yml file at this point, and what action would be required?

[Andre601]

I'm confused about what you mean with "where the original information would be on the lua version".

As for the current mkdocs.yml file: https://pastes.dev/4nCRWnBo7Z

Also, I already explained my primary goal, so I won't repeat it and instead give a summary:

• If possible, have the v0.1-alpha folder be renamed on mkdocs build to the value of script_version.
• Inject the script_version value into markdown and lua files (So basically the normal jinja behaviour effectively).

[fralau]

Thanks, the file mkdocs.yml makes it clear.

What I would do is to use a define_env() hook in a main.py file, to do what you need.

def define_env(env):
   "Hook for the actions"
    new_directory = f`assets/{env.variables.script_version}/setup.lua`
    
    # Make the changes here

[Andre601]

Thanks. Tho, this doesn't make it much clearer on how I would actually apply the actual changes to MkDocs itself, so that it accepts and makes the necessary changes for the generated site.

Also, by the looks of it does the Plugin ignore non-markdown files, as the lua file doesn't get the jinja value changed.

[fralau]

@Andre601 Certainly, MkDocs looks for markdown files. You would have to write the instructions to open the lua file and modify it (typically using a regex).

But within any markdown page, you should be able to write:

The new version of the lua file is {{ script_version }}.

[Andre601]

Honestly... this doesn't help me at all.

I was hoping the macros plugin would have some support to edit non-markdown files too (basically anything within the docs folder)...

[fralau]

I understand.

In general, MkDocs is not used to edit markdown files, but to generate target html files from those source files. It's a sort of compiler, and a compiler is not supposed to modify the source files.

The purpose of MkDocs-Macros, within MkDocs, is to allow:

1. To use of variables in Markdown files, or other Jinja2 instructions.
2. To program macros (which are Python functions that generate text), as well as some transformations to the output files.

That's why it will not modify the source files (mkdocs.yml, Markdown, assets). If you need to do that, the best would be to write a pre-processor, that would run before mkdocs build or mkdocs serve.

What you could do, is to use the Jinja2 include instruction in your pages. In your case, it could be a Markdown file or HTML file, etc. But once again, you need to set up a pre-processor to regenerate that file when needed.