marksonnet

This project is an experimental tool (and library) implementing an extension of CommonMark. It adds a special codeblock "language" for evaluating Jsonnet programs which can be used to inject output in the rendered document. It can be used to include other markdown files as snippets, embed configuration sources alongside relevant documentation, display Jsonnet-generated Kubernetes manifests or Tanka environments, or even generate templated markdown documentation from JSON or YAML sources.

[!CAUTION] marksonnet is a personal project for the purpose of learning Rust. While I think it has the potential to be a useful tool, it is not a seriously-maintained one.

Installation

The command line tool marksonnet can be installed from crates.io using cargo install.

cargo install marksonnet

To add the marksonnet library to your project, use cargo add.

cargo add marksonnet

Then, use the crate in your project like so.

use marksonnet;

for event in marksonnet::Parser::new(&text) {
    println!("{:?}", event)
}

Operation

marksonnet is both a Rust library crate and a binary crate. This means that it can be used as a command line tool, or from other Rust projects.

The library provides an interface similar to pulldown-cmark, as it is a thin wrapper over that. The command line tool reads a file or stdin, evaluates marksonnet blocks, and writes to a file or stdout.

In either case, marksonnet parses the input using pulldown-cmark, replacing marksonnet-labeled codeblocks with its Jsonnet evaluation result, and re-serializing the input to CommonMark using pulldown-cmark-to-cmark. Jsonnet is evaluated using jrsonnet, and the type of the result determines the nature of the output. If the result is a string, the codeblock is substituted with it, and it is parsed again as though it were part of the original document. If the result is anything else, it is serialized as indented JSON, embedded in a json-labeled codeblock, and substituted.

Examples

This File

This README is authored using marksonnet in README.src.md, and rendered as README.md. This is accomplished using the command line tool, invoked like so:

#!/bin/bash

marksonnet -o README.md README.src.md

Computing Values

This marksonnet codeblock displays the first five Fibonacci numbers as a JSON array.

    ```marksonnet
    local fib(n) = if (n <= 2) then 1 else (fib(n-1) + fib(n-2));
    [fib(n) for n in std.range(1, 5)]
    ```

is transformed into:

[
    1,
    1,
    2,
    3,
    5
]

Assembling Strings

This marksonnet codeblock is evaluated and its result is injected as CommonMark.

    ```marksonnet
    std.format('> %s, %s!', ['Hello', 'World'])
    ```

Hello, World!

Note: CommonMark in the result string is parsed as normal.

Imports

Imports are supported as in normal Jsonnet.

    ```marksonnet
    import 'example/sample.json'
    ```

{
    "bar": "baz",
    "foo": "bar"
}

Imports can also be used to include strings, such as other markdown files.

    ```marksonnet
    importstr 'example/sample.md'
    ```

Sample!

This file is a sample.

[!WARNING] Nested imports are not yet supported.