Preprocessor

Markugen provides a mechanism for executing JavaScript within your markdown files before they are parsed and converted to HTML. The mechanism is known as the Markugen preprocessor. The preprocessor executes before the markdown parser allowing for dynamically generated content.

Template Expansion

The preprocessor works by replacing/expanding JavaScript code that is surrounded by double curly braces {{ code }} and replacing the template with the return value of the JavaScript within the braces. For example, the following template code will be replaced with the words Hello World!:

.js
{{ return 'Hello World!'; }}

Output from the above template:

.txt
Hello World!

Caution

The preprocessor will execute any code within the curly braces; therefore, it is very important that you trust the markdown file being parsed.

Escaping Literal Braces

Since Markugen's preprocessor interprets double curly braces as templates to be expanded, you will need to escape sets of double curly braces if you want the preprocessor to use literal braces. To escape the braces, just prepend the open brace with a backslash (\) like so: \{{ code }}

Custom Variables

The preprocessor is also capable of providing the templated code blocks with custom variables defined at the time the Markugen object is created. Referring back to the Options page, you will see an option called vars. The vars option is provided to allow you to define custom variables that can be used within your templated code blocks.

For example, if the following code is provided to Markugen on creation, then the string You've been Marked! will be available in all your templated code blocks via the vars object provided to the executed code and the property named marked like so: vars['marked']

.js
const mark = new Markugen({
  ...
  vars: {
    marked: "You've been Marked!"
  },
  ...
});
mark.generate();

The following templated code block is an example of using the vars['marked'] variable within the code block:

.js
{{ return vars['marked']; }}

The above templated code block will output the following:

.txt
You've been marked!

Markugen Variable

Markugen will define a custom variable within the vars object called markugen automatically. The markugen variable is an object with the following structure:

markugendetails.ts

/**
 * Defines the properties of the markugen variable used by the 
 * {@link Preprocessor} when expanding templates.
 */
export interface MarkugenDetails
{
  /**
   * The version of Markugen used
   */
  version:string,
  /**
   * The name of Markugen
   */
  name:string,
  /**
   * The date/time stamp of Markugen creation
   */
  timestamp?:Date,
  /**
   * The platform on which Markugen was executed
   */
  platform:'windows'|'linux',
  /**
   * Markugen home page
   */
  homepage:string,
}

As an example, the following templated code block will output the values of the markugen variable when this page was generated:

.js
{{ return JSON.stringify(vars.markugen, null, 2); }}

Output from the above template:

.json
{
  "version": "2.0.5",
  "name": "markugen",
  "timestamp": "2025-03-06T15:49:36.080Z",
  "platform": "linux",
  "homepage": "https://falkorclark.com/markugen/index.html"
}