Update docs

README.md

@@ -172,34 +172,202 @@ Under the hood, the plugin converts the HTML string to `DomDocument` using `DomD
 
 Given a field named `text` and `$tree = $page->text()->toTree()`:
 
--   `$tree->select('xpath')` – return all elements matching the given xPath query.
--   `$tree->first()` – returns the first element of the selection.
--   `$tree->last()` – returns the last element of the selection.
--   `$tree->nth(5)` – returns the fiths element of the selection.
--   `$tree->limit(2)` – returns the first two elements of the selection.
--   `$tree->offset(1)` – return all elements but the first one of the selection.
--   `$tree->clear()` – clears the selection (select all again).
+### `$tree->select($xpath)`
+
+Selects all elements matching the given xPath query.
+
+-   **`$xpath`:** xPath query, see <https://en.wikipedia.org/wiki/XPath>
+
+```php
+// Select all paragraphs
+$tree->select('p');
+```
+
+### `$tree->first()`
+
+Selects the first element.
+
+### `$tree->last()`
+
+Selects the last element.
+
+### `$tree->nth($position)`
+
+Selects the nth element.
+
+-   **`$position`:** position of the element to
+
+### `$tree->limit($number)`
+
+Limits the current selection to the given number.
+
+-   **`$number`:** the limit.
+
+### `$tree->offset(1)`
+
+Offsets the current selection by the given number.
+
+-   **`$number`:** the offset.
+
+### `$tree->clear()`
+
+Clears the current selection and selects all nodes again (keeping all manipulations).
+
+### `$isEmpty()`
+
+Returns true is the current selection is empty.
+
+### `$isNotEmpty()`
+
+Returns true is the current selection is not empty.
+
+### `has($query)`
+
+Returns true is the current selection contains the given element.
+
+-   **`$query`:** an xPath query, can be as simple as the name of an element.
+
+### `count()`
+
+Counts the nodes in the current selection.
 
 ## Manipulations
 
 Given a field named `text` and `$tree = $page->text()->toTree()`:
 
--   `$tree->level(2)` – adjusts the headline hierachie to start at the given level.
--   `$tree->select('//strong')->setName('em')` – changes all `strong` elements to `em` elements.
--   `$tree->select('p')->setAttribute('class', 'example')` – adds an attributes to the selected elements.
--   `$tree->wrap('elementname', 'xpathfrom', 'xpathto', ['name' => 'value'])` – wraps all elements (from … to) in the given element, adding attributes if defined.
--   `$tree->wrapText('Kirby', 'strong', ['class' => 'is-great'])` – wraps all text occurences of 'Kirby' in a `strong` element with the class `is-great`.
+### `$tree->level($start)`
+
+Adjusts the headline hierarchy to start at the given level.
+
+-   **`$start`:** the level to start headlines with.
+
+```php
+// Make all `h1` a `h3`, all `h2` a `h4` …
+$tree->level(3);
+```
+
+### `$tree->select($xpath)->setName($name)`
+
+Selects all elements matching the given xPath query and updates the element names.
+
+-   **`$xpath`:** xPath query, see <https://en.wikipedia.org/wiki/XPath>
+-   **`$name`:** the new element name.
+
+```php
+// Rename all `strong` to `em`
+$tree->select('//strong')->setName('em');
+```
+
+### `$tree->select($xpath)->setAttribute($attribute, $value)`
+
+Selects all elements matching the given xPath query and sets the given attribute.
+
+-   **`$xpath`:** xPath query, see <https://en.wikipedia.org/wiki/XPath>
+-   **`$attribute`:** the attribute name.
+    . **`$value`:** the attribute value.
+
+```php
+// Set the class `example` to all paragraphs
+$tree->select('p')->setAttribute('class', 'example');
+```
+
+### `$tree->wrap($element, $from, $name, $attributes)`
+
+Wraps all elements (from … to) in the given element, adding attributes if defined.
+
+-   **`$element`:** name of the wrapping element.
+-   **`$from`:** xPath query for the start element, see <https://en.wikipedia>.
+-   **`$to`:** xPath query for the end element, see <https://en.wikipedia>.
+-   **`$attributes`:** array of attributes to be set on the wrapping element.
+
+```php
+$tree->wrap('div', 'h1', 'h2', ['class' => 'example']);
+```
+
+### `$tree->wrapText($string, $element, $attributes)`
+
+Wraps all text occurences of the string in the given element, adding attributes if defined.
+
+-   **`$string`:** string to search for.
+-   **`$element`:** name of the wrapping element.
+-   **`$attributes`:** array of attributes to be set on the wrapping element.
+
+```php
+$tree->wrapText('Kirby', 'strong', ['class' => 'is-great']);
+```
+
+### `snippets($path, $data)`
+
+Apply a snippet to each element in the current selection. Looks for a snippet with the name of the element first, uses a snippet named `default` second or leaves the element unchanged if none is found.
+
+-   **`$path`:** path inside the snippet folder to look for the element snippets.
+-   **`$data`:** additional data that should be passed to the snippet.
+
+By default, each snippet gets this data passed:
+
+-   **`$parent`:** the field parent, e. g. `$page` or `$site`.
+-   **`$field`:** the field.
+-   **`$node`:** the DOM node.
+-   **`$content`:** the inner HTML of the element.
+-   **`$attrs`:** the existing attributes of the element.
+-   **`$next`:** the next element.
+-   **`$prev`:** the previous element.
+-   **`$position`:** the position of the current element.
+-   **`$positionOfType`:** the position of the current element compared to elements of the same type.
+
+See example in the introduction.
+
+### `widont()`
+
+Improved version of the Kirby method, taking the DOM into account.
+
+### `excerpt()`
+
+Alias for the Kirby method.
+
+### `kirbytextinline()`
+
+Improved version of the Kirby method, taking the DOM into account.
+
+### `smartypants()`
+
+Improved version of the Kirby method, taking the DOM into account.
 
 ## Output
 
 Given a field named `text` and `$tree = $page->text()->toTree()`:
 
--   `$tree->html()` – returns the HTML of the current selection.
--   `$tree->content()` – returns the content of the current selection (text and child nodes).
--   `$tree->text()` – returns the text value of the current selection.
--   `$tree->toDocument()` – returns the `DomDocument` object.
--   `$tree->toSelection()` – returns the `DomNodeList` of the current selection.
--   `$tree->toField('html|content|text')` – returns the field instance with the field value set to the current html (default), content or text value.
+### `$tree->html($clear)`
+
+Returns the HTML of the current selection.
+
+-   **`$clear`:** boolean flag whether to clear the current selection, defaults to `false`.
+
+### `$tree->content($clear)`
+
+Returns the content of the current selection (text and child nodes).
+
+-   **`$clear`:** boolean flag whether to clear the current selection, defaults to `false`.
+
+### `$tree->text($clear)`
+
+Returns the text value of the current selection.
+
+-   **`$clear`:** boolean flag whether to clear the current selection, defaults to `false`.
+
+### `$tree->toDocument()`
+
+Returns the `DomDocument` object.
+
+### `$tree->toSelection()`
+
+Returns the `DomNodeList` of the current selection.
+
+### `$tree->toField($type)`
+
+Returns the field instance with the field value set to the current html (default), content or text value.
+
+-   **`$type`:** the returned content type, either `html`, `content` or `text`.
 
 # License