diff --git a/Gemfile.lock b/Gemfile.lock
index e273be7..67ecf51 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -4,6 +4,7 @@ PATH
     obsidian-parser (0.7.0)
       marcel (~> 0.3.1)
       markly (~> 0.7.0)
+      tilt (~> 2.0, >= 2.0.8)
 
 GEM
   remote: https://rubygems.org/
@@ -77,6 +78,7 @@ GEM
     standard-performance (1.1.1)
       lint_roller (~> 1.1)
       rubocop-performance (~> 1.18.0)
+    tilt (2.3.0)
     unicode-display_width (2.4.2)
 
 PLATFORMS
diff --git a/README.md b/README.md
index 67e61e0..be3bc25 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Obsidian::Parser
 
-A (work in progress) gem to parse notes created with the Obsidian note-taking tool.
+A gem to parse notes created with the Obsidian note-taking tool.
 
 ## Installation
 
@@ -13,24 +13,38 @@ If bundler is not being used to manage dependencies, install the gem by executin
     $ gem install obsidian-parser
 
 ## Usage
-WARNING: This API is not yet finalized.
+
+Parse the vault with:
 
 ```ruby
+require 'obsidian/parser'
 parser = Obsidian::Parser.new(Pathname.new("/path/to/vault"))
+```
+
+The return object allows you to iterate over all pages in the vault.
+
+A page is any note or directory within the vault.
+
+If a directory contains an `index.md`, that will be used as the directory content. Otherwise, the directory will have no content.
 
-puts parser.index.notes
-# -> [ Note(title: "README", slug: "README") ]
+```ruby
+puts parser.pages
+# -> [ Page(title: "", slug: ""), Page(title: "Foo", slug: "Foo"), Page(title: "Bar", slug: "Foo/Bar") ]
+```
+
+You can fetch pages by their slug (the relative path, without a leading slash):
 
-puts parser.index.directories
-# -> [ Index(title: "Drafts", slug: "Drafts"),
-#      Index(title: "Projects", slug: "Projects") ]
+```ruby
+page = parser.index.find_in_tree("foo/bar")
 ```
 
-### Generating HTML
+Page objects have titles, slugs, and a callable to fetch their content:
+
 ```ruby
-title = note.title
-content = note.content
-content.generate_html
+page = parser.pages[-1]
+title = page.title
+markdown = page.content.call
+html = page.generate_html
 ```
 
 ## Development
diff --git a/lib/obsidian/parser/page.rb b/lib/obsidian/parser/page.rb
index 9606440..4cd428f 100644
--- a/lib/obsidian/parser/page.rb
+++ b/lib/obsidian/parser/page.rb
@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# TODO: remove this dependency
+require "tilt/erb"
+
 module Obsidian
   # A page in the vault corresponding to either a markdown document,
   # or a directory containing other documents.
diff --git a/obsidian-parser.gemspec b/obsidian-parser.gemspec
index 5c3687d..73fc549 100644
--- a/obsidian-parser.gemspec
+++ b/obsidian-parser.gemspec
@@ -32,6 +32,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "markly", "~> 0.7.0"
   spec.add_dependency "marcel", "~> 0.3.1"
+  spec.add_dependency "tilt", "~> 2.0", ">= 2.0.8"
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html