Markdown into Micron

RNGit has a utility for converting markdown into micron and it works really well. Better still, I don’t have to maintain anything for it to work, I can just make use of the latest RNS library and I get it for free.

Here’s my Python to call it:

#!/usr/bin/env python

import argparse
import os

from RNS.Utilities.rngit.util import convert_markdown_to_micron


def parse_args():
    parser = argparse.ArgumentParser(description="Convert markdown to micron.")
    parser.add_argument("input_file", type=str, help="Path to the input markdown file")
    parser.add_argument("output_file", type=str, help="Path to the output micron file")
    parser.add_argument(
        "--overwrite", action="store_true", help="Overwrite existing output file"
    )
    return parser.parse_args()


if __name__ == "__main__":
    args = parse_args()

    if not os.path.isfile(args.input_file):
        raise FileNotFoundError(f"Input file '{args.input_file}' does not exist.")

    if os.path.isfile(args.output_file) and not args.overwrite:
        raise FileExistsError(
            f"Output file '{args.output_file}' already exists. Use --overwrite to overwrite it."
        )

    with open(args.input_file) as input_file:
        print(args.output_file)
        with open(args.output_file, "w") as output_file:
            output_file.write(convert_markdown_to_micron(input_file.read()))

For dependencies: rns, ucwidth, pygments (last one is optional for syntax highlighting – don’t leave off ucwidth, despite that it’s technically optional).

Remaining idiosyncrasies

YAML headers

It seems oblivious to YAML headers. They just get dumped in wholesale, but the --- goes to the micron - before and after. I forget, is that pre-formatted text?

Because I’m piping my markdown through pandoc as a preprocessing step, the YAML header has already been stripped bbefore the content is processed with the markdown to mircon script. I apply a template to add the title from the YAML header to the page and I shift indent levels. So no big deal here for my stuff.

reference links

It doesn’t support reference links, but pandoc can help here – any invocation of pandoc with a markdown output type will strip reference links unless the options is explicitly passed to allow them.

Pandoc hangups

Pandoc will escape the # if it’s used in a link title. This can be fixed with a sed expression. If the sed expression is put in a Makefile, it gets a little tricker with the escaping, for example:

To accomplish this:

pandoc input -t markdown | sed -e 's,\[\\\#,[\#,g' > output

Would require something like the following:

UNESCAPE_HASHES=sed -e 's,\[\\\\\#,[\#,g'

target:
    pandoc input -t markdown | $(UNESCAPE_HASHES) > output

link extensions

Link targets are not touched by the conversion process, so any links that need to point at a micron page need to have the extension swapped. This is pretty much how all tools work, so I already had logic for swapping extensions that could be adapted.

Sed can help here.

In the Makefile example:

FMT_MU=sed 's,\(.*\)\.md\>,\1.mu,g'
target:
    pandoc input -t markdown | $(FMT_MU) > output

Tags: index, reticulum

Markdown into Micron

Remaining idiosyncrasies

YAML headers

reference links

Pandoc hangups

link extensions

Tags

Navigation

Backlinks