Making the version accessible to mkdocs as an "extra" property

[bdellegrazie]

What would be the easiest way of making the version accessible to mkdocs - I'm presuming as an "extra" property?

We plan on using the macros plugin to allow the version to be explicitly used in the text.

[xvik]

If I understand correctly then your problem is to dynamically update extra properties in mkdocs.yaml

First of all, don't forget to add macros plugin to your build

python.pip 'mkdocs-macros-plugin:0.4.9'

Then select some unique name for property:

extra:
    project_version: TBD

So you could easily find and replace value:

mkdocsBuild.doFirst {
    def cfg = project.file(project.file(mkdocs.sourcesDir+'/mkdocs.yml'))
    cfg.text = cfg.text.replaceAll(/(?m)project_version:.*/, "project_version:${project.version}":
}

Should work.

(plugin dynamically updates site_url property during mkdocsBuild task using the same approach)

[bdellegrazie]

Hi @xvik,

Thanks for that. I've done almost the same thing but used the include_yaml option of the macros plugin with a templated file.
The result is the same but should reduce task ordering / caching problems.

[xvik]

The new version will provide direct support for variables with markdownextradata (installed by default, but not activated).

In gradle, variables declared as:

mkdocs {
  extras = [
     'version': "${-> project.version}",
     'foo': 'some other value'
  ]
}

Note that sensitive variables have to use closure notion in gstring to prevent immediate evaluation.

mkdocs.yml must declare a new plugin:

plugins:
  - search
  - markdownextradata

Gradle plugin would generate docs/_data/gradle.yml file before each mkdocs (including serve) task run and remove it after.

Markdownextradata plugin will automatically load generated gradle file and so it would be possible to use declared properties in docs as {{ gradle.version }} or {{ gradle.foo }}.

Some static variables (not supposed to be changed by gradle) may be declared directly in mkdocs.yml in extra section (see plugin docs).

[bdellegrazie]

@xvik that's brilliant - thank you!