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.

Query the underlying C library version with Apex::Native.version.

Requirements

Before installing the gem, you must have the cmark-gfm C library available on your system. The gem compiles a native extension that links against it.

• macOS (Homebrew):

  brew install cmark-gfm

• Other platforms: Install the cmark-gfm package for your distribution and ensure development headers and pkg-config are available. See cmark-gfm for build instructions.

If you run gem install apex-ruby without cmark-gfm installed, the build will fail with a clear error message and the same installation instructions.

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.