Getting Started with Nokogiri

What Is Nokogiri?

Nokogiri is a Ruby document parser that was released in October 2008. It’s great for reading, searching, editing, and otherwise mucking around with HTML (and XML).

Nokogiri Basics

After installing Nokogiri, run the following Ruby program:

require 'rubygems'
require 'nokogiri'
html = %Q{
<!DOCTYPE html>
<html lang="en">
    <title>A Riddle</title>
    <p id="question">
      How many web servers does it take to screw in a light bulb?
    <p id="answer">
      200, OK?
doc = Nokogiri::HTML(html)
body = doc.at_css("body")
body['style'] = "background-color: blue;"
html = doc.to_html
puts html

First we translate the HTML string into a Nokogiri document. Then we find the body element, change its style, and translate the Nokogiri document back into an HTML string. Easy as pi!

Locating Elements

Nokogiri makes locating HTML elements easy. Although you can use XPath to search through the HTML, Nokogiri lets you locate elements using CSS3 selectors.

This finds all paragraphs:


This finds the paragraph with id "answer":


Notice that doc.css is used to return multiple elements (also referred to as nodes) and doc.at_css is used to return a single element (node). Multiple nodes are returned as a Nokogiri::XML::NodeSet object, which is an array-like collection of Nokogiri::XML::Node objects.

Changing Elements

doc = Nokogiri::HTML(html)
question = doc.at_css("p#question")
question.content = "What is 50*PI rounded to the nearest hundred?"
html = doc.to_html

We use the content method to change the text. We can also add attributes to the node like this:

question['class'] = "math"

Adding Elements

First we need to create a new node:

new_paragraph ="p", doc)
new_paragraph.content = "Thanks!"

Then we add it to the body node:

body = doc.at_css("body")
body << new_paragraph

This makes it the last paragraph. We can make it the first paragraph like this:


Deleting Elements

This is how you delete a node:

answer_paragraph = doc.at_css("p#answer")

Diving Deeper into Nokogiri

As you can see, it’s really easy to get started with Nokogiri. Here are some resources for going deeper:

As you’re working with Nokogiri, you may notice that it can very quickly turn from easy to frustrating since document parsing is an inherently complex problem. Be sure to read the sequel to this blog post, Getting Mugged by Nokogiri, to learn how to avoid some Nokogiri pitfalls.

You can skip to the end and leave a response. Pinging is currently not allowed.

2 Responses to “Getting Started with Nokogiri”

  1. Thanks for the overview of Nokogiri, and also for the precise links to documentation. I’d read that the nokogiri website was helpful, but I found it quite the opposite until I followed your pointer to the Nokogiri::XML::Node page []. Nicholas’s Blog was also helpful. Thanks again.

    P.S. Nice puns in your Nokogiri posts.

  2. Wow, just wow. I was trying to add elements to a very simple HTML document, and finally with your blog I did it!! Wahoo.. Wow, searching and returning nodes has a TON of tutorials, but for some reason I found it very difficult to find decent docs on ADDING elements.. finally did it! And you might want to include this as well.. If you want to add an id or class to the element you insert, it looks like this: new_paragraph[‘id’] = “my_id” as the dot notation doesn’t work with id, class and probably the other elements.. thank you!

Leave a Reply