Home

Awesome

lcmark

lcmark is a high-level CommonMark converter built upon cmark. It comes as both a command-line program and a Lua module. It supports:

Also see the documentation.

Installation

To install: luarocks install lcmark

(This installs both the library and the program).

Additionally, you'll also need a YAML parsing library. lcmark will automatically attempt to load and use one of yaml, lua-yaml or lyaml, so make sure you have one of those installed. Alternatively, a custom parser can be used (see the yaml_parser option below).

Features

YAML Metadata

The YAML metadata section (if present) must occur at the beginning of the document. It begins with a line containing --- and ends with a line containing ... or ---. Between these, a YAML key/value map is expected.

String values found in the metadata will be parsed and rendered as CommonMark. If a string value contains only a single paragraph, it will be rendered as an inline string.

If the yaml_parser option (a function) is provided, lcmark will use it to parse YAML. The function should take a string as input and should return a table. In case of failure, it should either throw an error or return a nil, err tuple; other returns will be discarded silently.

Example:

---
# This is a comment!
# Note that the quotes below are needed because of the
# colon in the title:
title: 'This is my *article*: subtitle here'
author:
- name: Sam Smith
  institute: U of X
- name:  Sasha Xi
  institute: NXQ
abstract: |
  Here is a multiline abstract.

  - It can even
  - contain
  - lists and other block elements
...

Document body starts here...

Filters

Filters modify the parsed document prior to rendering.

A filter is a function that takes three arguments (doc, meta, to), where doc is a cmark node, meta is the YAML metadata as a (potentially nested) Lua table with all strings replaced with cmark nodes, and to is a string specifying the output format (the same string as passed to lcmark.convert). The filter may destructively modify doc and meta.

Some sample filters are provided in filters/.

Templates

Templates are used to build standalone documents from the parsed document body and metadata.

lcmark supports a small subset of the templating language used by pandoc, and lcmark templates can be used with pandoc (with the caveat that pandoc sets many variables automatically that lcmark does not).

nil, false and {} (an empty table) are considered to be "falsy" values. Any other value is considered "truthy".

A quick guide:

Additionally, if newlines occurs directly after both $for()$ and $endfor$ (or $if()$ and $endif$), they will be ignored. This is to prevent spurious blank lines in the rendered document if the template contains many directives that span multiple lines and evaluate to false.

Some sample templates are provided in templates/.

Documentation

Program

lcmark --help will print a short list of options.

For a more detailed description, see the lcmark(1) man page.

Module

Basic usage:

local lcmark = require("lcmark")
local body, metadata = lcmark.convert("Hello *world*",
                         "latex", {smart = true, columns = 40})

The module exports the following fields:

Development

make builds the rock and installs it locally.

make test runs some tests. These are in test.t and tests/. You'll need the prove executable, as well as luacheck and lua-TestMore.

make update will update the spec tests from the ../cmark directory.

make -C standalone will create a fully self-contained version of lcmark which embeds the lua interpreter and all required libraries, resulting in no external dependencies.