Apex Ruby Bindings

Ruby bindings for the Apex unified Markdown processor.

Apex is a C library that supports CommonMark, GFM, MultiMarkdown, Kramdown, and a number of Marked-specific extensions. This gem vendors the Apex sources (currently the 1.1.x library) and exposes a small, kramdown-style Ruby API for converting Markdown to HTML.

The gem has its own version number, separate from the Apex library it bundles. Each gem release ships the latest Apex release, and Apex::Native.version reports which one you have:

require "apex"

Apex::VERSION         # => "1.0.34" (the gem)
Apex::Native.version  # => "1.1.36" (the bundled Apex library)

Requirements

The gem compiles a native extension, so you need a C compiler (Xcode Command Line Tools on macOS, build-essential or equivalent on Linux). Apex's patched copy of cmark-gfm is bundled and compiled into the extension; a system cmark-gfm is not needed and is not used.

libyaml is optional. If it is installed (e.g. brew install libyaml), Apex uses it for nested YAML front matter; otherwise it falls back to its simple key: value parser.

Installation

Add this line to your application's Gemfile:

gem "apex-ruby"

And then execute:

bundle install

Or install it yourself as:

gem install apex-ruby

Usage

The main API mirrors the simplicity of the kramdown gem:

require "apex"

html = Apex::Document.markdown_to_html(text)

Modes

You can select a compatibility mode via the mode: keyword argument:

html = Apex::Document.markdown_to_html(text, mode: :unified)      # default
html = Apex::Document.markdown_to_html(text, mode: :gfm)          # or :github
html = Apex::Document.markdown_to_html(text, mode: :multimarkdown) # or :mmd
html = Apex::Document.markdown_to_html(text, mode: :commonmark)   # or :cmark
html = Apex::Document.markdown_to_html(text, mode: :kramdown)
html = Apex::Document.markdown_to_html(text, mode: :quarto)

Mode selection uses apex_options_for_mode, so unified/MMD/kramdown defaults match the CLI (including YAML front-matter extraction). Document front matter is applied to options; explicit keyword arguments override front matter.

Metadata / YAML front matter

In :unified, :multimarkdown, and :kramdown, YAML/MMD/Pandoc metadata at the top of the document is extracted and removed from the Markdown before rendering (so it does not appear as an <hr> plus leftover text). In :gfm and :commonmark, front matter is left in the document and typically renders as a horizontal rule.

There is no separate enable_metadata flag. strip_metadata is accepted for compatibility but is unused by the C library; stripping is controlled by mode as above.

Options

Any additional keyword arguments are mapped to the underlying apex_options struct defined in apex.h. For example:

html = Apex::Document.markdown_to_html(
  text,
  mode: :unified,
  enable_tables: true,
  enable_footnotes: true,
  generate_header_ids: true,
  relaxed_tables: true,
  enable_indices: true,
  concordance: "terms.tsv",          # or concordance_files: ["a.tsv", "b.tsv"]
  bibliography: "refs.bib",          # or bibliography_files: [...]
  wikilink_extension: "html"
)

See the Apex documentation for the complete list of options and their semantics.

Instance API

If you prefer an object-oriented style (similar to Kramdown::Document), you can use Apex::Document instances:

doc = Apex::Document.new(text, mode: :gfm, enable_tables: true)
html = doc.to_html

Jekyll

You can use Apex as Jekyll’s Markdown converter instead of Kramdown via a custom converter plugin. See Jekyll-Apex.md for step-by-step instructions. That integration is currently untested and documented as a placeholder; feedback from anyone willing to try it is welcome at ApexMarkdown/apex-ruby/issues.

Development

To run the test suite:

bundle exec rake test

To build and install the gem into all Ruby versions managed by mise:

bundle exec rake install

This will:

1. Build pkg/apex-ruby-<version>.gem
2. Run gem install for each Ruby reported by mise ls ruby.

License

This project is licensed under the MIT license. See the Apex repository for the license of the underlying C implementation.