markugen
Version:
Markdown to HTML/PDF static site generation tool
186 lines (179 loc) • 13.6 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<meta content="width=device-width, initial-scale=1" name="viewport">
<title>Preprocessor</title>
<link rel="stylesheet" href="../markugen.css">
</head>
<body>
<h1 id="preprocessor">Preprocessor</h1>
<p>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.</p>
<h2 id="template-expansion">Template Expansion</h2>
<p>The preprocessor works by replacing/expanding JavaScript code that is surrounded
by double curly braces <code>{{ code }}</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 <code>Hello World!</code>:</p>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.js</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-27', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-27" class="hljs language-js">{{ <span class="hljs-keyword">return</span> <span class="hljs-string">'Hello World!'</span>; }}</code></pre>
</div><p>Output from the above template:</p>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.txt</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-28', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-28" class="hljs language-txt">Hello World!</code></pre>
</div><div class="markdown-alert markdown-alert-caution">
<p class="markdown-alert-title"><svg class="octicon octicon-stop mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>Caution</p>
<p>The preprocessor will execute any code within the curly braces; therefore, it
is very important that you trust the markdown file being parsed.</p>
</div>
<h2 id="escaping-literal-braces">Escaping Literal Braces</h2>
<p>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 (<code>\</code>) like so: <code>\{{ code }}</code></p>
<h2 id="custom-variables">Custom Variables</h2>
<p>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 <a class="markugen-md-link" href="./Options.html">Options</a> page, you will see an option called <code>vars</code>.
The <code>vars</code> option is provided to allow you to define custom variables that
can be used within your templated code blocks.</p>
<p>For example, if the following code is provided to Markugen on creation, then
the string <code>You've been Marked!</code> will be available in all your templated code
blocks via the <code>vars</code> object provided to the executed code and the property
named <code>marked</code> like so: <code>vars['marked']</code></p>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.js</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-29', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-29" class="hljs language-js"><span class="hljs-keyword">const</span> mark = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Markugen</span>({
...
<span class="hljs-attr">vars</span>: {
<span class="hljs-attr">marked</span>: <span class="hljs-string">"You've been Marked!"</span>
},
...
});
mark.<span class="hljs-title function_">generate</span>();</code></pre>
</div><p>The following templated code block is an example of using the <code>vars['marked']</code>
variable within the code block:</p>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.js</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-30', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-30" class="hljs language-js">{{ <span class="hljs-keyword">return</span> vars[<span class="hljs-string">'marked'</span>]; }}</code></pre>
</div><p>The above templated code block will output the following:</p>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.txt</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-31', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-31" class="hljs language-txt">You've been marked!</code></pre>
</div><h3 id="markugen-variable">Markugen Variable</h3>
<p>Markugen will define a custom variable within the <code>vars</code> object called
<code>markugen</code> automatically. The <code>markugen</code> variable is an object with the
following structure:</p>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">markugendetails.ts</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-32', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
<div title="Save to markugendetails.ts" class="markugen-code-save" onclick="markugen.saveToFile('copy-save-32', 'markugendetails.ts', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M840-680v480q0 33-23.5 56.5T760-120H200q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h480l160 160Zm-80 34L646-760H200v560h560v-446ZM480-240q50 0 85-35t35-85q0-50-35-85t-85-35q-50 0-85 35t-35 85q0 50 35 85t85 35ZM240-560h360v-160H240v160Zm-40-86v446-560 114Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-32" class="hljs language-js">
<span class="hljs-comment">/**
* Defines the properties of the markugen variable used by the
* {<span class="hljs-doctag">@link</span> Preprocessor} when expanding templates.
*/</span>
<span class="hljs-keyword">export</span> interface <span class="hljs-title class_">MarkugenDetails</span>
{
<span class="hljs-comment">/**
* The version of Markugen used
*/</span>
<span class="hljs-attr">version</span>:string,
<span class="hljs-comment">/**
* The name of Markugen
*/</span>
<span class="hljs-attr">name</span>:string,
<span class="hljs-comment">/**
* The date/time stamp of Markugen creation
*/</span>
timestamp?:<span class="hljs-title class_">Date</span>,
<span class="hljs-comment">/**
* The platform on which Markugen was executed
*/</span>
<span class="hljs-attr">platform</span>:<span class="hljs-string">'windows'</span>|<span class="hljs-string">'linux'</span>,
<span class="hljs-comment">/**
* Markugen home page
*/</span>
<span class="hljs-attr">homepage</span>:string,
}</code></pre>
</div><p>As an example, the following templated code block will output the values of
the <code>markugen</code> variable when this page was generated:</p>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.js</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-33', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-33" class="hljs language-js">{{ <span class="hljs-keyword">return</span> <span class="hljs-title class_">JSON</span>.<span class="hljs-title function_">stringify</span>(vars.<span class="hljs-property">markugen</span>, <span class="hljs-literal">null</span>, <span class="hljs-number">2</span>); }}</code></pre>
</div><p>Output from the above template:</p>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.json</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-34', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-34" class="hljs language-json"><span class="hljs-punctuation">{</span>
<span class="hljs-attr">"version"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"2.0.5"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"markugen"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"timestamp"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"2025-03-06T15:49:36.080Z"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"platform"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"linux"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"homepage"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"https://falkorclark.com/markugen/index.html"</span>
<span class="hljs-punctuation">}</span></code></pre>
</div>
<script src="../markugen.js"></script>
</body>
</html>