diff --git a/README.md b/README.md
index 53d1789..426f1a7 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,60 @@
 # Pico-Search
-Simple search feature for pages in your Pico CMS
+
+A plugin for the flat file CMS [Pico](https://github.com/picocms/Pico). Allows you to create a very basic search form
+that searches through titles and content of your pages. The search results page filters the `pages` array to only
+contain pages matching the search terms.
+
+You can optionally scope the search to only get results from within a certain folder. For example, on the page
+`yoursite.com/blog/search/foobar`, the `pages` array will only contain results from pages in the `blog` folder.
+
+Search results can be paginated using a plugin such as [Pico-Pagination](https://github.com/rewdy/Pico-Pagination).
+The search plugin should be executed before the pagination plugin (execution order is determined by file name).
+
+## Installation
+
+Copy the file `40-PicoSearch.php` to the `plugins` sub-folder of your Pico installation directory. Add a file named
+`search.md` to your content root or the sub-folder you want to make searchable. This is your search results page. You
+can leave it empty of content, but set the `Template` meta tag to a template that loops through the pages and displays
+them. Your `search.md` might look like this:
+
+```
+/*
+Title: Search results
+Template: search
+*/
+```
+
+Your template file (`search.html` in the above example) should contain something like the following section, which
+lists the pages matching the search (substitute `paged_pages` for `pages` if using Pico-Pagination):
+
+```
+{% for page in pages %}
+<div class="search_result">
+	<h2><a href="{{ page.url }}">{{ page.title }}</a></h2>
+	{% if page.description %}<p>{{ page.description }}</p>{% endif %}
+</div>
+{% endfor %}
+```
+
+Now, you should be able to visit for example `yoursite.com/search/foobar` (adjust path accordingly if putting search.md
+in a sub-folder) and see the search results for "foobar" listed.
+
+## The search form
+
+How to design your search form is up to you, but here's a very rudimentary example which you can put either in a
+template file or on a specific page.
+
+```
+<form id="search_form">
+    <label for="search_input">Search the site:</label>
+    <input type="search" id="search_input" />
+    <input type="submit" value="Search" />
+</form>
+<script type="text/javascript">
+    document.getElementById('search_form').addEventListener('submit', function (e) {
+        var search_terms = document.getElementById('search_input').value;
+        location.href = '/search/' + encodeURIComponent(search_terms);
+        e.preventDefault();
+    });
+</script>
+```
\ No newline at end of file