Interpolated values within Markdown documentation

This relates to the blog post made by @jespern.

Big Picture

Looking to write technical documentation that references variables defined in external files and have the dereferenced values interpolated/woven into an output document format. When the output document is rendered as HTML for a BitBucket project page, for example, the variable references should be substituted with values from those definition files.

Replicate

Consider the following Markdown (e.g., README.md):

![Logo]($application.directory.images$/logo.png)
$application.title$
===
$application.description$
![Screenshot]($application.directory.images$/screenshot.png)

Along with the following standalone variable definition file:

application:
  title: Application
  directory:
    images: images
  description: $application.title$ is almost as amazing as BitBucket.

Using YAML as the variable definition source is arbitrary. A factory design pattern based on some criteria (such as the file name extension) would allow definitions in JSON, TOML, XML, or any other machine-readable format.

Expected Results

![Logo](images/logo.png)
Application
===
Application is almost as amazing as BitBucket.
![Screenshot](images/screenshot.png)

Actual Results

No substitution is preformed, so the README.md file is displayed as:

![Logo]($application.directory.images$/logo.png)
$application.title$
===
$application.description$
![Screenshot]($application.directory.images$/screenshot.png)

Additional Details

Prior to the markdown (e.g., README.md) being rendered into HTML for display, another link in the process chain performs a simple Aho-Corasick substitution for the interpolated variable values within the document. The document is then rendered into HTML as normal.

Part of the problem is that the variables must be able to reference other variables, with a variable interpolator to extract the correct dereferenced value (see $application.description$, above).

Variable Name Delimiters

Another issue is that it should be possible to define the variable delimiters and separators, such as:

• {{{{ application.title }}}} – {} and {} with a . separator;
• $application.title$ – $ and $ with a . separator; or
• optionally, `r#x( v$application$title )` – `r#x( v$ and )` with a $ separator, which would be useful for evaluating inline R statements, evaluated using knitr.

Not a Template Language

What is being proposed is not another template language, but two related ideas.

First, variable substitution for arbitrary definitions using a dot-separated notation and recursive interpolation. Second, the ability to set a prefix and suffix delimiter used for finding and replacing variables with a resolved value map.

I've developed both of these in Java. The first is about 19 lines of code. The second requires a kind of variable decorator pattern, which is also fairly trivial in terms of LoC (fewer than 50 lines).

Code that deals with variable substitution sometimes hard-codes variable delimiters in multiple places, which is a violation of DRY. Using a constants is better practice, but still violates DRY when those constants are referenced in multiple places, rather than being constructed dynamically using a factory pattern based on some arbitrary criteria (such as a file name extension).