A Ruby gem to parse HTML containing one or more microformats and microformats2 and return a collection of dynamically defined Ruby objects, a Ruby hash or a JSON hash.
Ruby HTML JavaScript
Clone or download
jgarber623 and dissolve Fix logo image sizing (#88)
…turns out GitHub's Markdown parser does some weird stuff to images.
Latest commit d2dbcac Jul 5, 2018



A Ruby gem for parsing HTML documents containing microformats.

Gem Downloads Build Maintainability Coverage

Key Features

Getting Started

Before installing and using microformats-ruby, you'll want to have Ruby 2.2.9 (or newer) installed. It's recommended that you use a Ruby version managment tool like rbenv, chruby, or rvm.

microformats-ruby is developed using Ruby 2.4.4 and is additionally tested against version 2.5.1 using Travis CI.


If you're using Bundler to manage gem dependencies, add microformats-ruby to your project's Gemfile:

source 'https://rubygems.org'

gem 'microformats', '~> 4.0', '>= 4.0.7'

…and then run:

bundle install

You may also install microformats-ruby directly using:

gem install microformats


An example working with a basic h-card:

source = '<div class="h-card"><p class="p-name">Jessica Lynn Suttles</p></div>'
collection = Microformats.parse(source)

# Get a copy of the canonical microformats hash structure

# The above as JSON in a string

# Return a string if there is only one item found
collection.card.name #=> "Jessica Lynn Suttles"

Below is a more complex markup structure using an h-entry with a nested h-card:

source = '<article class="h-entry">
  <h1 class="p-name">Microformats 2</h1>
  <div class="h-card p-author">
    <p class="p-name"><span class="p-first-name">Jessica</span> Lynn Suttles</p>

collection = Microformats.parse(source)

collection.entry.name.to_s #=> "Microformats 2"

# Accessing nested microformats
collection.entry.author.name.to_s #=> "Jessica Lynn Suttles"

# Accessing nested microformats can use shortcuts or expanded method
collection.entry.author.name #=> "Jessica Lynn Suttles"
collection.entry.properties.author.properties.name.to_s #=> "Jessica Lynn Suttles"

# Use `_` instead of `-` to return property values
collection.entry.author.first_name #=> "Jessica"
collection.rel_urls #=> {}

Using the same markup patterns as above, here's an h-entry with multiple authors, each marked up as h-cards:

source = '<article class="h-entry">
  <h1 class="p-name">Microformats 2</h1>
  <div class="h-card p-author">
    <p class="p-name"><span class="p-first-name">Jessica</span> Lynn Suttles</p>
  <div class="h-card p-author">
    <p class="p-name"><span class="p-first-name">Brandon</span> Edens</p>

collection = Microformats.parse(source)

# Arrays of items will always return the first item by default
collection.entry.author.name #=> "Jessica Lynn Suttles"
collection.entry.author(1).name #=> "Brandon Edens"

# Get the actual array of items by using `:all`
collection.entry.author(:all).count #=> 2
collection.entry.author(:all)[1].name #=> "Brandon Edens"

Command Line Interface

microformats-ruby also includes a command like program that will parse HTML and return a JSON representation of the included microformats.

microformats http://tantek.com

The program accepts URLs, file paths, or strings of HTML as an argument. Additionally, the script accepts piped input from other programs:

curl http://tantek.com | microformats

Implementation Status

Status Specification or Parsing Rule
Parse a document for microformats
Parsing a p- property
Parsing a u- property
Parsing a dt- property
Parsing an e- property
Parsing for implied properties
Nested properties
Nested microformat with associated property
Nested microformat without associated property
Recognize dynamically created properties
Support for rel attribute values
Normalizing u-* property values
Parse the value class pattern
Recognize vendor extensions
Support for classic microformats
Recognize the include pattern

Improving microformats-ruby

Have questions about using microformats-ruby? Found a bug? Have ideas for new or improved features? Want to pitch in and write some code?

Check out CONTRIBUTING.md for more on how you can help!


The microformats-ruby logo is derived from the microformats logo mark by Rémi Prévost.

microformats-ruby is written and maintained by:


microformats-ruby is dedicated to the public domain using the Creative Commons CC0 1.0 Universal license.

The authors waive all of their rights to the work worldwide under copyright law, including all related and neighboring rights, to the extent allowed by law. You can copy, modify, and distribute the work, even for commercial purposes, all without asking permission.

See LICENSE for more details.