Demonstration of jmarkdown

jmarkdown is a full-featured variant of markdown which provides the ability to define new syntax extensions in the markdown file itself. The extensions can be simple — where you specify only the starting- and ending- delimiters — or complex — where you specify a regular expression, possibly with groups. The text identified by the extension can then be manipulated, processed by the markdown interpreter, or inserted into arbitrary HTML. In addition, jmarkdown supports the evaluation of JavaScript included in the markdown file at the time the markdown code is processed. The JavaScript code can be used to define syntax extensions or to generate HTML output, or to use Cheerio as a post-processor to manipulate the HTML output generated by jmarkdown.

The syntax extensions can take advantage of the full set of Unicode characters, allowing you to define intuitive markup for certain effects. For example, this markdown file defines extensions using Unicode delimiters so that

↑Small caps↑ becomes Small caps
⌜strings like in the TeXBook⌝ becomes strings like in the TeXBook

Extensions can also be specified using regular expressions, allowing you to configure things so that

Consider points p1, p2, p3,... where pk is (xk, yk, zk) becomes consider points $p_{1}$, $p_{2}$, $p_{3}$,... where $p_{k}$ is $(x_k, y_k, z_k)$

As for embedding JavaScript in the markdown, here’s a fun example. With a suitable JavaScript function defined:

rainbow("And options can be specified!", {duration: 10}) becomes And options can be specified!

1. Motivation

This project started out small, and then grew in its ambition. The beginning was this: I’ve always found the default syntax of markdown to be a little annoying. Why aren't italics defined /like this/ rather than *like this*? It also seemed like boldface was better indicated *like this* rather than **like this**. And, finally, shouldn’t underlining be indicated __like this__? That just seems more… rational, you know.

From that initial goal — to create a custom markdown interpreter which catered to my own peculiar syntax preferences — this project has since grown into a full-featured markdown interpreter which allows you to define custom syntax extensions in the markdown file itself! There’s also a lot more.

Anyway, jmarkdown uses marked.js to adjust and extend the syntax of markdown in a number of ways. It also preloads several additional extensions from the marked.js extension library to make it behave more like multimarkdown, with some additional features multimarkdown doesn’t have. Here’s a list, in no particular order, of all the features jmarkdown offers:

2. Syntax adjustments

What about emojis? For the octocat emojis, you put the name of the emoji between colons, so that writing :heart: gives

. Consult the list of octocat emojis for the full list… there are a lot.

For FontAwesome, you’ll need to link to the appropriate javascript package in the header but, once you do, then you enter a FontAwesome icon by including the relevant class name. So :fa-thumbs-up: yields . If you want to add additional styling class, you don’t need to add the fa- prefix to them (they will be attached automatically). Thus, :fa-thumbs-up lg rotate-90: yields . N.B. you need to have the fa- part of the icon name immediately following the opening colon.

Normal markdown doesn’t provide any easy way of adding classes or an id to elements. jmarkdown uses the directive syntax (see below) to specify that classes or an id should be added to the parent element. So, for example, if .red and .lightgreen are classes with the appropriate CSS definitions, then we can do the following:

3. Disabled syntax

Most of normal markdown syntax is supported, but there are two which are disabled. These are:

The rule that two empty spaces indicates a line break is disabled because it is a really bad markup rule. It's problematic enough to have semantically significant white space at the start of a line, but we've figured out how to deal with that after years of working with Makefiles and Python. But semantically significant whitespace at the end of a line is deeply problematic because there's simply nothing in the source file to reveal that you have two spaces at the end of a line, unless you have a syntax highlighting scheme in your editor to flag that. Anyway, jmarkdown provides a better way of explicitly indicating line breaks via syntax extensions.

As for why I disabled indented code blocks… basically, that rule creates havoc with using indents to indicate hierarchical list structures. If you want to allow nested description lists or nest numeric lists, it's all-too-easy for indented code blocks to be created when you don't want them. Anyway, fenced code blocks are far superior, so just use them.

4. Tables and alerts

I’m not going to say much about tables, but here are some quick demonstrations.

4.1. Example 1

H1	H2	H3
This cell spans 3 columns

4.2. Example 2

This header spans two columns AND two rows	Header A
Cell A	Cell B	Cell C

4.3. Alerts

A detailed description for these can be found here. The formatting below isn’t perfect, but that just requires some CSS tweaks.

5. Description lists

Normal markdown, by default, doesn’t include syntax for creating description lists. The syntax used by jmarkdown for description lists is shown below. It also allows description lists to be nested. For some reason, this doesn’t play well with the footnotes extension, so if anyone would like to help debug it, that would be awesome.

6. Math support

MathJax integration is enabled out of the box, with the default being including the math as SVG. All forms of LaTeX syntax are supported ($...$, $$...$$, $...$, \[...\]), with whatever text appears between the math delimiters being fully protected from the markdown interpreter. This means that $\alpha^*$ yields $\alpha^*$ rather than starting a boldface element.

7. Enhanced lists

jmarkdown includes the marked-more-lists extension, which provides support for alphabetical and roman numeral lists.

8. Code highlighting

jmarkdown supports standard fenced code blocks with syntax highlighting. E.g., here is some HTML:

9. Bibliographic support

jmarkdown generates an HTML file which is configured to use Biblify, a Javascript-based “implementation” (so to speak) of a subset of BibTeX commands which is processed entirely within the browser. I initially wrote this to provide bibliographic support for reveal.js presentations, but that code proved useful to include here, too. You can specify the bibliographic style and the bibliography database file which is used. (At the moment, this is hard-coded into the jmarkdown source, so I need to fix this in the future.)

If you add any bibliographic citations they will be parsed. So, for example, writing \cite{Alexander:2024} will be processed and appear like this: \cite{Alexander:2024}, with the bibliography being appending to the end of the document after any footnotes. If you have requested a table of contents, an entry for that will be automatically included.

Bibliography support is initially disabled because jmarkdown doesn't know what additional files to use. To enable bibliography support, you need to tell it what bibliography file to use and which formatting scheme you want. This is explained below.

10. Directives syntax

The marked-directives extension provides support for directives. This is a particular form of markdown which allows you to include inline elements, block elements, or higher-level containers. For example, an inline element, like a span, is created like this: :span[contents]{#id .class1 .class2 key=value}. So, if the class .red sets the background of an element to red, then you insert a red span like this:

Block-level directives are prefixed with ::. To insert an empty unordered list with a specific id (say, to target with JavaScript later), just type ::ul{#my-id}. If you inspect the elements after this paragraph, you should find just such an empty element.

Where directives become particularly interesting is when we use them as containers. Here’s how to enclose part of your markdown file in a <section> tag:

Did you see the use of the inline directive in the list? That behaves as you think it should, i.e.,

The tag name which appears after the ::: can be a predefined HTML tag, or it can be a custom web element you’ve defined yourself. For example, when I'm marking exams I define a minimal custom web element named exam-feedback so I can write

and that custom element will add some additional HTML decorations around the text. It also means that you can target that particular set of feedback for inserting local bibliographies with Biblify. (See the Biblify website for details.)

10.1. Comments and optionally included text

It’s possible to define new directives which provide additional functionality. Since most markdown flavours don’t provide a way to comment out text, in the markdown source, jmarkdown provides a container directive which does that. So writing the following:

will cause everything from the start to the end of the directive to be omitted from the output. What if you decide, later, that you want to include it? Simply pass a setting which says to do that:

The comment directive is intended for commenting out parts of the markdown source. Sometimes, though, you might want to mark parts of the text for optional inclusion, for reasons that have nothing to do with it being a comment. Like answers for a question set. To handle these cases, jmarkdown supports the following line in the metadata header:

The line after Optionals should be a space-separate list of names, for the custom directives. All optionals will default to being not included. If you would like them to default to being included, simply put [true] after the name. If you want to be pedantic, there’s no harm in adding false between the square brackets syntax (e.g., answers[false]).

In addition, directives can include more than three :, to indicate higher levels of nesting. So, in our hypothetical quiz case, you could write the following:

If you want to generate the answers, simply change the declaration in the header to

10.2. Strategic-form games

jmarkdown defines a couple of extra directives which I find useful. The first is for showing strategic-form games. The syntax is pretty straighforward and is virtually the same as the notation used for typesetting strategic-form games in LaTeX. The only difference is that no \\ is needed at the end of the line, and there is no & character before the first column strategy label. Here’s what it looks like:

The extension parses the input and generates a <table> having the right form. All of the grid lines are drawn by CSS and can be customized. jmarkdown throws in some CSS at the start of the HTML output so that the games look more-or-less right out of the box.

One cool thing is that the text give to the row, column and caption options can (a) span multiple lines (if you have a really long name for the game) and (b) are passed through the markdown interpreter so you can do some tricksy things with it (such as include footnotes). E.g.,

10.3. Demonstrating markdown code

You’ll have noticed that this web page has a lot of side-by-side demonstrations of markdown code and the formatted output. That, too, was generated using a special jmarkdown extension. A special directive named markdown-demo takes its content and creates two <div> containers, with the left showing the markdown code and the right showing the formatted output. So, for example, the following:

That’s very useful because you only have to write the markdown code once, which guarantees that the demo and the output will never be out of sync.

10.4. Support for Mermaid diagrams

jmarkdown provides a custom directive which detects Mermaid diagrams and will generate HTML so that they will be automatically detected and formatted.

10.5. Support for TiKZ diagrams

If you have LaTeX installed, jmarkdown provides a special directive which can be used to typesetting TiKZ diagrams. The LaTeX code contained in the directive is processed as follows:

10.6. Sources and targets

HTML is a very expressive language and normal markdown allows for only a fraction of that to be expressed. In normal markdown you can’t, for example, construct a two-column table showing two different snippets of code, in different languages, side-by-side.

jmarkdown provides a very simple solution which greatly increases what can be done. The idea? It uses an inline directive to mark a location as a “target” and then a container directive to act as a “source” for that target, with the id of the target given. Once the HTML has been constructed, jmarkdown uses cheerio to replace the target with the contents of the source. Essentially, you can think of sources and targets working together to say “put this content there”.

JavaScript	Python
`function foo() { let x = 10; let y = 20; return x+y; }`	`def foo() x = 10 y = 20 return x+y`

There's also a special syntax abbreviation for indicating a target. If you write 🎯target-id that will create a target exactly the same as if you wrote :target[target-id].

Multiple targets for the same id can exist. The source will simply be cloned before each replacement.

JavaScript 1	JavaScript 2	JavaScript 3
`function foo() { let x = 10; let y = 20; return x+y; }`	`function foo() { let x = 10; let y = 20; return x+y; }`	`function foo() { let x = 10; let y = 20; return x+y; }`

11. Anchors

An “anchor” is simply an empty element that you can link back to from elsewhere in the page. In a jmarkdown file it is written as ⚓️id (that’s the unicode anchor symbol). When jmarkdown encounters that bit of syntax, it creates an empty <span> with an id set to whatever text followed the anchor.

12. Table of contents

If you want a table of contents included, simply add {{TOC}} to the relevant point of the markdown file. Easy.

13. Metadata header

When jmarkdown starts processing the file, it checks to see if the first line of the file contains a line of the following form:

If it finds something like that, it assumes that the document contains a metadata header. It then reads the header until it encounters a line beginning with at least three hyphens. It strips off the header, processes it, and then pushes the rest of the file through the markdown interpreter. When processing the header, the values assigned to keys can span multiple lines, and the same key can appear multiple times. (What happens when the same key appears multiple times depends on how that key is interpreted — more details in a moment.)

Title

The value of this key will be wrapped by <title></title> tag in the <head> of the output HTML.

Biblify activate

Initially, jmarkdown doesn't attempt to provide support for bibliographies because it doesn't know what bibliography file to use or what style you want. Once that information has been provided, either in the metadata header or in a config.json file (see here) you need to tell jmarkdown to switch on bibliographic support. To do that, set the key Biblify activate to true.

Bibliography

This should be a relative path specifying a BiBTeX bibliography database, which will be used by Biblify to process any citations in the HTML output.

Bibliography style

Biblify comes with a few formats preloaded. These are 'apa', 'harvard1', 'vancouver', 'bjps', and 'chicago'. If you specify one of these as the value for this key, that will be the output format. Any other string will be interpreted as a relative path to a CSL style file that will be used. Biblify uses citation.js behind the scenes, and citation.js uses Citation Style Language files to know how to format the bibliography.

Body classes

Any text here will be given to the class attribute of the <body> tag in the output HTML. This allows you to trivially change the appearance of the markdown file by writing CSS that takes the body classes into account.

CSS

The value of this key should be the name of a CSS file, with an optional relative path from the location of the markdown file being processed. This will be added to <link> tags in the <head> of the document.

If the header has multiple CSS keys, each of the files will appear in a separate <link> tag in the output HTML. The precise way this is done is explained below in the discussion of how mustache is used to process the output template.

Custom element

This provides an easy way to define custom web elements that play well with container directives. Consider the following markdown code:

:::that-container
Some text /inside/ a *container*
that has $\alpha$ math, too.
:::

The default behaviour of containers converts that into the following HTML:

<that-container>
Some text <em>inside</em> a <strong>container</strong>
that has $\alpha$ math, too.
</that-container>>

If you haven’t defined a custom web element named <that-container>, it will still be displayed in modern browsers — it just won't do anything special. But what if you want to customise its appearance? That's what this header element allows. If you write something like:

Custom element: that-container
	<p part='top'><strong>The start of my container</strong></p>
	<slot></slot> 
	<p part='bottom'><strong>The end of my container</strong></p>

When the markdown file gets compiled, a <script> tag is automatically generated and inserted at the beginning of the HTML file which will register a custom web element. In this case, the automatically generated script tag would look like the following:

 <script type="module">
   class custom_element extends HTMLElement {
     constructor() {
       super();
       // Create a shadow root
       this.attachShadow({
         mode: 'open'
       });
       // Set the shadow DOM's content
       this.shadowRoot.innerHTML = `<p part='top'><strong>The start of my container</strong></p>
<slot></slot>
<p part='bottom'><strong>The end of my container</strong></p>`;
     }
   }
   customElements.define('that-container', custom_element);
 </script>

And so you would get the following output:

Markdown code

Markdown output

:::that-container
Some text /inside/ a *container*
that has $\alpha$ math, too.
:::

Some text inside a container that has $\alpha$ math, too.

Highlight theme

The name of the theme which highlight.js should use when formatting source code.

HTML header

All of the text given as the value of this/these key(s) will be written verbatim to the output HTML, right before the closing </head> tag.

HTML footer

All of the text given as the value of this/these key(s) will be written verbatim to the output HTML, right before the closing </body> tag.

Script

The value of this key should be the name of a javascript file, with an optional relative path from the location of the markdown file being processed. This will be the value of the src attribute in a <script> tag in the <head> of the document. If you need to include scripts with additional attributes, that will need to be done using the HTML header key.

LaTeX preamble

If you are using jmarkdown to process TiKZ code, you might need to customise the preamble. The value of this key will be inserted verbatim into the LaTeX preamble.

Load directives

The value of this key can take one of two forms:

Load directives: foobar, barfoo from definitions.js

Load directives: definitions.js

The javascript file should be a module which exports definitions of directives, conforming to the marked-directive rules. (Strictly speaking, jmarkdown uses an extended implementation of marked-directive which allows the definition to provide a custom tokeniser as well as a custom renderer. Those interested can take a look at the jmarkdown source code for more details.) These definitions will then be dynamically imported using import() and registered as a custom directive.

The first form is when you only want to use some of the directives defined in the file. The second form is intended for when you want to use whatever the default export is. The following silly example shows how this works. By using both named exports and a default export which is an array containing all the directives defined in the file, you get the ability to either load some of the directives (using the first form) or all the directives (using the second form).

The file definitions.js

export const foobar = {
	level: 'container',
	marker: ":::",
	label: "foobar",
	renderer(token) {
		if (token.meta.name === "foobar") {
			return `<strong>FOOBAR</strong>`;
		}
		return false;
	}
};

export const barfoo = {
	level: 'container',
	marker: ":::",
	label: "barfoo",
	renderer(token) {
		if (token.meta.name === "barfoo") {
			return `<strong>BARFOO</strong>`;
		}
		return false;
	}
};

export default [ foobar, barfoo ];

Load extensions

The value of this key can take the same two forms as the Load directives key. Here, though, instead of dynamically loading directives it dynamically loads extensions written in the format recognised by marked.js. So, for example, if the metadata header had the following:

Load extensions: jmckalex from my-extensions.js

And the file contained the following code:

The file my-extensions.js

export const jmckalex = {
	name: 'jmckalex',
	level: 'inline',
	start(src) { return src.match(/jmckalex/)?.index },
	tokenizer(src) {
		const match = src.match(/^jmckalex/);
		if (match) {
			console.log(match);
			const token = {
				type: 'jmckalex',
				raw: match[0],
				mermaid: true,
				text: match[0],
				tokens: []
			};
			return token;
		}
	},
	renderer(token) {
		return `J. McKenzie Alexander`;
	}
};

Then that inline extension, which does nothing more than automatically replace the token text jmckalex with J. McKenzie Alexander would be loaded into the markdown interpreter.

Optionals

This should be a list of names optionally followed by [true] or [false]. jmarkdown will create container directives which include/exclude the code contained. The default setting if nothing is specified is false, i.e., to exclude the code. The default setting can be overriden as follows:

:::optional-name{include=true}
This will be included no matter what the default
setting was.
:::

:::optional-name{include=false}
This will be excluded no matter what the default
setting was.
:::

Template

This should be a relative path to a HTML template file written using Mustache. For more details, see the section below discussing the default template and how to create custom templates for the output HTML.

That’s it for most of the special keys in the metadata header. There is one more type which requires explanations of greater length. More on that in a moment.

What can you do with other definable keys in the metadata header? jmarkdown defines a mustache-like syntax where the expression {{variable name}} gets replaced by whatever the corresponding value is from the metadata header, if it's defined. This provides a very simple form of variable interpolation. So, for example, if the header contained:

If the same key has been used multiple times, then {{key}} will return all of the values concatenated into a single string.

13.1. Defining new markdown syntax (simple)

In the metadata header, you can define new markdown syntax by simply specifying the starting delimiter, the ending delimiter, and the replacement text as HTML. (With an optional argument, you can also indicated whether the contents of the new delimiter should be parsed as markdown text.) Anything between the delimiters is then inserted into the defined replacement text every place that ${content} appears. Here are three examples. Suppose the metadata header includes the following:

Each new defined extension must begin with the keyword Extension followed by a space and then a following unique identifier, which could be a short sequence of words naming the extension. In the simple case, we specify the opening and closing delimiters. These can be any normal text characters, in sequence, provided that there are no spaces in the delimiters. Since jmarkdown supports unicode, you have a large set of symbols you can use which provide good syntactic clues as to what the extension does. The third argument is optional, but if it is true then the contents surrounded by the delimiter will be parsed as markdown input, otherwise it will be assumed to be false and the contents surrounded will not be processed as markdown input.

There is an optional fourth argument. If it is an integer, it specifies how many arguments are given to the extension. The arguments are comma delimited. If you need to specify an argument that contains a comma, you can give it as a "string", where quotes can be included using the normal escape syntax of \". You refer to the arguments in the replacement text via ${content1} or ${content2} or so on, where the integer refers to the number of the argument.

If more than one argument is specified, then the third argument can take a special form. Instead of just true or false, it can be an array of values indicating whether the i^th argument should be pushed through the markdown processor. If the i^th entry in the array is true, that argument will be processed as markdown text. If the i^th entry is false, that argument will be treated as verbatim text.

The first defined extension converts [:First *argument*, /second/ argument, __third__ argument:] into third argument First argument /second/ argument (The spaces between the <span> elements appears because the definition text contains a tab before each span.)

The third defined extension allows ⌜⌝ to serve as delimiters for verbatim text, allowing me to type arbitary markdown code. But I also enclose the code in a <span class="texbook"> element, and then target it with a little bit of JavaScript, allowing the verbatim code to be typeset like in Knuth’s TeXBook, where spaces are indicated with little square caps. The result? ⌜Text *like* /this/⌝ ends up transformed into Text *like* /this/ . The fourth extension defines ↑ ↑ to function as delimiters which convert the enclosed text to small caps, so ↑Small caps↑ becomes Small caps.

13.2. Defining new markdown syntax (complex)

Syntax extensions can also be defined via regular expressions. To do this, you need to specify two regular expressions: the first should be a quick and easy regular expression which indicates the start of the new syntax element, and the second is the full regular expression to match the entire construct. (Why two? Because that's how marked.js defines syntax extensions.) Here are three examples, taken from my own personal use which are discussed in more detail below:

The first extension matches any two digits surrounded by brackets. It then takes the numeric mark and wraps it in some HTML which causes it to float to the right, so that [59] becomes the construct you see to the right. Grade 59

Why do I have this defined? Because when I mark student essays, I write the feedback in markdown, and it is nice to be able to simply include the mark using that syntax and have it formatted in a more readable way. Moreover, by automatically adding a class to the second inner span, we can do automated data extraction during the post-processing phase, as we’ll see later.

The second extension matches the expression Candidate: followed by any amount of optional space, and then a sequence of digits. This then gets formatted as follows:

Again, why do this? If you look, you'll see that a class has been added to the strong element, which means we can target that element during the post-processing phase.

The third expression is more interesting. On old internet math groups, it used to be the case that people would write x1, x2, x3,... to refer to subscripted variables. The use of regular expression in defining this extensions means that you can use that syntax directly in your markdown documents.

In short, using regular expressions to define syntax extensions means that patterned data can be automatically recognised by jmarkdown and formatted into something more aesthetically pleasing. In addition, classes can be added to the HTML markup so that the generated document has suitable structure for being able to automate certain tasks. However, automating certain tasks requires using JavaScript, so let me now explain why jmarkdown as a j in its name!

14. Scripting capabilities

One additional feature of jmarkdown is the ability to define JavaScript functions which can be embedded in the markdown code and invoked on pieces of markdown to perform additional transformations. The JavaScript functions can either return raw HTML, to be inserted into the output, or markdown code, to be processed in either inline- or block- mode.

14.1. Inline scripts (text generation and manipulation)

Here's a simple example (we’ll see more complicated examples below). Suppose the markdown code contains the following:

The data-type='jmarkdown' tells jmarkdown that the script code should actually be processed rather than simply passed through quietly to the output HTML file. What jmarkdown does behind-the-scenes is to extract the code contained in the <script> tag and evaluate it in a Node virtual machine. The context of that virtual machine is shared across all jmarkdown script environments, so variables and functions defined in one script block are accessible in all the others. Normally, the script block containing the jmarkdown code is simply removed from the output. (We will later see how to put arbitrary HTML code in place of the script block.) The export_to_markdown() function takes, as its first argument, the name of the function to “export” to the jmarkdown interpreter.

What happens if you attempt to include markdown text in the argument to the function? Unless you specifically request that the text should be interpreted, it will simply be passed through as uninterpreted text. For example:

In order to request that the text be interpreted, you need to pass a second argument to export_to_jmarkdown(), telling it what to do. For example:

The default way of handling embedded JavaScript functions works as long as the function arguments aren’t too complicated. You could, for example, interpret the string passed to the function as containing multiple arguments, as follows:

Since everything between the opening and closing parentheses is interpreted as a single string, this means that you have the freedom to create your own syntax for passing data to a function. For example, here’s a function which creates a button with an attached function using something akin to javascript’s => notation:

However, if you need nested function calls, that won’t work because of the requirement that the argument text cannot contain a ). If you need more complicated arguments, you need to tell export_to_jmarkdown to not assume that the argument structure is simple. When you export a function in this way, you are promising jmarkdown that you will properly handled quoted strings, etc., so that the tokenizer can just scan the source text looking for balanced parentheses (...) where the start and end paretheses do not appear in strings. This allows us to handle situations like the following:

Complex functions should only return HTML to be inserted as replacement text, because attempted anything too complicated while requesting the output be parsed can confuse the markdown interpreter. If you really need to, though, you can use marked.parse() as follows:

The marked object accessible in jmarkdown scripts is a separate markdown processor configured exactly the same as the processor which is interpreting the jmarkdown file. However, because it is a separate processor that means that if you attempt to do anything with footnotes, headings, and the like, the results probably won’t be what you expect because those things will be processed by a separate markdown processor whose state isn’t connected to the one processing the file.

What if you want to replace the jmarkdown <script> tag with some HTML, in addition to evaluating all the JavaScript inside it? A global variable named output is defined which allows you to specify the html which should be inserted in place of the <script> element. The value of output is set to the empty string before each jmarkdown script element is processed. Here is an example which also shows how variables and function definitions declared in one script element are available to another:

Here’s a fun example showing what you can do with this. Here’s a function which, when given the name of an image file, embeds a base64 encoded version of the image into the HTML output from jmarkdown.

And what about the special command used at the start of this page, which generated a rainbow effect for text? That was defined by including the following code in the markdown file:

14.2. Post-processing scripts

In addition, jmarkdown supports the inclusion of JavaScript which should be invoked once the final document has been assembled. In this case, once jmarkdown has finished constructing the HTML for the entire document, it will parse the document using cheerio, which provides jQuery-like functionality for manipulating the DOM. (Note that cheerio provides a lightweight DOM implementation and only supports a subset of the jQuery syntax.) The cheerio object can be accessed via $, and access to the filesystem (using the fs module provided by Node) is via the variable fs.

The HTML generated by jmarkdown is already loaded into cheerio. If you want to inspect the raw HTML source, that is available in the global variable html. If you make changes to the DOM that you want to be reflected in the HTML file exported by jmarkdown, you will need set html to the new content. More than one jmarkdown-postprocess script tag can be included in the markdown file: jmarkdown will simply collect the contents of each of those script tags and will evaluate them in order.

For example, the following script will open a file named output.txt in the same directory as the markdown file being processed, then it will convert each of the <h1> headings to upper-case, writing each new heading to output.txt. Once that’s done, the HTML contents to be exported by jmarkdown are set to the new state of the DOM and the file output.txt is closed.

Because all of the markdown-magic has already been performed by the post-processing state, the above changes will not, of course, be reflected in the table of contents.

While post-processing scripts don’t do anything which couldn’t already be done by including normal <script> tags to be evaluated in a browser, there are several things which are nice about them:

14.3. A detailed example

I use jmarkdown for writing feedback on exam questions and storing the marks. The markdown file is structured as follows (ignoring the metadata header), with each student’s feedback and grade noted.

In the metadata header, I've written several extensions which use regular expressions to do pattern matching on the candidate number, file name, question indicators, and the mark on each question. For example, here are the extensions which format the candidate number, the question text, and the mark for each question:

I’ve defined the feedback container directive to add text and wrap the content in a <section class='feedback'> element.

With this amount of markup automatically generated, it then becomes trivial to define a post-processing script which does the following:

Those tasks would, admittedly, be a little easier to do if I either used another container which wrapped the candidate number, file information, and feedback container or if I simply put the feedback container around all of the student information. But that would make the text a little less “natural” in how it was read. The important thing to note, though, is how much can be done by taking advantage of naturally occuring textual patterns, using regular expressions to find them, then automatically add structuring information (classes, etc.) which can then be used to compile/extract information during the post-processing phase.

15. Output Templates

jmarkdown uses a default Mustache template for creating the output HTML. That default template is designed to play well with certain keys in the metadata header, as described above. However, you don't have to use the default template — you can create your own, and tell jmarkdown to use that, instead. The only requirement is that the mustache template must have {{{Content}}} appearing somewhere in it, as that is used to insert the constructed HTML into the output file.

View jmarkdown’s default template. In reading through the template, you can see how a number of the special headings from the metadata header are used during constructing the output HTML. However, the metadata header is not the only way that the output file can be configured! jmarkdown supports configuration files other than the metadata header, which allow you to specify global or project-specific configurations. Here, “global” means specified for a specific user and “project-specific” means for any markdown file located in a particular directory. That’s the next topic.

16. Configuration files

When jmarkdown is started, it checks to see if .jmarkdown/config.json exists in two locations:

If neither config.json file exists, the default settings of jmarkdown contain some hard-coded settings which provide enough information to ensure that jmarkdown will likely produce a working output file regardless. Like what? Like this:

from the command-line, it will show the default configuration options as a formatted JSON file. Here's the current version:

from the command line in a directory which does not yet have a .jmarkdown/ directory or a config.json file, jmarkdown with automatically create that directory and create a file called config-template.json inside it. Why config-template.json rather than config.json? Because the file it creates contains just the default options hardwired in the source code, and so if that file had the name config.json then, given the merge rules above, that would clobber any global configuration settings you have set.

17. File inclusion

Any markdown file specified between [[...]] will be inserted at that point in the document. Markdown will be inserted before processing. Basic support of recursive file inclusion is provided, but I haven't tested this very much.

Like this! ↩ ↩² ↩³

		Player 2
		Rock	Paper	Scissors
Player 1	Rock	\((0,0)\)	\((-1,1)\)	\((1,-1)\)
	Paper	\((1,-1)\)	\((0,0)\)	\((-1,1)\)
	Scissors	\((-1,1)\)	\((1,-1)\)	\((0,0)\)
		The game of Rock-Paper-Scissors

		Player A₁ $\alpha$
		Rock	Paper	Scissors
Player¹ 1	Rock	\((0,0)\)	\((-1,1)\)	\((1,-1)\)
	Paper	\((1,-1)\)	\((0,0)\)	\((-1,1)\)
	Scissors	\((-1,1)\)	\((1,-1)\)	\((0,0)\)
		The game of Rock-Paper-Scissors has a caption with math $\int_{-1}^{+1}f(x)\,dx$

This header spans two columns AND two rows		Header A
This header spans two columns AND two rows		Header B
Cell A	Cell B	Cell C