#CMOS - CommonMark Output Schnutification

CMOS is a thin layer over the CommonMark (libcmark) markdown renderer. It adds three features, all opt-in:

• Simple syntax highlighting based on GNU source-highlight
• Adding id attributes to headings for linking to them
• Adding anchors to the headings linking to themselves

#Usage

Usage: cmos [OPTION]... [FILE]...
Render markdown FILE(s) to HTML

With no FILE, read markdown from standard input.

Options:
  -a, --anchors ANCHOR  Add anchors to headings (implies -i)
  -i, --heading-ids     Add id attribute to headings
  -t, --title           Output first first-level heading only
  -H, --highlight       Perform syntax highlighting of code blocks
  -s, --style FILE      Specify GNU source-highlight style file
  -v, --version         Print version
  -h, --help            Print usage information

#Features

#Syntax highlighting

If enabled, CMOS will use GNU source-highlight for syntax highlighting. This only applies to fenced code blocks that specify a language. Available languages can be found in the manual (anything on the left side of = is a valid language identifier).

A custom style file can supplied to GNU source-highlight. Refer to the manual for details. The CMOS source code contains one example style file.

#Add id attribute to headings

If enabled, CMOS will add an id attribute to every heading (<hX>). The value will be the text of the heading. The only processing performed is the replacement of & and " with & and " respectively. The replacement handles UTF-8. The result should be that you can in most cases copy the actual heading and append it to the URL (plus a # of course) and it will just work. This depends on your browser doing basic input processing, but again, mostly just works.

NOTE: CMOS does not yet enforce uniqueness of the id attribute, this will be added soon.

#Add anchors to headings

This a common technique to allow users to easily get the link to a specific section. The anchors are usually styled with CSS to only appear when hovering over the heading. If you are viewing the HTML rendering of this document on sr.ht you can see a similar mechanism in action by hovering the mouse over any section heading.

The anchor text to be used is passed as an argument to the flag. This feature is based on the id attribute feature and will implicitly enable it.

#Building

meson ./build
ninja -C ./build

#Packages

• Arch Linux: AUR

#Contact

Until something more appropriate is in place, feel free to send comments, questions, or patches to my public inbox.