diff --git a/README.md b/README.md
index 9324fdf..04eda06 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,6 @@
 # jekyll-theme-bluelib
 
-Welcome to your new Jekyll theme! In this directory, you'll find the files you need to be able to package up your theme into a gem. Put your layouts in `_layouts`, your includes in `_includes`, your sass files in `_sass` and any other assets in `assets`.
-
-To experiment with this code, add some sample content and run `bundle exec jekyll serve` – this directory is setup just like a Jekyll site!
-
-TODO: Delete this and the text above, and describe your gem
-
+A theme providing Bluelib themes on Jekyll static sites!
 
 ## Installation
 
@@ -23,19 +18,50 @@ theme: jekyll-theme-bluelib
 
 And then execute:
 
-    $ bundle
+```console
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install jekyll-theme-bluelib
+```console 
+$ gem install jekyll-theme-bluelib
+```
+
+After installing, add to `_config.yml` the name of your preferred bluelib theme:
+```yml 
+bluelib: "royalblue"
+```
 
 ## Usage
 
-TODO: Write usage instructions here. Describe your available layouts, includes, sass and/or assets.
+The theme provides four layouts: `default`, `base`, `box` and `post`.
 
-## Contributing
+### `default`
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/hello. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Default is the simplest layout of the four, and only adds the bluelib stylesheets for the theme to be displayed.
+
+In particular, it `<link>`s in the following order:
+
+1. The `skeleton.root.css` from the latest version of bluelib
+2. The bluelib `root` target defined in the `bluelib` variable of `_config.yml` (`site.bluelib`)
+3. The bluelib `root` target defined in the `bluelib` variable of the Front Matter of the page (`page.bluelib`)
+
+### `base`
+
+Base adds some elements to the `default` layout: 
+
+- it adds a `layout-threecol` to the page
+- it centers the page `contents` by using `layout-threecol-center` 
+- it renders the `title` defined in `_config.yml` as a `<h1>` element before the contents
+
+### `box`
+
+Box wraps the `contents` of the page in a `panel panel-box`.
+
+### `post`
+
+Post extends the `box` layout by adding the `page.title` to the top of the box, rendered as a `<h2>` element.
 
 ## Development
 
@@ -45,8 +71,3 @@ Your theme is setup just like a normal Jekyll site! To test your theme, run `bun
 
 When your theme is released, only the files in `_layouts`, `_includes`, `_sass` and `assets` tracked with Git will be bundled.
 To add a custom directory to your theme-gem, please edit the regexp in `jekyll-theme-bluelib.gemspec` accordingly.
-
-## License
-
-The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-