Explain how to use the tags in the documentation

docs/getting-started.md

@@ -36,7 +36,7 @@ From `zk`'s interactive edit screen, press `Ctrl-N` to create a new note using t
 After some time, hopefully you will have enough notes to be lost in it. Use `zk`'s powerful [filtering capabilities](note-filtering.md) to find the notes you need.
 
 ```sh
-$ zk list -m "recipe pizza -pineapple"
+$ zk list --tag "recipe" --match "pizza -pineapple"
 ```
 <div align="center"><img alt="Format the list output" width="85%" src="assets/media/list.svg"/></div>
 

docs/note-filtering.md

@@ -106,6 +106,36 @@ Prefixing a query with `^` will match notes whose title or body start with the f
 "title: ^journal"
 ```
 
+## Filter by tags
+
+You can filter your notes by their [tags](tags.md) using `--tags` (or `-t`).
+
+Find the notes having several tags by separating them with a comma.
+
+```sh
+$ zk list --tag "history, europe"
+```
+
+To match notes having either or both tags, use a pipe `|` or `OR` (all caps).
+
+```sh
+$ zk list --tag "inbox OR todo"
+```
+
+If you want to exclude notes having a particular tag instead, prefix it with `-` or `NOT` (all caps).
+
+```sh
+$ zk list --tag "NOT done"
+```
+
+Your shell might give you some trouble using the `-` prefix. You can quote it and add an extra space as a workaround, e.g. `--tag " -done"`.
+
+Finally, you can use glob patterns to match multiple tags. This is particularly useful if you use a separator (e.g. `/`) to group multiple tags under a parent tag.
+
+```sh
+$ zk list --tag "year/201*"
+```
+
 ## Filter by creation or modification date
 
 To find notes created or modified on a specific day, use `--created <date>` and `--modified <date>`. They accept a human-friendly date for argument.

docs/tags.md

@@ -0,0 +1,14 @@
+# Tags
+
+Tags are a useful way to organize and filter your notes with `zk`, which supports most syntaxes:
+
+* `#hashtags`
+* `:colon:separated:tags:` ([opt-in](note-format.md))
+* Bear's `#multi-word tags#` ([opt-in](note-format.md))
+* YAML frontmatter (`tags` and `keywords` keys).
+
+You can filter your notes by their tags using the `--tags` option, as demonstrated in [Searching and filtering notes](note-filtering.md).
+
+```sh
+$ zk list --tag "inbox OR todo, NOT done"
+```