parse jinja templates on non-markdown pages

[spettinichi]

I have a project where I store sample source files so users can clone the repository and run them as is, but I also want to embed them into markdown pages for usage with mkdocs as well. I followed this to be able to embed the source files https://mkdocs-macros-plugin.readthedocs.io/en/latest/tips/#i-would-like-to-include-a-text-file-from-line-a-to-line-b
This works great, except that variables in the source files will not be evaluated and replaced.

I don't see a way to accomplish this. I believe I will have to add variable parsing within my python file, but this plugin does not have a function to pass a variable and have it evaluated by jinja rules and return the result, so it seems I would have to duplicate much of the functionality of this plugin which is not ideal.

Is there something I am missing, or is this something of interest to include into the project?

[github-actions[bot]]

Welcome to this project and thank you!' first issue

[spettinichi]

I ended up getting this working and submitted a PR for the changes to the documentation page linked above
#161

[fralau]

Thanks! Would this work for you?
https://mkdocs-macros-plugin.readthedocs.io/en/latest/advanced/#including-snippets-in-pages

You may also use the Jinja2 include directive.

[SadParad1se]

Hi, I have a similar problem. I have a YAML file (Jinja template) in the docs directory. However, I'm unable to render its variables.

The file (docker-compose.yml) contains a configuration that the user can download directly. For example:

foo:
  bar: {{ predefined_value }}

(The variable predefined_value is defined in an external file.)

Project structure:
.
├── docs
│   ├── getting-started
│   │   ├── docker-compose.yml
│   │   └── quick-start.md
│   ├── index.md
└── mkdocs.yml

Is there a way to render variables on non-markdown pages?

[fralau]

You may use the Jinja2 include directive. Include renders the file included.

[SadParad1se]

You may use the Jinja2 include directive. Include renders the file included.

The problem is that I don't want to include the file, but leave it as it is and let the user download it using cURL for example.
If I include the configuration inside a Markdown file, the user won't be able to use it.

[fralau]

I am not sure I understand what you want to do with your yaml file. Could you explain what the workflow is and, what problem you wish to solve?

[SadParad1se]

I have two files.

docs
├─ docker-compose.yml
└─ instructions.md

The docker-compose.yml file contains a configuration with empty Jinja variables.
The instructions.md file contains instructions on downloading and running the configuration file. The user will download the file itself (for example: curl -O {{{ config.site_url }}}/docker-compose.yml). The docker-compose.yml is only mentioned, not included in the page itself.

The problem is that the Jinja variables in the docker-compose.yml file are ignored (not rendered) since it's not a markdown file.
Is there a way to render variables in files that are not markdown (do not have the .md file type extension)?

[fralau]

So wou wish to render an external page, that will not be displayed? Where do you want the result to be stored?

[spettinichi]

@fralau Aha the include does seem to do the trick! My PR is unnecessary (though may still be handy for anyone who needs to include only certain lines and wants the variables parsed).
I think it would be helpful to link to that bit about includes under the tips and tricks, since they are related topics. Also, on the "Including external files in pages" the example is blank, which is also confusing and I only understood it with the direct jinja link you provided.

@SadParad1se I think I understand what you are going for, but am not sure that this project is the correct target to accomplish that. What you are working on is not related to mkdocs, so I don't want to speak for the author, but that may be outside the scope of this plugin.
I did look around and found there is a jinja-compose tool you can use to wrap docker-compose and parse jinja variables. This may be helpful to you: https://github.com/sinzlab/jinja-compose Since you are making the resulting file available for download and not just using it at build time I'm not sure if this will cover your use case entirely, but I suspect there is an existing tool out there to write the result to a usable file!

[fralau]

@spettinichi In the latest version of the doc, including external files has been included under Advance use (there is a problem with the display of the code examples, because the readthedocs environment seems to "eat" the include directives).

@SadParad1se I agree that mkdocs-macros might not be the ideal tool for that, and you might need an external jinja2 engine (or, at worst, write your own; it's not very difficult).

[SadParad1se]

Okay. Thanks to both of you.