Welcome to the lab.

The latest version of mdless, my most recent coding obsession, now includes MultiMarkdown document transclusion.

File transclusion is the ability to tell MultiMarkdown to insert the contents of another file inside the current file being processed.

You can include a document by inserting a relative path between two pairs of curly brackets:

{{myfile.md}}

The path is relative to the current document, which won’t work if you’re piping text to mdless. In that case it would need to be an absolute path, or have transclude base specified in the metadata.

To provide a base for transclusion paths, just add transclude base to your document’s metadata, either as MultiMarkdown metadata, or as a YAML header:

transclude base: ~/Documents/myproject/chapters

It’s probably not a super useful feature to 90% of mdless users, but should be handy for some.

I just pushed v2.1.6 of mdless. Once all these 2.0 changes are confirmed to be stable, I’ll let this project go for a while, but right now there’s lots to improve on and I’m enjoying it as a way to blow off steam.

The biggest change in 2.1.6 is the ability to use hex codes when theming. If you didn’t know, the first time mdless is run, it saves a theme file to ~/.config/mdless/mdless.theme. You can edit this file to change what colors different elements display as. You can also create additional NAME.theme files and trigger them with --theme NAME, or set the :theme: setting in your ~/.config/mdless/config.yml.

With the latest version, you can use 3 or 6-digit RGB codes in addition to color names. Where previously you were limited to the default ANSI colors like red, blue, magenta, cyan, etc., you can now insert something like eccc87 where a color name would usually go. You can affect background colors by prefixing with bg or on_, e.g. bgeccc87. The depth of color that can be displayed depends on your terminal, but at minimum this opens up 256 colors for theming, a 32x increase in options.

I also fixed a couple of issues where span elements in list items would cause the coloration to change. And when there’s a space between list items, they get rendered as paragraphs within list items (standard for most Markdown parsers), causing the coloring to be unexpectedly the same as regular paragraphs. Now mdless strips out regular paragraph coloring on paragraphs contained in list items, so every paragraph within a list gets the list item coloring.

In TaskPaper rendering, documents will now respond to --list to list projects, and --section to list just certain project(s) contents. These no longer have to be numeric (for Markdown or TaskPaper); fuzzy text matching can pick a section (or multiple sections) for you. I also improved the TaskPaper auto-detection by adding a routine that removes all lines that match project or task regular expressions, and if there’s nothing left, it assumes it’s a TaskPaper document. Let me know how this works in the real world.

Lastly, I added a --changes flag that will display the changelog (using mdless for readability), so when you update you can see what changed just by running mdless --changes.

Check out the project page for the full changelog and more details!

I’ve updated mdless to 2.0. Well, 2.0.5 at this point. It’s a complete overhaul of the command line Markdown parser/viewer.

It’s been a pretty popular project, and is being used on all kinds of OSs, but it got frustrating as the whole thing was based on regular expressions for parsing and users expected it to handle some more complex markup than it could. So for the reboot, I switched to using RedCarpet for parsing, then added my own terminal handling to that via a custom renderer and pre/post processing.

Table cleanup is better than ever. Footnotes can still be displayed directly after the paragraph that references them, or at the end of the display. Code highlighting (with Pygments) is more accurate than ever. Ordered lists are properly numbered, regardless of the numbering in the Markdown. There are a few differences in the way things like code blocks nested in lists are displayed (they’re no longer indented), but overall it’s a big step up.

If you’re into Markdown and spend time in the Terminal, let mdless display those README files for you, rather than opening up a dedicated viewer or editor with a preview. See the project page for more details and installation instructions.

Update: Just pushed a new version that allows for links to be output in reference format (--links ref) or as per-paragraph references (--links para). Inline links is the default (--links inline). This setting can be made permanent by editing ~/.config/mdless/config.yml.