Docfx: Is there any way to create a yaml header variable and use it within markdown?

[Shazwazza]

Operation System: (Windows or Linux or MacOS)

DocFX Version Used:

2.50

Template used: (default or statictoc or contain custom template)

custom

Steps to Reproduce:

I just want to be able to define variables, both globally and hopefully within a yaml header and then reference them within the markdown file.

For example, in an md file I might have:

uid: download/4.8.0-beta00008
currentVersion: 4.8.0-beta00008
---

Then I want to be able to use the currentVersion variable/front-matter/yaml-header in my markdown file.

Is this possible? and can this also be achieved by specifying global variables in the docfx.json file?

Thanks

[climber03]

Hi, i would also be very interested in this possibility. Thanks for any suggestions!

[DMiradakis]

I've been up late for several nights trying to figure this one out. +1

[Shazwazza]

I've found a way to use Environment Variables, don't think you can use yaml headers because that information is not available in the markdown parsing context as far as I have been able to figure out.

For us for now, being able to replace env vars works ok. In our build script before we run the docfx.exe we set the env vars we want to replace and then run the exe. I wrote a blog post about how to write an 'inline' markdown plugin since it's undocumented how to do it properly and it's also a bit painful without knowing the dos/donts https://shazwazza.com/post/writing-a-docfx-markdown-plugin/

[DMiradakis]

@Shazwazza

Thanks for the informative and detailed response! I took a look at your blog late last night (I was up much later than I should've been). You are beyond me at the moment in C# fluency, but I appreciate the link to your blogpost!

I have been studying up a lot on web technologies lately, particularly Javascript. So I thought to myself, well, there's a Javascript library for _everything_, so why not try it out that way!

So it turns out that I found this awesome Javascript library for Mustache, the same templating language that DocFX uses in its templates. By combining some jQuery with the Mustache.js library, I was indeed able to dynamically render content into a test page!

To streamline this with DocFX, you would need to go into the scripts.tmpl.partial file for your template you use and add several new <script> tags:

1. jQuery
2. Mustache.js
3. A template script for rendering Mustache content.

The two downsides that I see to this are the following:

1. The data must exist in JSON, and I am still brainstorming ways on how to streamline JSON data for each and every markdown file. A 1,000 line JSON file doesn't sound ideal and neither do 1,000 separate JSON files for each markdown file you make.
2. Mustache.js must attach to a specific html element, so you'd probably have to include <div>, <span>, or similar tags in your markdown for whenever you want to render dynamic content.

And of course, back to your original question, you were interested in using YAML headers, not JSON, so this may not be desirable for you at all.

But for you and anyone else who sees, here is another way to accomplish the dynamic content rendering.

[jbltx]

I am also interested about using variables, not only in Markdown, but also in toc files (for example name: My Page Title for {{ApplicationName}}). I think it could be a good opportunity to integrate a preprocessing stage in the process. To more we could use directly MustacheJS since it's already there (Mustache.render() methods works with any text content, not only valid html content).
I also follow @Shazwazza idea about using the docfx.json file directly to set these variables.